# Webhooks ## `client.webhooks.events(RequestOptionsoptions?): void` **** `` ### Example ```typescript import LinqAPIV3 from '@linqapp/sdk'; const client = new LinqAPIV3({ apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted }); await client.webhooks.events(); ``` ## Domain Types ### Message Event V2 - `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: Chat` Chat information - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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 | null` Whether this is a group chat - `owner_handle?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" | "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: Array` Message parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` 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?: string | null` When the message was delivered. Null if not yet delivered. - `effect?: SchemasMessageEffect | null` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key?: string | null` Idempotency key for deduplication of outbound messages. - `preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at?: string | null` When the message was read. Null if not yet read. - `reply_to?: ReplyTo | null` Reference to the message this is replying to (for threaded replies) - `message_id?: string` ID of the message being replied to - `part_index?: number` Index of the part being replied to - `sent_at?: string | null` When the message was sent. Null if not yet sent. ### Message Payload - `MessagePayload` Message content nested within webhook events - `id?: string` Message identifier - `created_at?: string` When the message record was created - `delivered_at?: string | null` When the message was delivered - `effect?: SchemasMessageEffect` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `is_delivered?: boolean` Whether the message has been delivered - `is_read?: boolean` Whether the message has been read - `parts?: Array` Message content parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` A rich link preview part - `type: "link"` Indicates this is a rich link preview part - `"link"` - `value: string` The URL - `read_at?: string | null` When the message was read - `reply_to?: ReplyTo` Reference to the message this is replying to - `message_id?: string` The ID of the message being replied to - `part_index?: number` Index of the message part being replied to (0-based) - `sent_at?: string | null` When the message was sent - `updated_at?: string` When the message record was last updated ### Reaction Event Base - `ReactionEventBase` - `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?: string` Chat identifier (UUID) - `custom_emoji?: string | null` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from?: string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle?: 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `message_id?: string` Message identifier (UUID) that the reaction was added to or removed from - `part_index?: number` Index of the message part that was reacted to (0-based) - `reacted_at?: string` When the reaction was added or removed - `service?: ServiceType` Messaging service type - `sticker?: Sticker | null` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name?: string` Filename of the sticker - `height?: number` Sticker image height in pixels - `mime_type?: string` MIME type of the sticker image - `url?: string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width?: number` Sticker image width in pixels ### Schemas Media Part Response - `SchemasMediaPartResponse` 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` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` ### Schemas Text Part Response - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` ### Message Sent Webhook Event - `MessageSentWebhookEvent` 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: Chat` Chat information - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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 | null` Whether this is a group chat - `owner_handle?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" | "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: Array` Message parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` 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?: string | null` When the message was delivered. Null if not yet delivered. - `effect?: SchemasMessageEffect | null` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key?: string | null` Idempotency key for deduplication of outbound messages. - `preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at?: string | null` When the message was read. Null if not yet read. - `reply_to?: ReplyTo | null` Reference to the message this is replying to (for threaded replies) - `message_id?: string` ID of the message being replied to - `part_index?: number` Index of the part being replied to - `sent_at?: string | null` 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` 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: Chat` Chat information - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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 | null` Whether this is a group chat - `owner_handle?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" | "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: Array` Message parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` 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?: string | null` When the message was delivered. Null if not yet delivered. - `effect?: SchemasMessageEffect | null` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key?: string | null` Idempotency key for deduplication of outbound messages. - `preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at?: string | null` When the message was read. Null if not yet read. - `reply_to?: ReplyTo | null` Reference to the message this is replying to (for threaded replies) - `message_id?: string` ID of the message being replied to - `part_index?: number` Index of the part being replied to - `sent_at?: string | null` 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` 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: Chat` Chat information - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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 | null` Whether this is a group chat - `owner_handle?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" | "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: Array` Message parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` 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?: string | null` When the message was delivered. Null if not yet delivered. - `effect?: SchemasMessageEffect | null` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key?: string | null` Idempotency key for deduplication of outbound messages. - `preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at?: string | null` When the message was read. Null if not yet read. - `reply_to?: ReplyTo | null` Reference to the message this is replying to (for threaded replies) - `message_id?: string` ID of the message being replied to - `part_index?: number` Index of the part being replied to - `sent_at?: string | null` 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` 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: Chat` Chat information - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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 | null` Whether this is a group chat - `owner_handle?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" | "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: Array` Message parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` 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?: string | null` When the message was delivered. Null if not yet delivered. - `effect?: SchemasMessageEffect | null` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key?: string | null` Idempotency key for deduplication of outbound messages. - `preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at?: string | null` When the message was read. Null if not yet read. - `reply_to?: ReplyTo | null` Reference to the message this is replying to (for threaded replies) - `message_id?: string` ID of the message being replied to - `part_index?: number` Index of the part being replied to - `sent_at?: string | null` 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` 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: Data` 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?: string` Chat identifier (UUID) - `message_id?: string` Message identifier (UUID) - `reason?: 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` 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: Data` 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: Chat` Chat context - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "outbound" | "inbound"` "outbound" if you sent the original message, "inbound" if you received it - `"outbound"` - `"inbound"` - `edited_at: string` When the edit occurred - `part: Part` 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` 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?: string` Chat identifier (UUID) - `custom_emoji?: string | null` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from?: string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle?: 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `message_id?: string` Message identifier (UUID) that the reaction was added to or removed from - `part_index?: number` Index of the message part that was reacted to (0-based) - `reacted_at?: string` When the reaction was added or removed - `service?: ServiceType` Messaging service type - `sticker?: Sticker | null` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name?: string` Filename of the sticker - `height?: number` Sticker image height in pixels - `mime_type?: string` MIME type of the sticker image - `url?: string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width?: 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` 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?: string` Chat identifier (UUID) - `custom_emoji?: string | null` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from?: string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle?: 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `message_id?: string` Message identifier (UUID) that the reaction was added to or removed from - `part_index?: number` Index of the message part that was reacted to (0-based) - `reacted_at?: string` When the reaction was added or removed - `service?: ServiceType` Messaging service type - `sticker?: Sticker | null` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name?: string` Filename of the sticker - `height?: number` Sticker image height in pixels - `mime_type?: string` MIME type of the sticker image - `url?: string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width?: 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` 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: Data` Payload for participant.added webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant. - `added_at?: string` When the participant was added - `chat_id?: string` Chat identifier (UUID) of the group chat - `participant?: 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` 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` 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: Data` Payload for participant.removed webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant. - `chat_id?: string` Chat identifier (UUID) of the group chat - `participant?: 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `removed_at?: 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` 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: Data` 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 | null` Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats. - `handles: Array` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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?: ServiceType | null` 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` 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: Data` 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?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `new_value?: string | null` New group name (null if the name was removed) - `old_value?: string | null` 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` 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: Data` 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?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `new_value?: string | null` New icon URL (null if the icon was removed) - `old_value?: string | null` 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` 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: Data` 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` 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: Data` 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` 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: Data` 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` 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: Data` 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` 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: Data` Payload for phone_number.status_updated webhook events - `changed_at: string` When the status change occurred - `new_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"` The new line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `new_status: "ACTIVE" | "FLAGGED"` The new service status - `"ACTIVE"` - `"FLAGGED"` - `phone_number: string` Phone number in E.164 format - `previous_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"` The previous line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `previous_status: "ACTIVE" | "FLAGGED"` The previous service status - `"ACTIVE"` - `"FLAGGED"` - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: "message.sent" | "message.received" | "message.read" | 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 | MessageReceivedWebhookEvent | MessageReadWebhookEvent | 15 more` Complete webhook payload for message.sent events (2026-02-03 format) - `MessageSentWebhookEvent` 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: Chat` Chat information - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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 | null` Whether this is a group chat - `owner_handle?: ChatHandle | null` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `"active"` - `"left"` - `"removed"` - `direction: "inbound" | "outbound"` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: Array` Message parts (text and/or media) - `SchemasTextPartResponse` A text message part - `type: "text"` Indicates this is a text message part - `"text"` - `value: string` The text content - `text_decorations?: Array | null` Text decorations applied to character ranges in the value - `range: Array` 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?: "big" | "small" | "shake" | 5 more` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style?: "bold" | "italic" | "strikethrough" | "underline"` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `SchemasMediaPartResponse` 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` 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?: string | null` When the message was delivered. Null if not yet delivered. - `effect?: SchemasMessageEffect | null` iMessage effect applied to a message (screen or bubble animation) - `name?: string` Effect name (confetti, fireworks, slam, gentle, etc.) - `type?: "screen" | "bubble"` Effect category - `"screen"` - `"bubble"` - `idempotency_key?: string | null` Idempotency key for deduplication of outbound messages. - `preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at?: string | null` When the message was read. Null if not yet read. - `reply_to?: ReplyTo | null` Reference to the message this is replying to (for threaded replies) - `message_id?: string` ID of the message being replied to - `part_index?: number` Index of the part being replied to - `sent_at?: string | null` 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` 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` 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` 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` 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: Data` 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?: string` Chat identifier (UUID) - `message_id?: string` Message identifier (UUID) - `reason?: 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` 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: Data` 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: Chat` Chat context - `id: string` Chat identifier - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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" | "inbound"` "outbound" if you sent the original message, "inbound" if you received it - `"outbound"` - `"inbound"` - `edited_at: string` When the edit occurred - `part: Part` 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` 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?: string` Chat identifier (UUID) - `custom_emoji?: string | null` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from?: string` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle?: ChatHandle` The person who added/removed the reaction as a full handle object - `message_id?: string` Message identifier (UUID) that the reaction was added to or removed from - `part_index?: number` Index of the message part that was reacted to (0-based) - `reacted_at?: string` When the reaction was added or removed - `service?: ServiceType` Messaging service type - `sticker?: Sticker | null` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name?: string` Filename of the sticker - `height?: number` Sticker image height in pixels - `mime_type?: string` MIME type of the sticker image - `url?: string` Presigned URL for downloading the sticker image (expires in 1 hour). - `width?: 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` 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` 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: Data` Payload for participant.added webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant. - `added_at?: string` When the participant was added - `chat_id?: string` Chat identifier (UUID) of the group chat - `participant?: 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` 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: Data` Payload for participant.removed webhook events - `handle: string` DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant. - `chat_id?: string` Chat identifier (UUID) of the group chat - `participant?: ChatHandle` The removed participant as a full handle object - `removed_at?: 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` 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: Data` 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 | null` Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats. - `handles: Array` 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?: boolean | null` Whether this handle belongs to the sender (your phone number) - `left_at?: string | null` When they left (if applicable) - `status?: "active" | "left" | "removed" | null` Participant status - `health_status: HealthStatus` **[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" | "AT_RISK" | "CRITICAL" | "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?: ServiceType | null` 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` 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: Data` 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?: ChatHandle | null` The handle who made the change. - `new_value?: string | null` New group name (null if the name was removed) - `old_value?: string | null` 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` 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: Data` 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?: ChatHandle | null` The handle who made the change. - `new_value?: string | null` New icon URL (null if the icon was removed) - `old_value?: string | null` 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` 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: Data` 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` 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: Data` 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` 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: Data` 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` 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: Data` 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` 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: Data` Payload for phone_number.status_updated webhook events - `changed_at: string` When the status change occurred - `new_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"` The new line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `new_status: "ACTIVE" | "FLAGGED"` The new service status - `"ACTIVE"` - `"FLAGGED"` - `phone_number: string` Phone number in E.164 format - `previous_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"` The previous line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `previous_status: "ACTIVE" | "FLAGGED"` The previous service status - `"ACTIVE"` - `"FLAGGED"` - `event_id: string` Unique identifier for this event (for deduplication) - `event_type: "message.sent" | "message.received" | "message.read" | 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.