Webhooks

Events

client.webhooks.events(?): void

Function

ModelsExpand Collapse

MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

[BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.

Switch on status to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a doc_url that deep-links to the relevant section of the Chat Health guide.

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

Character range [start, end) in the value string where the decoration applies. start is inclusive, end is exclusive. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

MessagePayload { id, created_at, delivered_at, 8 more }

Message content nested within webhook events

id?: string

Message identifier

formatuuid

created_at?: string

When the message record was created

formatdate-time

delivered_at?: string | null

When the message was delivered

formatdate-time

effect?: SchemasMessageEffect { name, type }

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

is_delivered?: boolean

Whether the message has been delivered

is_read?: boolean

Whether the message has been read

parts?: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message content parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

read_at?: string | null

When the message was read

formatdate-time

reply_to?: ReplyTo { message_id, part_index }

Reference to the message this is replying to

message_id?: string

The ID of the message being replied to

formatuuid

part_index?: number

Index of the message part being replied to (0-based)

formatint32

minimum0

sent_at?: string | null

When the message was sent

formatdate-time

updated_at?: string

When the message record was last updated

formatdate-time

ReactionEventBase { is_from_me, reaction_type, chat_id, 8 more }

is_from_me: boolean

Whether this reaction was from the owner of the phone number (true) or from someone else (false)

reaction_type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

chat_id?: string

Chat identifier (UUID)

custom_emoji?: string | null

The actual emoji when reaction_type is “custom”. Null for standard tapbacks.

Deprecatedfrom?: string

DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction.

from_handle?: ChatHandle { id, handle, joined_at, 4 more }

The person who added/removed the reaction as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

message_id?: string

Message identifier (UUID) that the reaction was added to or removed from

part_index?: number

Index of the message part that was reacted to (0-based)

formatint32

minimum0

reacted_at?: string

When the reaction was added or removed

formatdate-time

service?: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasMessageEffect { name, type }

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

MessageSentWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.sent events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageReceivedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.received events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageReadWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.read events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageDeliveredWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.delivered events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageFailedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { code, failed_at, chat_id, 2 more }

Error details for message.failed webhook events. See WebhookErrorCode for the full error code reference.

code: number

Error codes in webhook failure events (3007, 4001).

failed_at: string

When the failure was detected

formatdate-time

chat_id?: string

Chat identifier (UUID)

message_id?: string

Message identifier (UUID)

reason?: string

Human-readable description of the failure

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageEditedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.edited events (2026-02-03 format only)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { id, chat, direction, 3 more }

Payload for message.edited events (2026-02-03 format).

Describes which part of a message was edited and when. Only text parts can be edited. Only available for subscriptions using webhook_version: "2026-02-03".

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat context

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group: boolean

Whether this is a group chat

owner_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that owns this chat (your phone number)

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "outbound" | "inbound"

“outbound” if you sent the original message, “inbound” if you received it

One of the following:

"outbound"

"inbound"

edited_at: string

When the edit occurred

formatdate-time

part: Part { index, text }

The edited part

index: number

Zero-based index of the edited part within the message

text: string

New text content of the part

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent (and edited) this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ReactionAddedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: ReactionEventBase { is_from_me, reaction_type, chat_id, 8 more }

Payload for reaction.added webhook events

is_from_me: boolean

Whether this reaction was from the owner of the phone number (true) or from someone else (false)

reaction_type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

chat_id?: string

Chat identifier (UUID)

custom_emoji?: string | null

The actual emoji when reaction_type is “custom”. Null for standard tapbacks.

Deprecatedfrom?: string

DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction.

from_handle?: ChatHandle { id, handle, joined_at, 4 more }

The person who added/removed the reaction as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

message_id?: string

Message identifier (UUID) that the reaction was added to or removed from

part_index?: number

Index of the message part that was reacted to (0-based)

formatint32

minimum0

reacted_at?: string

When the reaction was added or removed

formatdate-time

service?: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ReactionRemovedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: ReactionEventBase { is_from_me, reaction_type, chat_id, 8 more }

Payload for reaction.removed webhook events

is_from_me: boolean

Whether this reaction was from the owner of the phone number (true) or from someone else (false)

reaction_type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

chat_id?: string

Chat identifier (UUID)

custom_emoji?: string | null

The actual emoji when reaction_type is “custom”. Null for standard tapbacks.

Deprecatedfrom?: string

DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction.

from_handle?: ChatHandle { id, handle, joined_at, 4 more }

The person who added/removed the reaction as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

message_id?: string

Message identifier (UUID) that the reaction was added to or removed from

part_index?: number

Index of the message part that was reacted to (0-based)

formatint32

minimum0

reacted_at?: string

When the reaction was added or removed

formatdate-time

service?: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ParticipantAddedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for participant.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { handle, added_at, chat_id, participant }

Payload for participant.added webhook events

Deprecatedhandle: string

DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant.

added_at?: string

When the participant was added

formatdate-time

chat_id?: string

Chat identifier (UUID) of the group chat

participant?: ChatHandle { id, handle, joined_at, 4 more }

The added participant as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ParticipantRemovedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for participant.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { handle, chat_id, participant, removed_at }

Payload for participant.removed webhook events

Deprecatedhandle: string

DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant.

chat_id?: string

Chat identifier (UUID) of the group chat

participant?: ChatHandle { id, handle, joined_at, 4 more }

The removed participant as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

removed_at?: string

When the participant was removed

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatCreatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.created events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { id, created_at, display_name, 5 more }

Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response.

id: string

Unique identifier for the chat

formatuuid

created_at: string

When the chat was created

formatdate-time

display_name: string | null

Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.

handles: Array<ChatHandle { id, handle, joined_at, 4 more } >

List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group: boolean

Whether this is a group chat

updated_at: string

When the chat was last updated

formatdate-time

service?: ServiceType | null

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupNameUpdatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, updated_at, changed_by_handle, 2 more }

Payload for chat.group_name_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

The handle who made the change.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

new_value?: string | null

New group name (null if the name was removed)

old_value?: string | null

Previous group name (null if no previous name)

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupIconUpdatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, updated_at, changed_by_handle, 2 more }

Payload for chat.group_icon_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

The handle who made the change.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

new_value?: string | null

New icon URL (null if the icon was removed)

old_value?: string | null

Previous icon URL (null if no previous icon)

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupNameUpdateFailedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, error_code, failed_at }

Error details for chat.group_name_update_failed webhook events. See WebhookErrorCode for the full error code reference.

chat_id: string

Chat identifier (UUID) of the group chat

error_code: number

Error codes in webhook failure events (3007, 4001).

failed_at: string

When the failure was detected

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupIconUpdateFailedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, error_code, failed_at }

Error details for chat.group_icon_update_failed webhook events. See WebhookErrorCode for the full error code reference.

chat_id: string

Chat identifier (UUID) of the group chat

error_code: number

Error codes in webhook failure events (3007, 4001).

failed_at: string

When the failure was detected

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatTypingIndicatorStartedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.started events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id }

Payload for chat.typing_indicator.started webhook events

chat_id: string

Chat identifier

formatuuid

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatTypingIndicatorStoppedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.stopped events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id }

Payload for chat.typing_indicator.stopped webhook events

chat_id: string

Chat identifier

formatuuid

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

PhoneNumberStatusUpdatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for phone_number.status_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { changed_at, new_health_status, new_status, 3 more }

Payload for phone_number.status_updated webhook events

changed_at: string

When the status change occurred

formatdate-time

new_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"

The new line health status

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

new_status: "ACTIVE" | "FLAGGED"

The new service status

One of the following:

"ACTIVE"

"FLAGGED"

phone_number: string

Phone number in E.164 format

previous_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"

The previous line health status

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

previous_status: "ACTIVE" | "FLAGGED"

The previous service status

One of the following:

"ACTIVE"

"FLAGGED"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

event_type: "message.sent" | "message.received" | "message.read" | 22 more

The type of event

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

EventsWebhookEvent = MessageSentWebhookEvent { api_version, created_at, data, 5 more } | MessageReceivedWebhookEvent { api_version, created_at, data, 5 more } | MessageReadWebhookEvent { api_version, created_at, data, 5 more } | 15 more

Complete webhook payload for message.sent events (2026-02-03 format)

One of the following:

MessageSentWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.sent events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageReceivedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.received events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageReadWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.read events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageDeliveredWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.delivered events (2026-02-03 format)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: MessageEventV2 { id, chat, direction, 10 more }

Unified payload for message webhooks when using webhook_version: "2026-02-03".

This schema is used for message.sent, message.received, message.delivered, and message.read events when the subscription URL includes ?version=2026-02-03.

Key differences from V1 (2025-01-01):

direction: “inbound” or “outbound” instead of is_from_me boolean
sender_handle: Full handle object for the sender
chat: Nested object with id, is_group, and owner_handle
Message fields (id, parts, effect, etc.) are at the top level, not nested in message

Timestamps indicate the message state:

message.sent: sent_at set, delivered_at=null, read_at=null
message.received: sent_at set, delivered_at=null, read_at=null
message.delivered: sent_at set, delivered_at set, read_at=null
message.read: sent_at set, delivered_at set, read_at set

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group?: boolean | null

Whether this is a group chat

owner_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

Your phone number’s handle. Always has is_me=true.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" | "outbound"

Message direction - “outbound” if sent by you, “inbound” if received

One of the following:

"inbound"

"outbound"

parts: Array<SchemasTextPartResponse { type, value, text_decorations } | SchemasMediaPartResponse { id, filename, mime_type, 3 more } | SchemasLinkPartResponse { type, value } >

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse { id, filename, mime_type, 3 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid

filename: string

Original filename

mime_type: string

MIME type of the file

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

Presigned URL for downloading the attachment (expires in 1 hour).

formaturi

SchemasLinkPartResponse { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at?: string | null

When the message was delivered. Null if not yet delivered.

formatdate-time

effect?: SchemasMessageEffect { name, type } | null

iMessage effect applied to a message (screen or bubble animation)

name?: string

Effect name (confetti, fireworks, slam, gentle, etc.)

type?: "screen" | "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key?: string | null

Idempotency key for deduplication of outbound messages.

preferred_service?: "iMessage" | "SMS" | "RCS" | "auto" | null

Preferred messaging service type. Includes “auto” for default fallback behavior.

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at?: string | null

When the message was read. Null if not yet read.

formatdate-time

reply_to?: ReplyTo | null

Reference to the message this is replying to (for threaded replies)

message_id?: string

ID of the message being replied to

formatuuid

part_index?: number

Index of the part being replied to

formatint32

minimum0

sent_at?: string | null

When the message was sent. Null if not yet sent.

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageFailedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { code, failed_at, chat_id, 2 more }

Error details for message.failed webhook events. See WebhookErrorCode for the full error code reference.

code: number

Error codes in webhook failure events (3007, 4001).

failed_at: string

When the failure was detected

formatdate-time

chat_id?: string

Chat identifier (UUID)

message_id?: string

Message identifier (UUID)

reason?: string

Human-readable description of the failure

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

MessageEditedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for message.edited events (2026-02-03 format only)

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { id, chat, direction, 3 more }

Payload for message.edited events (2026-02-03 format).

Describes which part of a message was edited and when. Only text parts can be edited. Only available for subscriptions using webhook_version: "2026-02-03".

id: string

Message identifier

formatuuid

chat: Chat { id, health_status, is_group, owner_handle }

Chat context

id: string

Chat identifier

formatuuid

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group: boolean

Whether this is a group chat

owner_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that owns this chat (your phone number)

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

direction: "outbound" | "inbound"

“outbound” if you sent the original message, “inbound” if you received it

One of the following:

"outbound"

"inbound"

edited_at: string

When the edit occurred

formatdate-time

part: Part { index, text }

The edited part

index: number

Zero-based index of the edited part within the message

text: string

New text content of the part

sender_handle: ChatHandle { id, handle, joined_at, 4 more }

The handle that sent (and edited) this message

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ReactionAddedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: ReactionEventBase { is_from_me, reaction_type, chat_id, 8 more }

Payload for reaction.added webhook events

is_from_me: boolean

Whether this reaction was from the owner of the phone number (true) or from someone else (false)

reaction_type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

chat_id?: string

Chat identifier (UUID)

custom_emoji?: string | null

The actual emoji when reaction_type is “custom”. Null for standard tapbacks.

Deprecatedfrom?: string

DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction.

from_handle?: ChatHandle { id, handle, joined_at, 4 more }

The person who added/removed the reaction as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

message_id?: string

Message identifier (UUID) that the reaction was added to or removed from

part_index?: number

Index of the message part that was reacted to (0-based)

formatint32

minimum0

reacted_at?: string

When the reaction was added or removed

formatdate-time

service?: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ReactionRemovedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: ReactionEventBase { is_from_me, reaction_type, chat_id, 8 more }

Payload for reaction.removed webhook events

is_from_me: boolean

Whether this reaction was from the owner of the phone number (true) or from someone else (false)

reaction_type: ReactionType

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

chat_id?: string

Chat identifier (UUID)

custom_emoji?: string | null

The actual emoji when reaction_type is “custom”. Null for standard tapbacks.

Deprecatedfrom?: string

DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction.

from_handle?: ChatHandle { id, handle, joined_at, 4 more }

The person who added/removed the reaction as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

message_id?: string

Message identifier (UUID) that the reaction was added to or removed from

part_index?: number

Index of the message part that was reacted to (0-based)

formatint32

minimum0

reacted_at?: string

When the reaction was added or removed

formatdate-time

service?: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

Presigned URL for downloading the sticker image (expires in 1 hour).

formaturi

width?: number

Sticker image width in pixels

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ParticipantAddedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for participant.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { handle, added_at, chat_id, participant }

Payload for participant.added webhook events

Deprecatedhandle: string

DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant.

added_at?: string

When the participant was added

formatdate-time

chat_id?: string

Chat identifier (UUID) of the group chat

participant?: ChatHandle { id, handle, joined_at, 4 more }

The added participant as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ParticipantRemovedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for participant.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { handle, chat_id, participant, removed_at }

Payload for participant.removed webhook events

Deprecatedhandle: string

DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant.

chat_id?: string

Chat identifier (UUID) of the group chat

participant?: ChatHandle { id, handle, joined_at, 4 more }

The removed participant as a full handle object

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

removed_at?: string

When the participant was removed

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatCreatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.created events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { id, created_at, display_name, 5 more }

Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response.

id: string

Unique identifier for the chat

formatuuid

created_at: string

When the chat was created

formatdate-time

display_name: string | null

Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.

handles: Array<ChatHandle { id, handle, joined_at, 4 more } >

List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

health_status: HealthStatus { doc_url, status, updated_at }

See the Chat Health guide for what each status means and how to react.

doc_url: string

Deep-link to the relevant section of the Chat Health guide for this status.

formaturi

status: "HEALTHY" | "AT_RISK" | "CRITICAL" | "OPTED_OUT"

Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

formatdate-time

is_group: boolean

Whether this is a group chat

updated_at: string

When the chat was last updated

formatdate-time

service?: ServiceType | null

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupNameUpdatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, updated_at, changed_by_handle, 2 more }

Payload for chat.group_name_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

The handle who made the change.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

new_value?: string | null

New group name (null if the name was removed)

old_value?: string | null

Previous group name (null if no previous name)

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupIconUpdatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, updated_at, changed_by_handle, 2 more }

Payload for chat.group_icon_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle?: ChatHandle { id, handle, joined_at, 4 more } | null

The handle who made the change.

id: string

Unique identifier for this handle

formatuuid

handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

is_me?: boolean | null

Whether this handle belongs to the sender (your phone number)

left_at?: string | null

When they left (if applicable)

formatdate-time

status?: "active" | "left" | "removed" | null

Participant status

One of the following:

"active"

"left"

"removed"

new_value?: string | null

New icon URL (null if the icon was removed)

old_value?: string | null

Previous icon URL (null if no previous icon)

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupNameUpdateFailedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, error_code, failed_at }

Error details for chat.group_name_update_failed webhook events. See WebhookErrorCode for the full error code reference.

chat_id: string

Chat identifier (UUID) of the group chat

error_code: number

Error codes in webhook failure events (3007, 4001).

failed_at: string

When the failure was detected

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatGroupIconUpdateFailedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id, error_code, failed_at }

Error details for chat.group_icon_update_failed webhook events. See WebhookErrorCode for the full error code reference.

chat_id: string

Chat identifier (UUID) of the group chat

error_code: number

Error codes in webhook failure events (3007, 4001).

failed_at: string

When the failure was detected

formatdate-time

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatTypingIndicatorStartedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.started events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id }

Payload for chat.typing_indicator.started webhook events

chat_id: string

Chat identifier

formatuuid

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

ChatTypingIndicatorStoppedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.stopped events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { chat_id }

Payload for chat.typing_indicator.stopped webhook events

chat_id: string

Chat identifier

formatuuid

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

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.

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.

PhoneNumberStatusUpdatedWebhookEvent { api_version, created_at, data, 5 more }

Complete webhook payload for phone_number.status_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: Data { changed_at, new_health_status, new_status, 3 more }

Payload for phone_number.status_updated webhook events

changed_at: string

When the status change occurred

formatdate-time

new_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"

The new line health status

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

new_status: "ACTIVE" | "FLAGGED"

The new service status

One of the following:

"ACTIVE"

"FLAGGED"

phone_number: string

Phone number in E.164 format

previous_health_status: "HEALTHY" | "AT_RISK" | "CRITICAL"

The previous line health status

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

previous_status: "ACTIVE" | "FLAGGED"

The previous service status

One of the following:

"ACTIVE"

"FLAGGED"

event_id: string

Unique identifier for this event (for deduplication)

formatuuid

event_type: "message.sent" | "message.received" | "message.read" | 22 more

The type of event

One of the following:

"message.sent"

"message.received"

"message.read"

"message.delivered"

"message.failed"

"message.edited"

"reaction.added"

"reaction.removed"

"participant.added"

"participant.removed"

"chat.created"

"chat.group_name_updated"

"chat.group_icon_updated"

"chat.group_name_update_failed"

"chat.group_icon_update_failed"

"chat.typing_indicator.started"

"chat.typing_indicator.stopped"

"phone_number.status_updated"

"call.initiated"

"call.ringing"

"call.answered"

"call.ended"

"call.failed"

"call.declined"

"call.no_answer"

partner_id: string

Partner identifier. Present on all webhooks for cross-referencing.

trace_id: string

Trace ID for debugging and correlation across systems.

webhook_version: string

Date-based webhook payload version. Determined by the ?version= query parameter in your webhook subscription URL. If no version parameter is specified, defaults based on subscription creation date.