> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# Message status callback

POST 

Payload sent by SignalWire to the `status_callback` URL each time a message transitions to a new state. The same payload shape is used for Relay SDK message callbacks, SWML `send_sms` status callbacks, and SWML messaging `reply.status_url` callbacks.

Configure `status_callback` when [sending a message](/docs/apis/rest/messages/create-message).

Status callbacks are advisory, best-effort notifications — delivery can be delayed or fail silently, so don't gate time-critical actions on receiving one. See [Status callback reliability](/docs/platform/webhooks#status-callback-reliability).

Reference: https://signalwire.com/docs/apis/rest/webhooks/message-status-callback

## Request

### Payload

- `id` (string, required) — The unique ID of the message segment.
- `project_id` (string, required) — The ID of the project the message belongs to.
- `status` (enum, required) — The current delivery state of the message.
  - Allowed values: `queued`, `initiated`, `sent`, `delivered`, `undelivered`, `failed`, `read`
- `to` (string, required) — The destination phone number.
- `from` (string, required) — The source phone number.
- `body` (string, required) — The message body text.
- `number_of_segments` (integer, required) — Number of segments the message body was split into for delivery.
- `timestamp` (datetime, required) — Timestamp of the status transition.
- `error_code` (string, required, nullable) — Provider-specific error code if delivery failed. Null when no error occurred.
- `error_message` (string, required, nullable) — Human-readable error message if delivery failed. Null when no error occurred.
- `custom_variables` (object, optional) — The same `custom_variables` key/value pairs you supplied when [sending the message](/docs/apis/rest/messages/create-message), echoed back so you can match this callback to a record in your own system. Included only when the message was sent with custom variables.