# Webhooks ## `webhooks.events()` **** `` ### Example ```python import os from linq import LinqAPIV3 client = LinqAPIV3( api_key=os.environ.get("LINQ_API_V3_API_KEY"), # This is the default and can be omitted ) client.webhooks.events() ``` ## Domain Types ### Message Event V2 - `class 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: str` Message identifier - `chat: Chat` Chat information - `id: str` Chat identifier - `health_status: ChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: Optional[bool]` Whether this is a group chat - `owner_handle: Optional[ChatHandle]` Your phone number's handle. Always has is_me=true. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["inbound", "outbound"]` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: List[Part]` Message parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: Optional[datetime]` When the message was delivered. Null if not yet delivered. - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `idempotency_key: Optional[str]` Idempotency key for deduplication of outbound messages. - `preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: Optional[datetime]` When the message was read. Null if not yet read. - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to (for threaded replies) - `message_id: Optional[str]` ID of the message being replied to - `part_index: Optional[int]` Index of the part being replied to - `sent_at: Optional[datetime]` When the message was sent. Null if not yet sent. ### Message Payload - `class MessagePayload: …` Message content nested within webhook events - `id: Optional[str]` Message identifier - `created_at: Optional[datetime]` When the message record was created - `delivered_at: Optional[datetime]` When the message was delivered - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `is_delivered: Optional[bool]` Whether the message has been delivered - `is_read: Optional[bool]` Whether the message has been read - `parts: Optional[List[Part]]` Message content parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `read_at: Optional[datetime]` When the message was read - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to - `message_id: Optional[str]` The ID of the message being replied to - `part_index: Optional[int]` Index of the message part being replied to (0-based) - `sent_at: Optional[datetime]` When the message was sent - `updated_at: Optional[datetime]` When the message record was last updated ### Reaction Event Base - `class ReactionEventBase: …` - `is_from_me: bool` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: Optional[str]` Chat identifier (UUID) - `custom_emoji: Optional[str]` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from_: Optional[str]` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: Optional[ChatHandle]` The person who added/removed the reaction as a full handle object - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `message_id: Optional[str]` Message identifier (UUID) that the reaction was added to or removed from - `part_index: Optional[int]` Index of the message part that was reacted to (0-based) - `reacted_at: Optional[datetime]` When the reaction was added or removed - `service: Optional[ServiceType]` Messaging service type - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels ### Schemas Media Part Response - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). ### Schemas Message Effect - `class SchemasMessageEffect: …` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` ### Schemas Text Part Response - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` ### Message Sent Webhook Event - `class MessageSentWebhookEvent: …` Complete webhook payload for message.sent events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: Chat` Chat information - `id: str` Chat identifier - `health_status: ChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: Optional[bool]` Whether this is a group chat - `owner_handle: Optional[ChatHandle]` Your phone number's handle. Always has is_me=true. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["inbound", "outbound"]` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: List[Part]` Message parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: Optional[datetime]` When the message was delivered. Null if not yet delivered. - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `idempotency_key: Optional[str]` Idempotency key for deduplication of outbound messages. - `preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: Optional[datetime]` When the message was read. Null if not yet read. - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to (for threaded replies) - `message_id: Optional[str]` ID of the message being replied to - `part_index: Optional[int]` Index of the part being replied to - `sent_at: Optional[datetime]` When the message was sent. Null if not yet sent. - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class MessageReceivedWebhookEvent: …` Complete webhook payload for message.received events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: Chat` Chat information - `id: str` Chat identifier - `health_status: ChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: Optional[bool]` Whether this is a group chat - `owner_handle: Optional[ChatHandle]` Your phone number's handle. Always has is_me=true. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["inbound", "outbound"]` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: List[Part]` Message parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: Optional[datetime]` When the message was delivered. Null if not yet delivered. - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `idempotency_key: Optional[str]` Idempotency key for deduplication of outbound messages. - `preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: Optional[datetime]` When the message was read. Null if not yet read. - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to (for threaded replies) - `message_id: Optional[str]` ID of the message being replied to - `part_index: Optional[int]` Index of the part being replied to - `sent_at: Optional[datetime]` When the message was sent. Null if not yet sent. - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class MessageReadWebhookEvent: …` Complete webhook payload for message.read events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: Chat` Chat information - `id: str` Chat identifier - `health_status: ChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: Optional[bool]` Whether this is a group chat - `owner_handle: Optional[ChatHandle]` Your phone number's handle. Always has is_me=true. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["inbound", "outbound"]` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: List[Part]` Message parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: Optional[datetime]` When the message was delivered. Null if not yet delivered. - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `idempotency_key: Optional[str]` Idempotency key for deduplication of outbound messages. - `preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: Optional[datetime]` When the message was read. Null if not yet read. - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to (for threaded replies) - `message_id: Optional[str]` ID of the message being replied to - `part_index: Optional[int]` Index of the part being replied to - `sent_at: Optional[datetime]` When the message was sent. Null if not yet sent. - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class MessageDeliveredWebhookEvent: …` Complete webhook payload for message.delivered events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: Chat` Chat information - `id: str` Chat identifier - `health_status: ChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: Optional[bool]` Whether this is a group chat - `owner_handle: Optional[ChatHandle]` Your phone number's handle. Always has is_me=true. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["inbound", "outbound"]` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: List[Part]` Message parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: Optional[datetime]` When the message was delivered. Null if not yet delivered. - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `idempotency_key: Optional[str]` Idempotency key for deduplication of outbound messages. - `preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: Optional[datetime]` When the message was read. Null if not yet read. - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to (for threaded replies) - `message_id: Optional[str]` ID of the message being replied to - `part_index: Optional[int]` Index of the part being replied to - `sent_at: Optional[datetime]` When the message was sent. Null if not yet sent. - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class MessageFailedWebhookEvent: …` Complete webhook payload for message.failed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: int` Error codes in webhook failure events (3007, 4001). - `failed_at: datetime` When the failure was detected - `chat_id: Optional[str]` Chat identifier (UUID) - `message_id: Optional[str]` Message identifier (UUID) - `reason: Optional[str]` Human-readable description of the failure - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class MessageEditedWebhookEvent: …` Complete webhook payload for message.edited events (2026-02-03 format only) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: DataChat` Chat context - `id: str` Chat identifier - `health_status: DataChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: bool` Whether this is a group chat - `owner_handle: ChatHandle` The handle that owns this chat (your phone number) - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["outbound", "inbound"]` "outbound" if you sent the original message, "inbound" if you received it - `"outbound"` - `"inbound"` - `edited_at: datetime` When the edit occurred - `part: DataPart` The edited part - `index: int` Zero-based index of the edited part within the message - `text: str` New text content of the part - `sender_handle: ChatHandle` The handle that sent (and edited) this message - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ReactionAddedWebhookEvent: …` Complete webhook payload for reaction.added events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: ReactionEventBase` Payload for reaction.added webhook events - `is_from_me: bool` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: Optional[str]` Chat identifier (UUID) - `custom_emoji: Optional[str]` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from_: Optional[str]` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: Optional[ChatHandle]` The person who added/removed the reaction as a full handle object - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `message_id: Optional[str]` Message identifier (UUID) that the reaction was added to or removed from - `part_index: Optional[int]` Index of the message part that was reacted to (0-based) - `reacted_at: Optional[datetime]` When the reaction was added or removed - `service: Optional[ServiceType]` Messaging service type - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ReactionRemovedWebhookEvent: …` Complete webhook payload for reaction.removed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: ReactionEventBase` Payload for reaction.removed webhook events - `is_from_me: bool` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: Optional[str]` Chat identifier (UUID) - `custom_emoji: Optional[str]` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from_: Optional[str]` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: Optional[ChatHandle]` The person who added/removed the reaction as a full handle object - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `message_id: Optional[str]` Message identifier (UUID) that the reaction was added to or removed from - `part_index: Optional[int]` Index of the message part that was reacted to (0-based) - `reacted_at: Optional[datetime]` When the reaction was added or removed - `service: Optional[ServiceType]` Messaging service type - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ParticipantAddedWebhookEvent: …` Complete webhook payload for participant.added events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for participant.added webhook events - `handle: str` DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant. - `added_at: Optional[datetime]` When the participant was added - `chat_id: Optional[str]` Chat identifier (UUID) of the group chat - `participant: Optional[ChatHandle]` The added participant as a full handle object - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ParticipantRemovedWebhookEvent: …` Complete webhook payload for participant.removed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for participant.removed webhook events - `handle: str` DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant. - `chat_id: Optional[str]` Chat identifier (UUID) of the group chat - `participant: Optional[ChatHandle]` The removed participant as a full handle object - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `removed_at: Optional[datetime]` When the participant was removed - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatCreatedWebhookEvent: …` Complete webhook payload for chat.created events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response. - `id: str` Unique identifier for the chat - `created_at: datetime` When the chat was created - `display_name: Optional[str]` Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats. - `handles: List[ChatHandle]` List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant). - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `health_status: DataHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: bool` Whether this is a group chat - `updated_at: datetime` When the chat was last updated - `service: Optional[ServiceType]` Messaging service type - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatGroupNameUpdatedWebhookEvent: …` Complete webhook payload for chat.group_name_updated events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.group_name_updated webhook events - `chat_id: str` Chat identifier (UUID) of the group chat - `updated_at: datetime` When the update occurred - `changed_by_handle: Optional[ChatHandle]` The handle who made the change. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `new_value: Optional[str]` New group name (null if the name was removed) - `old_value: Optional[str]` Previous group name (null if no previous name) - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatGroupIconUpdatedWebhookEvent: …` Complete webhook payload for chat.group_icon_updated events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.group_icon_updated webhook events - `chat_id: str` Chat identifier (UUID) of the group chat - `updated_at: datetime` When the update occurred - `changed_by_handle: Optional[ChatHandle]` The handle who made the change. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `new_value: Optional[str]` New icon URL (null if the icon was removed) - `old_value: Optional[str]` Previous icon URL (null if no previous icon) - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatGroupNameUpdateFailedWebhookEvent: …` Complete webhook payload for chat.group_name_update_failed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Chat identifier (UUID) of the group chat - `error_code: int` Error codes in webhook failure events (3007, 4001). - `failed_at: datetime` When the failure was detected - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatGroupIconUpdateFailedWebhookEvent: …` Complete webhook payload for chat.group_icon_update_failed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Chat identifier (UUID) of the group chat - `error_code: int` Error codes in webhook failure events (3007, 4001). - `failed_at: datetime` When the failure was detected - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatTypingIndicatorStartedWebhookEvent: …` Complete webhook payload for chat.typing_indicator.started events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.typing_indicator.started webhook events - `chat_id: str` Chat identifier - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class ChatTypingIndicatorStoppedWebhookEvent: …` Complete webhook payload for chat.typing_indicator.stopped events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.typing_indicator.stopped webhook events - `chat_id: str` Chat identifier - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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 - `class PhoneNumberStatusUpdatedWebhookEvent: …` Complete webhook payload for phone_number.status_updated events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for phone_number.status_updated webhook events - `changed_at: datetime` When the status change occurred - `new_health_status: Literal["HEALTHY", "AT_RISK", "CRITICAL"]` The new line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `new_status: Literal["ACTIVE", "FLAGGED"]` The new service status - `"ACTIVE"` - `"FLAGGED"` - `phone_number: str` Phone number in E.164 format - `previous_health_status: Literal["HEALTHY", "AT_RISK", "CRITICAL"]` The previous line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `previous_status: Literal["ACTIVE", "FLAGGED"]` The previous service status - `"ACTIVE"` - `"FLAGGED"` - `event_id: str` Unique identifier for this event (for deduplication) - `event_type: Literal["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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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` Complete webhook payload for message.sent events (2026-02-03 format) - `class MessageSentWebhookEvent: …` Complete webhook payload for message.sent events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: Chat` Chat information - `id: str` Chat identifier - `health_status: ChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: Optional[bool]` Whether this is a group chat - `owner_handle: Optional[ChatHandle]` Your phone number's handle. Always has is_me=true. - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `"iMessage"` - `"SMS"` - `"RCS"` - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `"active"` - `"left"` - `"removed"` - `direction: Literal["inbound", "outbound"]` Message direction - "outbound" if sent by you, "inbound" if received - `"inbound"` - `"outbound"` - `parts: List[Part]` Message parts (text and/or media) - `class SchemasTextPartResponse: …` A text message part - `type: Literal["text"]` Indicates this is a text message part - `"text"` - `value: str` The text content - `text_decorations: Optional[List[TextDecoration]]` Text decorations applied to character ranges in the value - `range: List[int]` Character range `[start, end)` in the `value` string where the decoration applies. `start` is inclusive, `end` is exclusive. *Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.* - `animation: Optional[Literal["big", "small", "shake", 5 more]]` Animated text effect to apply. Mutually exclusive with `style`. - `"big"` - `"small"` - `"shake"` - `"nod"` - `"explode"` - `"ripple"` - `"bloom"` - `"jitter"` - `style: Optional[Literal["bold", "italic", "strikethrough", "underline"]]` Text style to apply. Mutually exclusive with `animation`. - `"bold"` - `"italic"` - `"strikethrough"` - `"underline"` - `class SchemasMediaPartResponse: …` A media attachment part - `id: str` Unique attachment identifier - `filename: str` Original filename - `mime_type: str` MIME type of the file - `size_bytes: int` File size in bytes - `type: Literal["media"]` Indicates this is a media attachment part - `"media"` - `url: str` Presigned URL for downloading the attachment (expires in 1 hour). - `class PartSchemasLinkPartResponse: …` A rich link preview part - `type: Literal["link"]` Indicates this is a rich link preview part - `"link"` - `value: str` The URL - `sender_handle: ChatHandle` The handle that sent this message - `service: ServiceType` Messaging service type - `delivered_at: Optional[datetime]` When the message was delivered. Null if not yet delivered. - `effect: Optional[SchemasMessageEffect]` iMessage effect applied to a message (screen or bubble animation) - `name: Optional[str]` Effect name (confetti, fireworks, slam, gentle, etc.) - `type: Optional[Literal["screen", "bubble"]]` Effect category - `"screen"` - `"bubble"` - `idempotency_key: Optional[str]` Idempotency key for deduplication of outbound messages. - `preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]` Preferred messaging service type. Includes "auto" for default fallback behavior. - `"iMessage"` - `"SMS"` - `"RCS"` - `"auto"` - `read_at: Optional[datetime]` When the message was read. Null if not yet read. - `reply_to: Optional[ReplyTo]` Reference to the message this is replying to (for threaded replies) - `message_id: Optional[str]` ID of the message being replied to - `part_index: Optional[int]` Index of the part being replied to - `sent_at: Optional[datetime]` When the message was sent. Null if not yet sent. - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class MessageReceivedWebhookEvent: …` Complete webhook payload for message.received events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class MessageReadWebhookEvent: …` Complete webhook payload for message.read events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class MessageDeliveredWebhookEvent: …` Complete webhook payload for message.delivered events (2026-02-03 format) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class MessageFailedWebhookEvent: …` Complete webhook payload for message.failed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: int` Error codes in webhook failure events (3007, 4001). - `failed_at: datetime` When the failure was detected - `chat_id: Optional[str]` Chat identifier (UUID) - `message_id: Optional[str]` Message identifier (UUID) - `reason: Optional[str]` Human-readable description of the failure - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class MessageEditedWebhookEvent: …` Complete webhook payload for message.edited events (2026-02-03 format only) - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Message identifier - `chat: DataChat` Chat context - `id: str` Chat identifier - `health_status: DataChatHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: bool` Whether this is a group chat - `owner_handle: ChatHandle` The handle that owns this chat (your phone number) - `direction: Literal["outbound", "inbound"]` "outbound" if you sent the original message, "inbound" if you received it - `"outbound"` - `"inbound"` - `edited_at: datetime` When the edit occurred - `part: DataPart` The edited part - `index: int` Zero-based index of the edited part within the message - `text: str` New text content of the part - `sender_handle: ChatHandle` The handle that sent (and edited) this message - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ReactionAddedWebhookEvent: …` Complete webhook payload for reaction.added events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: ReactionEventBase` Payload for reaction.added webhook events - `is_from_me: bool` Whether this reaction was from the owner of the phone number (true) or from someone else (false) - `reaction_type: ReactionType` Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type "custom" with the actual emoji in the custom_emoji field. Sticker reactions have type "sticker" with sticker attachment details in the sticker field. - `"love"` - `"like"` - `"dislike"` - `"laugh"` - `"emphasize"` - `"question"` - `"custom"` - `"sticker"` - `chat_id: Optional[str]` Chat identifier (UUID) - `custom_emoji: Optional[str]` The actual emoji when reaction_type is "custom". Null for standard tapbacks. - `from_: Optional[str]` DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction. - `from_handle: Optional[ChatHandle]` The person who added/removed the reaction as a full handle object - `message_id: Optional[str]` Message identifier (UUID) that the reaction was added to or removed from - `part_index: Optional[int]` Index of the message part that was reacted to (0-based) - `reacted_at: Optional[datetime]` When the reaction was added or removed - `service: Optional[ServiceType]` Messaging service type - `sticker: Optional[Sticker]` Sticker attachment details when reaction_type is "sticker". Null for non-sticker reactions. - `file_name: Optional[str]` Filename of the sticker - `height: Optional[int]` Sticker image height in pixels - `mime_type: Optional[str]` MIME type of the sticker image - `url: Optional[str]` Presigned URL for downloading the sticker image (expires in 1 hour). - `width: Optional[int]` Sticker image width in pixels - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ReactionRemovedWebhookEvent: …` Complete webhook payload for reaction.removed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: ReactionEventBase` Payload for reaction.removed webhook events - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ParticipantAddedWebhookEvent: …` Complete webhook payload for participant.added events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for participant.added webhook events - `handle: str` DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant. - `added_at: Optional[datetime]` When the participant was added - `chat_id: Optional[str]` Chat identifier (UUID) of the group chat - `participant: Optional[ChatHandle]` The added participant as a full handle object - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ParticipantRemovedWebhookEvent: …` Complete webhook payload for participant.removed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for participant.removed webhook events - `handle: str` DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant. - `chat_id: Optional[str]` Chat identifier (UUID) of the group chat - `participant: Optional[ChatHandle]` The removed participant as a full handle object - `removed_at: Optional[datetime]` When the participant was removed - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatCreatedWebhookEvent: …` Complete webhook payload for chat.created events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response. - `id: str` Unique identifier for the chat - `created_at: datetime` When the chat was created - `display_name: Optional[str]` Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats. - `handles: List[ChatHandle]` List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant). - `id: str` Unique identifier for this handle - `handle: str` Phone number (E.164) or email address of the participant - `joined_at: datetime` When this participant joined the chat - `service: ServiceType` Messaging service type - `is_me: Optional[bool]` Whether this handle belongs to the sender (your phone number) - `left_at: Optional[datetime]` When they left (if applicable) - `status: Optional[Literal["active", "left", "removed"]]` Participant status - `health_status: DataHealthStatus` **[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: str` Deep-link to the relevant section of the Chat Health guide for this status. - `status: Literal["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: datetime` When this status last changed. - `is_group: bool` Whether this is a group chat - `updated_at: datetime` When the chat was last updated - `service: Optional[ServiceType]` Messaging service type - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatGroupNameUpdatedWebhookEvent: …` Complete webhook payload for chat.group_name_updated events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.group_name_updated webhook events - `chat_id: str` Chat identifier (UUID) of the group chat - `updated_at: datetime` When the update occurred - `changed_by_handle: Optional[ChatHandle]` The handle who made the change. - `new_value: Optional[str]` New group name (null if the name was removed) - `old_value: Optional[str]` Previous group name (null if no previous name) - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatGroupIconUpdatedWebhookEvent: …` Complete webhook payload for chat.group_icon_updated events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.group_icon_updated webhook events - `chat_id: str` Chat identifier (UUID) of the group chat - `updated_at: datetime` When the update occurred - `changed_by_handle: Optional[ChatHandle]` The handle who made the change. - `new_value: Optional[str]` New icon URL (null if the icon was removed) - `old_value: Optional[str]` Previous icon URL (null if no previous icon) - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatGroupNameUpdateFailedWebhookEvent: …` Complete webhook payload for chat.group_name_update_failed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Chat identifier (UUID) of the group chat - `error_code: int` Error codes in webhook failure events (3007, 4001). - `failed_at: datetime` When the failure was detected - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatGroupIconUpdateFailedWebhookEvent: …` Complete webhook payload for chat.group_icon_update_failed events - `api_version: str` API version for the webhook payload format - `created_at: datetime` 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: str` Chat identifier (UUID) of the group chat - `error_code: int` Error codes in webhook failure events (3007, 4001). - `failed_at: datetime` When the failure was detected - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatTypingIndicatorStartedWebhookEvent: …` Complete webhook payload for chat.typing_indicator.started events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.typing_indicator.started webhook events - `chat_id: str` Chat identifier - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class ChatTypingIndicatorStoppedWebhookEvent: …` Complete webhook payload for chat.typing_indicator.stopped events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for chat.typing_indicator.stopped webhook events - `chat_id: str` Chat identifier - `event_id: str` 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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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. - `class PhoneNumberStatusUpdatedWebhookEvent: …` Complete webhook payload for phone_number.status_updated events - `api_version: str` API version for the webhook payload format - `created_at: datetime` When the event was created - `data: Data` Payload for phone_number.status_updated webhook events - `changed_at: datetime` When the status change occurred - `new_health_status: Literal["HEALTHY", "AT_RISK", "CRITICAL"]` The new line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `new_status: Literal["ACTIVE", "FLAGGED"]` The new service status - `"ACTIVE"` - `"FLAGGED"` - `phone_number: str` Phone number in E.164 format - `previous_health_status: Literal["HEALTHY", "AT_RISK", "CRITICAL"]` The previous line health status - `"HEALTHY"` - `"AT_RISK"` - `"CRITICAL"` - `previous_status: Literal["ACTIVE", "FLAGGED"]` The previous service status - `"ACTIVE"` - `"FLAGGED"` - `event_id: str` Unique identifier for this event (for deduplication) - `event_type: Literal["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: str` Partner identifier. Present on all webhooks for cross-referencing. - `trace_id: str` Trace ID for debugging and correlation across systems. - `webhook_version: str` 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.