---
title: "SMS status callback"
method: POST
path: "smsStatusCallback"
tags: ["Messages"]
---

# SMS status callback

`POST smsStatusCallback` (webhook)

Payload sent by SignalWire to your SMS Status Callback URL when the status of an SMS/MMS message changes.

Configure this callback using the `StatusCallback` parameter when
[sending an outgoing message](/docs/compatibility-api/rest/messages/create-message).

There are 8 possible message statuses:

| Status | Description |
|--------|-------------|
| `queued` | The API request was processed and the message is waiting to be sent. |
| `sending` | The message is being transmitted to the nearest upstream carrier. |
| `sent` | The nearest upstream carrier has accepted the message. |
| `delivered` | The nearest upstream carrier confirmed receipt of the message. |
| `undelivered` | SignalWire received notice from the upstream carrier that the message was not delivered. |
| `failed` | SignalWire could not send the message. There is no charge for failed messages. |
| `receiving` | SignalWire has received and is currently processing an inbound message. |
| `received` | The inbound message has been received by a number in your account. |

<Note>
SignalWire only marks a message as `delivered` when it receives a Delivery Receipt (DLR)
from the receiving carrier confirming entry into the end carrier's network. `sent` means the message
left SignalWire and reached the downstream peer. Some carriers send delayed DLRs; others send none
at all. MMS messages never receive DLRs, so they will only ever reach `sent` status.
</Note>

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).

## Payload

- object — Payload sent by SignalWire to your SMS Status Callback URL when the status of an SMS/MMS message changes. Configure this callback using the `StatusCallback` parameter when [sending an outgoing message](/docs/compatibility-api/rest/messages/create-message). There are 8 possible message statuses: | Status | Description | |--------|-------------| | `queued` | The API request was processed and the message is waiting to be sent. | | `sending` | The message is being transmitted to the nearest upstream carrier. | | `sent` | The nearest upstream carrier has accepted the message. | | `delivered` | The nearest upstream carrier confirmed receipt of the message. | | `undelivered` | SignalWire received notice from the upstream carrier that the message was not delivered. | | `failed` | SignalWire could not send the message. There is no charge for failed messages. | | `receiving` | SignalWire has received and is currently processing an inbound message. | | `received` | The inbound message has been received by a number in your account. | <Note> SignalWire only marks a message as `delivered` when it receives a Delivery Receipt (DLR) from the receiving carrier confirming entry into the end carrier's network. `sent` means the message left SignalWire and reached the downstream peer. Some carriers send delayed DLRs; others send none at all. MMS messages never receive DLRs, so they will only ever reach `sent` status. </Note> 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).
  - `MessageStatus` 'queued' | 'sending' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'receiving' | 'received', required — The current status of the message at the time of the callback. One of: `queued`, `sending`, `sent`, `delivered`, `undelivered`, `failed`, `receiving`, `received`.
  - `ErrorCode` string — If the message has failed or is undelivered, the error code may provide more information about what went wrong.
  - `MessageSid` string, required — The unique ID of this message.
  - `AccountSid` string, required — The unique ID of the project this message is associated with.
  - `From` string, required — The From number of the message.
  - `To` string, required — The To number of the message.
  - `Body` string, required — The body of the message.
  - `NumMedia` integer, required — The number of media files that were included with the message.
  - `NumSegments` integer, required — The number of segments that make up the entire message. If the body exceeds 160 GSM-7 characters or 70 UCS-2 characters, it is automatically split into smaller segments that are annotated for reconstruction on the recipient handset.

## Acknowledgement `200`

Webhook received

---

[API](https://skmtc.net/signalwire/apis/compatibility-api.md) · [All operations](https://skmtc.net/signalwire/apis/compatibility-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signalwire/compatibility-api/revisions/e6faba43acd7/schema)