> For complete lifecycle-event payload schemas and examples, use the canonical overview: Session /api/sessions; Room lifecycle, members, and room playback /api/rooms; Session playback /api/playback; Recording /api/recording; DTMF /api/keypad-input; Messages /api/messages; WebSocket Session /api/web-socket. Use /api/event-delivery for transport behavior. Endpoint pages name relevant events, but these overviews are the canonical references.

# Message

> Complete Message resource and lifecycle-event reference for SMS sending and recipient delivery.

A `Message` represents one outbound SMS. The API tracks two independent state
dimensions:

* `sending_status` reports the latest confirmed provider sending milestone:
  `queued` or `sent`.
* `delivery_status` reports what the platform knows about recipient delivery:
  `pending`, `delivered`, `failed`, or `unknown`.

`unknown` means that monitoring ended without conclusive delivery evidence. It
does not mean that delivery failed. Provider evidence can also skip the
intermediate `sent` milestone, so do not infer delivery from `sending_status`.

Use [Get message status](/api/messages/get-message-status) to reconcile state
after a missed event. Treat the returned resource as the latest snapshot.

## Methods

* [Send an outbound message](/api/messages/create-message)
* [List messages](/api/messages/list-messages)
* [Get message status](/api/messages/get-message-status)

## Lifecycle events

Message events report provider sending milestones and the final
platform-observed recipient-delivery outcome. All events contain `aud`,
`event`, `message_uuid`, `channel: "sms"`, `direction: "outbound"`, and an RFC
3339 UTC `timestamp`.

[Send an outbound message](/api/messages/create-message) produces the Message
that these events describe.

Provider evidence can skip `message.sent`. Process each event independently and
use [`GET /v1/messages/{message_uuid}`](/api/messages/get-message-status) to
reconcile the latest state after a missed event.

## message.queued

Fires after the SMS provider positively acknowledges queueing and the platform
persists the Message. This is the provider's queue, not an internal platform
queue. The event also contains `from` and `to`.

| Field          | Type   | Description                                                            |
| -------------- | ------ | ---------------------------------------------------------------------- |
| `aud`          | string | Application UUID that identifies the intended recipient. **Required**  |
| `event`        | string | Always `"message.queued"`. **Required**                                |
| `message_uuid` | string | Stable Message identifier. **Required**                                |
| `channel`      | string | Always `"sms"`. **Required**                                           |
| `direction`    | string | Always `"outbound"`. **Required**                                      |
| `from`         | string | Authorized SMS identity presented to the recipient. **Required**       |
| `to`           | string | Destination in canonical E.164 format with a leading `+`. **Required** |
| `timestamp`    | string | RFC 3339 / ISO 8601 UTC event time with a `Z` suffix. **Required**     |

```json
{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "message.queued",
  "message_uuid": "msg_550e8400-e29b-41d4-a716-446655440000",
  "channel": "sms",
  "direction": "outbound",
  "from": "Example",
  "to": "+972500000000",
  "timestamp": "2026-08-28T12:00:00.000Z"
}
```

## message.sent

Fires only when the provider reports positive evidence that it sent the SMS
onward. A later delivery report can arrive without this intermediate event. The
event also contains `from` and `to`.

| Field          | Type   | Description                                                            |
| -------------- | ------ | ---------------------------------------------------------------------- |
| `aud`          | string | Application UUID that identifies the intended recipient. **Required**  |
| `event`        | string | Always `"message.sent"`. **Required**                                  |
| `message_uuid` | string | Stable Message identifier. **Required**                                |
| `channel`      | string | Always `"sms"`. **Required**                                           |
| `direction`    | string | Always `"outbound"`. **Required**                                      |
| `from`         | string | Authorized SMS identity presented to the recipient. **Required**       |
| `to`           | string | Destination in canonical E.164 format with a leading `+`. **Required** |
| `timestamp`    | string | RFC 3339 / ISO 8601 UTC event time with a `Z` suffix. **Required**     |

```json
{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "message.sent",
  "message_uuid": "msg_550e8400-e29b-41d4-a716-446655440000",
  "channel": "sms",
  "direction": "outbound",
  "from": "Example",
  "to": "+972500000000",
  "timestamp": "2026-08-28T12:00:02.000Z"
}
```

## message.delivery\_status

Fires when recipient delivery succeeds, fails conclusively, or remains unknown
after monitoring ends.

| Field             | Type   | Description                                                           |
| ----------------- | ------ | --------------------------------------------------------------------- |
| `aud`             | string | Application UUID that identifies the intended recipient. **Required** |
| `event`           | string | Always `"message.delivery_status"`. **Required**                      |
| `message_uuid`    | string | Stable Message identifier. **Required**                               |
| `channel`         | string | Always `"sms"`. **Required**                                          |
| `direction`       | string | Always `"outbound"`. **Required**                                     |
| `delivery_status` | string | Final status: `delivered`, `failed`, or `unknown`. **Required**       |
| `timestamp`       | string | RFC 3339 / ISO 8601 UTC event time with a `Z` suffix. **Required**    |

```json
{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "message.delivery_status",
  "message_uuid": "msg_550e8400-e29b-41d4-a716-446655440000",
  "channel": "sms",
  "direction": "outbound",
  "delivery_status": "delivered",
  "timestamp": "2026-08-28T12:00:08.000Z"
}
```

`unknown` means monitoring ended without conclusive evidence. It is terminal,
but it is not a delivery failure.

All webhook deliveries use the shared authentication, retry, deduplication, and
ordering behavior described in [Event delivery](/api/event-delivery).