# Webhooks ## **** `` ## Domain Types ### Message Event V2 - `MessageEventV2 object { id, chat, direction, 10 more }` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat information - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: optional boolean` Whether this is a group chat - `owner_handle: optional ChatHandle` Your phone number's handle. Always has is_me=true. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" or "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `Link object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: optional string` When the message was delivered. Null if not yet delivered. - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key: optional string` Idempotency key for deduplication of outbound messages. - `preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: optional string` When the message was read. Null if not yet read. - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to (for threaded replies) - `message_id: optional string` ID of the message being replied to - `part_index: optional number` Index of the part being replied to - `sent_at: optional string` When the message was sent. Null if not yet sent. ### Message Payload - `MessagePayload object { id, created_at, delivered_at, 8 more }` Message content nested within webhook events - `id: optional string` Message identifier - `created_at: optional string` When the message record was created - `delivered_at: optional string` When the message was delivered - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `is_delivered: optional boolean` Whether the message has been delivered - `is_read: optional boolean` Whether the message has been read - `parts: optional array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message content parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `SchemasLinkPartResponse object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `read_at: optional string` When the message was read - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to - `message_id: optional string` The ID of the message being replied to - `part_index: optional number` Index of the message part being replied to (0-based) - `sent_at: optional string` When the message was sent - `updated_at: optional string` When the message record was last updated ### Reaction Event Base - `ReactionEventBase object { is_from_me, reaction_type, chat_id, 8 more }` - `is_from_me: boolean` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: optional string` Chat identifier (UUID) - `custom_emoji: optional string` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from: optional string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: optional ChatHandle` The person who added/removed the reaction as a full handle object - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `message_id: optional string` Message identifier (UUID) that the reaction was added to or removed from - `part_index: optional number` Index of the message part that was reacted to (0-based) - `reacted_at: optional string` When the reaction was added or removed - `service: optional ServiceType` Messaging service type - `sticker: optional object { file_name, height, mime_type, 2 more }` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: optional string` Filename of the sticker - `height: optional number` Sticker image height in pixels - `mime_type: optional string` MIME type of the sticker image - `url: optional string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: optional number` Sticker image width in pixels ### Schemas Media Part Response - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). ### Schemas Message Effect - `SchemasMessageEffect object { name, type }` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` ### Schemas Text Part Response - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` ### Message Sent Webhook Event - `MessageSentWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.sent events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat information - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: optional boolean` Whether this is a group chat - `owner_handle: optional ChatHandle` Your phone number's handle. Always has is_me=true. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" or "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `Link object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: optional string` When the message was delivered. Null if not yet delivered. - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key: optional string` Idempotency key for deduplication of outbound messages. - `preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: optional string` When the message was read. Null if not yet read. - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to (for threaded replies) - `message_id: optional string` ID of the message being replied to - `part_index: optional number` Index of the part being replied to - `sent_at: optional string` When the message was sent. Null if not yet sent. - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Message Received Webhook Event - `MessageReceivedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.received events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat information - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: optional boolean` Whether this is a group chat - `owner_handle: optional ChatHandle` Your phone number's handle. Always has is_me=true. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" or "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `Link object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: optional string` When the message was delivered. Null if not yet delivered. - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key: optional string` Idempotency key for deduplication of outbound messages. - `preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: optional string` When the message was read. Null if not yet read. - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to (for threaded replies) - `message_id: optional string` ID of the message being replied to - `part_index: optional number` Index of the part being replied to - `sent_at: optional string` When the message was sent. Null if not yet sent. - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Message Read Webhook Event - `MessageReadWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.read events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat information - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: optional boolean` Whether this is a group chat - `owner_handle: optional ChatHandle` Your phone number's handle. Always has is_me=true. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" or "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `Link object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: optional string` When the message was delivered. Null if not yet delivered. - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key: optional string` Idempotency key for deduplication of outbound messages. - `preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: optional string` When the message was read. Null if not yet read. - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to (for threaded replies) - `message_id: optional string` ID of the message being replied to - `part_index: optional number` Index of the part being replied to - `sent_at: optional string` When the message was sent. Null if not yet sent. - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Message Delivered Webhook Event - `MessageDeliveredWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.delivered events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat information - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: optional boolean` Whether this is a group chat - `owner_handle: optional ChatHandle` Your phone number's handle. Always has is_me=true. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" or "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `Link object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: optional string` When the message was delivered. Null if not yet delivered. - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key: optional string` Idempotency key for deduplication of outbound messages. - `preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: optional string` When the message was read. Null if not yet read. - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to (for threaded replies) - `message_id: optional string` ID of the message being replied to - `part_index: optional number` Index of the part being replied to - `sent_at: optional string` When the message was sent. Null if not yet sent. - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Message Failed Webhook Event - `MessageFailedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.failed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { code, failed_at, chat_id, 2 more }` Error details for message.failed webhook events. See [WebhookErrorCode](#/components/schemas/WebhookErrorCode) for the full error code reference. - `code: number` Error codes in webhook failure events (3007, 4001). - `failed_at: string` When the failure was detected - `chat_id: optional string` Chat identifier (UUID) - `message_id: optional string` Message identifier (UUID) - `reason: optional string` Human-readable description of the failure - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Message Edited Webhook Event - `MessageEditedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.edited events (2026-02-03 format only) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { id, chat, direction, 3 more }` Payload for `message.edited` events (2026-02-03 format). Describes which part of a message was edited and when. Only text parts can be edited. Only available for subscriptions using `webhook_version: "2026-02-03"`. - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat context - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: boolean` Whether this is a group chat - `owner_handle: ChatHandle` The handle that owns this chat (your phone number) - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "outbound" or "inbound"` "outbound" if you sent the original message, "inbound" if you received it - `"outbound"` - `"inbound"` - `edited_at: string` When the edit occurred - `part: object { index, text }` The edited part - `index: number` Zero-based index of the edited part within the message - `text: string` New text content of the part - `sender_handle: ChatHandle` The handle that sent (and edited) this message - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Reaction Added Webhook Event - `ReactionAddedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for reaction.added events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: ReactionEventBase` Payload for reaction.added webhook events - `is_from_me: boolean` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: optional string` Chat identifier (UUID) - `custom_emoji: optional string` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from: optional string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: optional ChatHandle` The person who added/removed the reaction as a full handle object - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `message_id: optional string` Message identifier (UUID) that the reaction was added to or removed from - `part_index: optional number` Index of the message part that was reacted to (0-based) - `reacted_at: optional string` When the reaction was added or removed - `service: optional ServiceType` Messaging service type - `sticker: optional object { file_name, height, mime_type, 2 more }` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: optional string` Filename of the sticker - `height: optional number` Sticker image height in pixels - `mime_type: optional string` MIME type of the sticker image - `url: optional string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: optional number` Sticker image width in pixels - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Reaction Removed Webhook Event - `ReactionRemovedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for reaction.removed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: ReactionEventBase` Payload for reaction.removed webhook events - `is_from_me: boolean` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: optional string` Chat identifier (UUID) - `custom_emoji: optional string` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from: optional string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: optional ChatHandle` The person who added/removed the reaction as a full handle object - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `message_id: optional string` Message identifier (UUID) that the reaction was added to or removed from - `part_index: optional number` Index of the message part that was reacted to (0-based) - `reacted_at: optional string` When the reaction was added or removed - `service: optional ServiceType` Messaging service type - `sticker: optional object { file_name, height, mime_type, 2 more }` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: optional string` Filename of the sticker - `height: optional number` Sticker image height in pixels - `mime_type: optional string` MIME type of the sticker image - `url: optional string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: optional number` Sticker image width in pixels - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Participant Added Webhook Event - `ParticipantAddedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for participant.added events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { handle, added_at, chat_id, participant }` Payload for participant.added webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant. - `added_at: optional string` When the participant was added - `chat_id: optional string` Chat identifier (UUID) of the group chat - `participant: optional ChatHandle` The added participant as a full handle object - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Participant Removed Webhook Event - `ParticipantRemovedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for participant.removed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { handle, chat_id, participant, removed_at }` Payload for participant.removed webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant. - `chat_id: optional string` Chat identifier (UUID) of the group chat - `participant: optional ChatHandle` The removed participant as a full handle object - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `removed_at: optional string` When the participant was removed - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Created Webhook Event - `ChatCreatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.created events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { id, created_at, display_name, 5 more }` Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response. - `id: string` Unique identifier for the chat - `created_at: string` When the chat was created - `display_name: string` Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats. - `handles: array of ChatHandle` List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant). - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: boolean` Whether this is a group chat - `updated_at: string` When the chat was last updated - `service: optional ServiceType` Messaging service type - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Group Name Updated Webhook Event - `ChatGroupNameUpdatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_name_updated events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, updated_at, changed_by_handle, 2 more }` Payload for chat.group_name_updated webhook events - `chat_id: string` Chat identifier (UUID) of the group chat - `updated_at: string` When the update occurred - `changed_by_handle: optional ChatHandle` The handle who made the change. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `new_value: optional string` New group name (null if the name was removed) - `old_value: optional string` Previous group name (null if no previous name) - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Group Icon Updated Webhook Event - `ChatGroupIconUpdatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_icon_updated events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, updated_at, changed_by_handle, 2 more }` Payload for chat.group_icon_updated webhook events - `chat_id: string` Chat identifier (UUID) of the group chat - `updated_at: string` When the update occurred - `changed_by_handle: optional ChatHandle` The handle who made the change. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `new_value: optional string` New icon URL (null if the icon was removed) - `old_value: optional string` Previous icon URL (null if no previous icon) - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Group Name Update Failed Webhook Event - `ChatGroupNameUpdateFailedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_name_update_failed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, error_code, failed_at }` Error details for chat.group_name_update_failed webhook events. See [WebhookErrorCode](#/components/schemas/WebhookErrorCode) for the full error code reference. - `chat_id: string` Chat identifier (UUID) of the group chat - `error_code: number` Error codes in webhook failure events (3007, 4001). - `failed_at: string` When the failure was detected - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Group Icon Update Failed Webhook Event - `ChatGroupIconUpdateFailedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_icon_update_failed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, error_code, failed_at }` Error details for chat.group_icon_update_failed webhook events. See [WebhookErrorCode](#/components/schemas/WebhookErrorCode) for the full error code reference. - `chat_id: string` Chat identifier (UUID) of the group chat - `error_code: number` Error codes in webhook failure events (3007, 4001). - `failed_at: string` When the failure was detected - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Typing Indicator Started Webhook Event - `ChatTypingIndicatorStartedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.typing_indicator.started events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id }` Payload for chat.typing_indicator.started webhook events - `chat_id: string` Chat identifier - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Chat Typing Indicator Stopped Webhook Event - `ChatTypingIndicatorStoppedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.typing_indicator.stopped events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id }` Payload for chat.typing_indicator.stopped webhook events - `chat_id: string` Chat identifier - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Phone Number Status Updated Webhook Event - `PhoneNumberStatusUpdatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for phone_number.status_updated events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { changed_at, new_health_status, new_status, 3 more }` Payload for phone_number.status_updated webhook events - `changed_at: string` When the status change occurred - `new_health_status: "HEALTHY" or "AT_RISK" or "CRITICAL"` The new line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `new_status: "ACTIVE" or "FLAGGED"` The new service status - `"ACTIVE"` - `"FLAGGED"` - `phone_number: string` Phone number in E.164 format - `previous_health_status: "HEALTHY" or "AT_RISK" or "CRITICAL"` The previous line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `previous_status: "ACTIVE" or "FLAGGED"` The previous service status - `"ACTIVE"` - `"FLAGGED"` - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: "message.sent" or "message.received" or "message.read" or 22 more` The type of event - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. ### Events Webhook Event - `EventsWebhookEvent = MessageSentWebhookEvent or MessageReceivedWebhookEvent or MessageReadWebhookEvent or 15 more` Complete webhook payload for message.sent events (2026-02-03 format) - `MessageSentWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.sent events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat information - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: optional boolean` Whether this is a group chat - `owner_handle: optional ChatHandle` Your phone number's handle. Always has is_me=true. - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" or "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: array of SchemasTextPartResponse or SchemasMediaPartResponse or object { type, value }` Message parts (text and/or media) - `SchemasTextPartResponse object { type, value, text_decorations }` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations: optional array of TextDecoration` Text decorations applied to character ranges in the value - `range: array of number` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: optional "big" or "small" or "shake" or 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: optional "bold" or "italic" or "strikethrough" or "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse object { id, filename, mime_type, 3 more }` A media attachment part - `id: string` Unique attachment identifier - `filename: string` Original filename - `mime_type: string` MIME type of the file - `size_bytes: number` File size in bytes - `type: "media"` Indicates this is a media attachment part - `"media"` - `url: string` Presigned URL for downloading the attachment (expires in 1 hour). - `Link object { type, value }` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: optional string` When the message was delivered. Null if not yet delivered. - `effect: optional SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name: optional string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: optional "screen" or "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key: optional string` Idempotency key for deduplication of outbound messages. - `preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: optional string` When the message was read. Null if not yet read. - `reply_to: optional object { message_id, part_index }` Reference to the message this is replying to (for threaded replies) - `message_id: optional string` ID of the message being replied to - `part_index: optional number` Index of the part being replied to - `sent_at: optional string` When the message was sent. Null if not yet sent. - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `MessageReceivedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.received events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `MessageReadWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.read events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `MessageDeliveredWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.delivered events (2026-02-03 format) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: MessageEventV2` Unified payload for message webhooks when using `webhook_version: "2026-02-03"`. This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes `?version=2026-02-03`. Key differences from V1 (2025-01-01): - `direction`: "inbound" or "outbound" instead of `is_from_me` boolean - `sender_handle`: Full handle object for the sender - `chat`: Nested object with `id`, `is_group`, and `owner_handle` - Message fields (`id`, `parts`, `effect`, etc.) are at the top level, not nested in `message` Timestamps indicate the message state: - `message.sent`: sent_at set, delivered_at=null, read_at=null - `message.received`: sent_at set, delivered_at=null, read_at=null - `message.delivered`: sent_at set, delivered_at set, read_at=null - `message.read`: sent_at set, delivered_at set, read_at set - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `MessageFailedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.failed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { code, failed_at, chat_id, 2 more }` Error details for message.failed webhook events. See [WebhookErrorCode](#/components/schemas/WebhookErrorCode) for the full error code reference. - `code: number` Error codes in webhook failure events (3007, 4001). - `failed_at: string` When the failure was detected - `chat_id: optional string` Chat identifier (UUID) - `message_id: optional string` Message identifier (UUID) - `reason: optional string` Human-readable description of the failure - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `MessageEditedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for message.edited events (2026-02-03 format only) - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { id, chat, direction, 3 more }` Payload for `message.edited` events (2026-02-03 format). Describes which part of a message was edited and when. Only text parts can be edited. Only available for subscriptions using `webhook_version: "2026-02-03"`. - `id: string` Message identifier - `chat: object { id, health_status, is_group, owner_handle }` Chat context - `id: string` Chat identifier - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: boolean` Whether this is a group chat - `owner_handle: ChatHandle` The handle that owns this chat (your phone number) - `direction: "outbound" or "inbound"` "outbound" if you sent the original message, "inbound" if you received it - `"outbound"` - `"inbound"` - `edited_at: string` When the edit occurred - `part: object { index, text }` The edited part - `index: number` Zero-based index of the edited part within the message - `text: string` New text content of the part - `sender_handle: ChatHandle` The handle that sent (and edited) this message - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ReactionAddedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for reaction.added events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: ReactionEventBase` Payload for reaction.added webhook events - `is_from_me: boolean` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: optional string` Chat identifier (UUID) - `custom_emoji: optional string` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from: optional string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: optional ChatHandle` The person who added/removed the reaction as a full handle object - `message_id: optional string` Message identifier (UUID) that the reaction was added to or removed from - `part_index: optional number` Index of the message part that was reacted to (0-based) - `reacted_at: optional string` When the reaction was added or removed - `service: optional ServiceType` Messaging service type - `sticker: optional object { file_name, height, mime_type, 2 more }` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: optional string` Filename of the sticker - `height: optional number` Sticker image height in pixels - `mime_type: optional string` MIME type of the sticker image - `url: optional string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: optional number` Sticker image width in pixels - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ReactionRemovedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for reaction.removed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: ReactionEventBase` Payload for reaction.removed webhook events - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ParticipantAddedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for participant.added events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { handle, added_at, chat_id, participant }` Payload for participant.added webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant. - `added_at: optional string` When the participant was added - `chat_id: optional string` Chat identifier (UUID) of the group chat - `participant: optional ChatHandle` The added participant as a full handle object - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ParticipantRemovedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for participant.removed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { handle, chat_id, participant, removed_at }` Payload for participant.removed webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant. - `chat_id: optional string` Chat identifier (UUID) of the group chat - `participant: optional ChatHandle` The removed participant as a full handle object - `removed_at: optional string` When the participant was removed - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatCreatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.created events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { id, created_at, display_name, 5 more }` Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response. - `id: string` Unique identifier for the chat - `created_at: string` When the chat was created - `display_name: string` Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats. - `handles: array of ChatHandle` List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant). - `id: string` Unique identifier for this handle - `handle: string` Phone number (E.164) or email address of the participant - `joined_at: string` When this participant joined the chat - `service: ServiceType` Messaging service type - `is_me: optional boolean` Whether this handle belongs to the sender (your phone number) - `left_at: optional string` When they left (if applicable) - `status: optional "active" or "left" or "removed"` Participant status - `health_status: object { doc_url, status, updated_at }` **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY` and may shift based on engagement and delivery signals on the conversation. Many `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line flagging. Switch on `status` to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a `doc_url` that deep-links to the relevant section of the Chat Health guide. See the [Chat Health guide](/guides/chats/chat-health) for what each status means and how to react. - `doc_url: string` Deep-link to the relevant section of the Chat Health guide for this status. - `status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"` Current health bucket for the chat. See the [Chat Health guide](/guides/chats/chat-health) for what each value means and how to react. `doc_url` deep-links to the relevant section. - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `"OPTED_OUT"` - `updated_at: string` When this status last changed. - `is_group: boolean` Whether this is a group chat - `updated_at: string` When the chat was last updated - `service: optional ServiceType` Messaging service type - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatGroupNameUpdatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_name_updated events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, updated_at, changed_by_handle, 2 more }` Payload for chat.group_name_updated webhook events - `chat_id: string` Chat identifier (UUID) of the group chat - `updated_at: string` When the update occurred - `changed_by_handle: optional ChatHandle` The handle who made the change. - `new_value: optional string` New group name (null if the name was removed) - `old_value: optional string` Previous group name (null if no previous name) - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatGroupIconUpdatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_icon_updated events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, updated_at, changed_by_handle, 2 more }` Payload for chat.group_icon_updated webhook events - `chat_id: string` Chat identifier (UUID) of the group chat - `updated_at: string` When the update occurred - `changed_by_handle: optional ChatHandle` The handle who made the change. - `new_value: optional string` New icon URL (null if the icon was removed) - `old_value: optional string` Previous icon URL (null if no previous icon) - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatGroupNameUpdateFailedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_name_update_failed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, error_code, failed_at }` Error details for chat.group_name_update_failed webhook events. See [WebhookErrorCode](#/components/schemas/WebhookErrorCode) for the full error code reference. - `chat_id: string` Chat identifier (UUID) of the group chat - `error_code: number` Error codes in webhook failure events (3007, 4001). - `failed_at: string` When the failure was detected - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatGroupIconUpdateFailedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.group_icon_update_failed events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id, error_code, failed_at }` Error details for chat.group_icon_update_failed webhook events. See [WebhookErrorCode](#/components/schemas/WebhookErrorCode) for the full error code reference. - `chat_id: string` Chat identifier (UUID) of the group chat - `error_code: number` Error codes in webhook failure events (3007, 4001). - `failed_at: string` When the failure was detected - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatTypingIndicatorStartedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.typing_indicator.started events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id }` Payload for chat.typing_indicator.started webhook events - `chat_id: string` Chat identifier - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `ChatTypingIndicatorStoppedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for chat.typing_indicator.stopped events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { chat_id }` Payload for chat.typing_indicator.stopped webhook events - `chat_id: string` Chat identifier - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: WebhookEventType` Valid webhook event types that can be subscribed to. **Note:** `message.edited` is only delivered to subscriptions using `webhook_version: "2026-02-03"`. Subscribing to this event on a v2025 subscription will not produce any deliveries. - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date. - `PhoneNumberStatusUpdatedWebhookEvent object { api_version, created_at, data, 5 more }` Complete webhook payload for phone_number.status_updated events - `api_version: string` API version for the webhook payload format - `created_at: string` When the event was created - `data: object { changed_at, new_health_status, new_status, 3 more }` Payload for phone_number.status_updated webhook events - `changed_at: string` When the status change occurred - `new_health_status: "HEALTHY" or "AT_RISK" or "CRITICAL"` The new line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `new_status: "ACTIVE" or "FLAGGED"` The new service status - `"ACTIVE"` - `"FLAGGED"` - `phone_number: string` Phone number in E.164 format - `previous_health_status: "HEALTHY" or "AT_RISK" or "CRITICAL"` The previous line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `previous_status: "ACTIVE" or "FLAGGED"` The previous service status - `"ACTIVE"` - `"FLAGGED"` - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: "message.sent" or "message.received" or "message.read" or 22 more` The type of event - `"message.sent"` - `"message.received"` - `"message.read"` - `"message.delivered"` - `"message.failed"` - `"message.edited"` - `"reaction.added"` - `"reaction.removed"` - `"participant.added"` - `"participant.removed"` - `"chat.created"` - `"chat.group_name_updated"` - `"chat.group_icon_updated"` - `"chat.group_name_update_failed"` - `"chat.group_icon_update_failed"` - `"chat.typing_indicator.started"` - `"chat.typing_indicator.stopped"` - `"phone_number.status_updated"` - `"call.initiated"` - `"call.ringing"` - `"call.answered"` - `"call.ended"` - `"call.failed"` - `"call.declined"` - `"call.no_answer"` - `partner_id: string` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: string` Trace ID for debugging and correlation across systems. - `webhook_version: string` Date-based webhook payload version. Determined by the `?version=` query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.