Message Events API Reference

Receive inbound messages and message status updates via webhook. See our guide for handling events with SDKs.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Represents an incoming message or message status update received via webhook.

typestring

Type of webhook event. MESSAGE.STATUS for message status updates, MESSAGE.RECEIVED for inbound messages.

Allowed values

"MESSAGE.STATUS""MESSAGE.RECEIVED"

object

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

statusstring

Current status of the message.

Allowed values

"QUEUED""PENDING""SENT""SEND_FAILED""DELIVERED""DELIVERY_FAILED""RECEIVED""READ""FALLBACK_SENT"

directionstring

Direction of the message flow.

Allowed values

"INBOUND""OUTBOUND"

segmentsinteger

Number of segments for this message.

sentAtstring

Timestamp when the message was sent in ISO 8601 format. Null if the message has not been sent yet.

deliveredAtstringOptional

Timestamp when the message was delivered in ISO 8601 format. Null if not yet delivered or for inbound messages.

7 variants

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

originalMessageIdstringOptional

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.

objectOptional

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.

Response Body

Webhook payload

JSON delivered to your webhook endpoint.

Example

{
  "type": "MESSAGE.RECEIVED",
  "conversation": {
    "id": 12345,
    "from": "+14155551234",
    "to": "+14155555678"
  },
  "status": "RECEIVED",
  "direction": "INBOUND",
  "segments": 1,
  "sentAt": "2024-01-15T09:30:00Z",
  "deliveredAt": null,
  "message": {
    "type": "SMS",
    "id": "msg_1234567890",
    "text": "Hello, I need help with my order"
  }
}

Webhook headers1

Message Events

Header Parameters

Request Body

Response Body

Try asking

Message Events

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200

Header Parameters

Request Body

Response Body