---
title: "Message status callback"
method: POST
path: "messageStatusCallback"
tags: ["Messages"]
---

# Message status callback

`POST messageStatusCallback` (webhook)

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

## Payload

- object — 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).
  - `id` string, uuid, required — The unique ID of the message segment.
  - `project_id` string, uuid, required — The ID of the project the message belongs to.
  - `status` 'queued' | 'initiated' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'read', required — The current delivery state of the message.
  - `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` string, date-time, required — Timestamp of the status transition.
  - `error_code` string, nullable, required — Provider-specific error code if delivery failed. Null when no error occurred.
  - `error_message` string, nullable, required — Human-readable error message if delivery failed. Null when no error occurred.
  - `custom_variables` object — 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.

## Acknowledgement `200`

Webhook received

---

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