> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Message Events

POST 

Receive inbound messages and message status updates via webhook. See our [guide](/guides/messages/receiving) for handling events with SDKs.

Reference: https://docs.pinnacle.sh/webhooks/message-events

## Request

### Headers

- `PINNACLE-SIGNING-SECRET` (string, required) — Secret for verifying the authenticity of the request. Starts with `pss-` and is unique for each webhook. Find it at [webhooks](https://app.pinnacle.sh/dashboard/development/webhooks).

### Payload

- `type` (enum, required) — Type of webhook event. `MESSAGE.STATUS` for message status updates, `MESSAGE.RECEIVED` for inbound messages.
  - Allowed values: `MESSAGE.STATUS`, `MESSAGE.RECEIVED`
- `conversation` (MessageEventConversation, required) — Conversation metadata containing the conversation ID, sender, and recipient information.
- `status` (enum, required) — Current status of the message.
  - Allowed values: `QUEUED`, `PENDING`, `SENT`, `SEND_FAILED`, `DELIVERED`, `DELIVERY_FAILED`, `RECEIVED`, `READ`, `FALLBACK_SENT`
- `direction` (enum, required) — Direction of the message flow.
  - Allowed values: `INBOUND`, `OUTBOUND`
- `segments` (integer, required) — Number of segments for this message.
- `sentAt` (string, required, nullable) — Timestamp when the message was sent in ISO 8601 format. Null if the message has not been sent yet.
- `message` (MessageEventContent, required) — Content of an incoming or outgoing message. Discriminated by the `type` field.
- `deliveredAt` (string, optional, nullable) — Timestamp when the message was delivered in ISO 8601 format. Null if not yet delivered or for inbound messages.
- `originalMessageId` (string, optional, nullable) — The unique identifier of the original RCS message that this fallback SMS/MMS was sent on behalf of. Always begins with the prefix `msg_`. Only present on webhook events for fallback SMS/MMS messages. Use this to link the fallback back to the RCS message that could not be delivered. The `message.id` field on this event refers to the actual SMS/MMS that was sent — `originalMessageId` refers to the RCS message it replaced. Null when the message is not a fallback.
- `fallbackMessage` (MessageEventFallbackMessage, optional, nullable) — Details of the fallback SMS/MMS message(s) that were actually sent to the recipient instead of the original RCS message. Only present when the message `status` is `FALLBACK_SENT`. The `message.id` on this event refers to the original RCS message that could not be delivered. The `fallbackMessage.ids` contain the identifiers of the actual SMS/MMS messages that were sent.

## Types

### MessageEventConversation

Conversation metadata containing the conversation ID, sender, and recipient information.

- `id` (string, required) — Unique identifier for the conversation. This identifier is a string that always begins with the prefix `conv_`, for example: `conv_1234567890`.  To get more conversation details, use the [POST /conversations/get](/api-reference/conversations/get) endpoint.
- `from` (string, required) — Sender's phone number or agent ID.
- `to` (string, required) — Recipient's phone number.

### MessageEventContent

Content of an incoming or outgoing message. Discriminated by the `type` field.

### MessageEventFallbackMessage

Details of the fallback SMS/MMS message(s) that were actually sent to the recipient instead of the original RCS message. Only present when the message `status` is `FALLBACK_SENT`. The `message.id` on this event refers to the original RCS message that could not be delivered. The `fallbackMessage.ids` contain the identifiers of the actual SMS/MMS messages that were sent.

- `ids` (list of string, required) — Unique identifiers of the actual SMS/MMS message(s) that were sent as the fallback. Each identifier always begins with the prefix `msg_`. Multiple IDs indicate the fallback was split into multiple SMS/MMS messages.  These are the messages that were actually delivered to the recipient. To get their full details, use the [GET /messages/\{id}](/api-reference/messages/get) endpoint.
- `type` (enum, required) — Delivery protocol of the fallback message that was sent.
  - Allowed values: `SMS`, `MMS`
- `from` (string, required) — Phone number the fallback message was sent from in E.164 format.
- `to` (string, required) — Recipient's phone number in E.164 format.
- `text` (string, optional) — Text content of the fallback message.
- `mediaUrls` (list of string, optional) — Media URLs included in the fallback MMS message. Empty array for SMS fallbacks.