> For complete lifecycle-event payload schemas and examples, use the canonical overview: Session /api/sessions; Room lifecycle, participants, 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 outbound SMS.

A `Message` represents one outbound SMS. The API tracks sending progress
separately from delivery:

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

`queued` means that the SMS provider accepted the message into its queue.

After the provider switch described in the [API changelog](/api-changelog),
newly accepted messages stay `queued/pending` until delivery monitoring closes
as `unknown` after 72 hours. Confirmed sending and delivery reports require
further integration work. Handle `unknown` explicitly and do not resend an SMS
automatically because delivery is unconfirmed.

Sending and delivery evidence can arrive independently. A delivery report can
skip the intermediate `sent` milestone, so do not infer delivery
from `sending_status`. `unknown` means that monitoring ended without conclusive
delivery evidence. It does not mean that delivery failed.

Use [Get message status](/api/messages/get-message-status) to retrieve the
latest snapshot after a missed event.

## Methods

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

## List messages

[List messages](/api/messages/list-messages) returns retained SMS messages,
newest first.

## Lifecycle events

The `202 Accepted` response confirms acceptance and includes `message_uuid`
and `sending_status: "queued"`. Acceptance does not emit a webhook.

Message events report subsequent sending milestones and final observed
delivery outcomes. Every event contains `aud`, `event`, `message_uuid`, `channel`,
`direction: "outbound"`, and an RFC 3339 UTC `timestamp`.

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

Fires when the provider reports onward submission. 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. **Required**                                 |
| `to`           | string | Destination in canonical E.164 format. **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 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 | `delivered`, `failed`, or `unknown`. **Required**                     |
| `timestamp`       | string | RFC 3339 / ISO 8601 UTC event time with a `Z` suffix. **Required**    |

An SMS delivery event has this shape:

```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 that the 72-hour monitoring window ended without conclusive
evidence. It is terminal for platform monitoring and does not mean delivery
failed.

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

> Build reliable calling experiences with Vorbal APIs for calls, media, messaging, and webhooks.


## API Docs

- Messages [List messages](https://docs.vorbal.dev/api/messages/list-messages.md)
- Messages [Send an outbound SMS message](https://docs.vorbal.dev/api/messages/create-message.md)
- Messages [Get SMS message status](https://docs.vorbal.dev/api/messages/get-message-status.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.vorbal.dev/openapi.json)
- [OpenAPI YAML](https://docs.vorbal.dev/openapi.yaml)