API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Webhooks

Events

Function

ModelsExpand Collapse

MessageEventV2 object { id, chat, direction, 10 more }

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

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

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

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

Timestamps indicate the message state:

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

id: string

Message identifier

formatuuid

chat: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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

formatdate-time

MessagePayload object { id, created_at, delivered_at, 8 more }

Message content nested within webhook events

id: optional string

Message identifier

formatuuid

created_at: optional string

When the message record was created

formatdate-time

delivered_at: optional string

When the message was delivered

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

is_delivered: optional boolean

Whether the message has been delivered

is_read: optional boolean

Whether the message has been read

parts: optional array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message content parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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 object { type, value }

A rich link preview part

type: "link"

Indicates this is a rich link preview part

value: string

The URL

read_at: optional string

When the message was read

formatdate-time

reply_to: optional object { message_id, part_index }

Reference to the message this is replying to

message_id: optional string

The ID of the message being replied to

formatuuid

part_index: optional number

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

formatint32

minimum0

sent_at: optional string

When the message was sent

formatdate-time

updated_at: optional string

When the message record was last updated

formatdate-time

ReactionEventBase object { is_from_me, reaction_type, chat_id, 8 more }

is_from_me: boolean

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

reaction_type: ReactionType

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

One of the following:

"love"

"like"

"dislike"

"laugh"

"emphasize"

"question"

"custom"

"sticker"

chat_id: optional string

Chat identifier (UUID)

custom_emoji: optional string

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

Deprecatedfrom: optional string

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

from_handle: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

message_id: optional string

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

part_index: optional number

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

formatint32

minimum0

reacted_at: optional string

When the reaction was added or removed

formatdate-time

service: optional ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker: optional object { file_name, height, mime_type, 2 more }

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

file_name: optional string

Filename of the sticker

height: optional number

Sticker image height in pixels

mime_type: optional string

MIME type of the sticker image

url: optional string

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

formaturi

width: optional number

Sticker image width in pixels

SchemasMediaPartResponse object { 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 object { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

MessageSentWebhookEvent object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for message.failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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: optional string

Chat identifier (UUID)

message_id: optional string

Message identifier (UUID)

reason: optional string

Human-readable description of the failure

event_id: string

Unique identifier for this event (for deduplication)

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

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

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

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

id: string

Message identifier

formatuuid

chat: object { id, is_group, owner_handle }

Chat context

id: string

Chat identifier

formatuuid

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "outbound" or "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: object { index, text }

The edited part

index: number

Zero-based index of the edited part within the message

text: string

New text content of the part

sender_handle: ChatHandle { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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

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: optional string

Chat identifier (UUID)

custom_emoji: optional string

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

Deprecatedfrom: optional string

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

from_handle: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

message_id: optional string

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

part_index: optional number

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

formatint32

minimum0

reacted_at: optional string

When the reaction was added or removed

formatdate-time

service: optional ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker: optional object { file_name, height, mime_type, 2 more }

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

file_name: optional string

Filename of the sticker

height: optional number

Sticker image height in pixels

mime_type: optional string

MIME type of the sticker image

url: optional string

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

formaturi

width: optional 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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

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: optional string

Chat identifier (UUID)

custom_emoji: optional string

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

Deprecatedfrom: optional string

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

from_handle: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

message_id: optional string

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

part_index: optional number

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

formatint32

minimum0

reacted_at: optional string

When the reaction was added or removed

formatdate-time

service: optional ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker: optional object { file_name, height, mime_type, 2 more }

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

file_name: optional string

Filename of the sticker

height: optional number

Sticker image height in pixels

mime_type: optional string

MIME type of the sticker image

url: optional string

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

formaturi

width: optional 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for participant.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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: optional string

When the participant was added

formatdate-time

chat_id: optional string

Chat identifier (UUID) of the group chat

participant: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for participant.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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: optional string

Chat identifier (UUID) of the group chat

participant: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

removed_at: optional 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.created events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { id, created_at, display_name, 4 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

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

handles: array of 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

is_group: boolean

Whether this is a group chat

updated_at: string

When the chat was last updated

formatdate-time

service: optional ServiceType

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

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

Payload for chat.group_name_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle: optional ChatHandle { id, handle, joined_at, 4 more }

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

new_value: optional string

New group name (null if the name was removed)

old_value: optional string

Previous group name (null if no previous name)

event_id: string

Unique identifier for this event (for deduplication)

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

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

Payload for chat.group_icon_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle: optional ChatHandle { id, handle, joined_at, 4 more }

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

new_value: optional string

New icon URL (null if the icon was removed)

old_value: optional string

Previous icon URL (null if no previous icon)

event_id: string

Unique identifier for this event (for deduplication)

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.started events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.stopped events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for phone_number.status_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { changed_at, new_status, phone_number, previous_status }

Payload for phone_number.status_updated webhook events

changed_at: string

When the status change occurred

formatdate-time

new_status: "ACTIVE" or "FLAGGED"

The new service status

One of the following:

"ACTIVE"

"FLAGGED"

phone_number: string

Phone number in E.164 format

previous_status: "ACTIVE" or "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" or "message.received" or "message.read" or 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 } or MessageReceivedWebhookEvent { api_version, created_at, data, 5 more } or MessageReadWebhookEvent { api_version, created_at, data, 5 more } or 15 more

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

One of the following:

MessageSentWebhookEvent object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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: object { id, health_score, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_score: optional object { reason, score, updated_at }

[BETA] Health assessment for a chat. Higher score is healthier. null when a score isn’t available yet. Scoring may change during beta.

reason: string

Short summary of what’s affecting the score. Empty when the score is 100.

score: number

Health score from 0 to 100. Higher is healthier.

minimum0

maximum100

updated_at: string

When this health score was last computed.

formatdate-time

is_group: optional boolean

Whether this is a group chat

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

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "inbound" or "outbound"

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

One of the following:

"inbound"

"outbound"

parts: array of SchemasTextPartResponse { type, value, text_decorations } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value }

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, text_decorations }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

text_decorations: optional array of TextDecoration { range, animation, style }

Text decorations applied to character ranges in the value

range: array of number

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

animation: optional "big" or "small" or "shake" or 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:

"big"

"small"

"shake"

"nod"

"explode"

"ripple"

"bloom"

"jitter"

style: optional "bold" or "italic" or "strikethrough" or "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:

"bold"

"italic"

"strikethrough"

"underline"

SchemasMediaPartResponse object { 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

Link object { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

service: ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

delivered_at: optional string

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

formatdate-time

effect: optional SchemasMessageEffect { name, type }

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

name: optional string

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

idempotency_key: optional string

Idempotency key for deduplication of outbound messages.

preferred_service: optional "iMessage" or "SMS" or "RCS" or "auto"

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

One of the following:

"iMessage"

"SMS"

"RCS"

"auto"

read_at: optional string

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

formatdate-time

reply_to: optional object { message_id, part_index }

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

message_id: optional string

ID of the message being replied to

formatuuid

part_index: optional number

Index of the part being replied to

formatint32

minimum0

sent_at: optional string

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for message.failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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: optional string

Chat identifier (UUID)

message_id: optional string

Message identifier (UUID)

reason: optional string

Human-readable description of the failure

event_id: string

Unique identifier for this event (for deduplication)

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 object { api_version, created_at, data, 5 more }

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

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

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

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

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

id: string

Message identifier

formatuuid

chat: object { id, is_group, owner_handle }

Chat context

id: string

Chat identifier

formatuuid

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

direction: "outbound" or "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: object { index, text }

The edited part

index: number

Zero-based index of the edited part within the message

text: string

New text content of the part

sender_handle: ChatHandle { 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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

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: optional string

Chat identifier (UUID)

custom_emoji: optional string

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

Deprecatedfrom: optional string

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

from_handle: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

message_id: optional string

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

part_index: optional number

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

formatint32

minimum0

reacted_at: optional string

When the reaction was added or removed

formatdate-time

service: optional ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker: optional object { file_name, height, mime_type, 2 more }

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

file_name: optional string

Filename of the sticker

height: optional number

Sticker image height in pixels

mime_type: optional string

MIME type of the sticker image

url: optional string

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

formaturi

width: optional 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for reaction.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

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

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: optional string

Chat identifier (UUID)

custom_emoji: optional string

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

Deprecatedfrom: optional string

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

from_handle: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

message_id: optional string

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

part_index: optional number

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

formatint32

minimum0

reacted_at: optional string

When the reaction was added or removed

formatdate-time

service: optional ServiceType

Messaging service type

One of the following:

"iMessage"

"SMS"

"RCS"

sticker: optional object { file_name, height, mime_type, 2 more }

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

file_name: optional string

Filename of the sticker

height: optional number

Sticker image height in pixels

mime_type: optional string

MIME type of the sticker image

url: optional string

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

formaturi

width: optional 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for participant.added events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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: optional string

When the participant was added

formatdate-time

chat_id: optional string

Chat identifier (UUID) of the group chat

participant: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for participant.removed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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: optional string

Chat identifier (UUID) of the group chat

participant: optional 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

removed_at: optional 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.created events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { id, created_at, display_name, 4 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

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

handles: array of 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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

is_group: boolean

Whether this is a group chat

updated_at: string

When the chat was last updated

formatdate-time

service: optional ServiceType

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

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

Payload for chat.group_name_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle: optional ChatHandle { id, handle, joined_at, 4 more }

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

new_value: optional string

New group name (null if the name was removed)

old_value: optional string

Previous group name (null if no previous name)

event_id: string

Unique identifier for this event (for deduplication)

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

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

Payload for chat.group_icon_updated webhook events

chat_id: string

Chat identifier (UUID) of the group chat

updated_at: string

When the update occurred

formatdate-time

changed_by_handle: optional ChatHandle { id, handle, joined_at, 4 more }

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: optional boolean

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

left_at: optional string

When they left (if applicable)

formatdate-time

status: optional "active" or "left" or "removed"

Participant status

One of the following:

"active"

"left"

"removed"

new_value: optional string

New icon URL (null if the icon was removed)

old_value: optional string

Previous icon URL (null if no previous icon)

event_id: string

Unique identifier for this event (for deduplication)

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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_name_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.group_icon_update_failed events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.started events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for chat.typing_indicator.stopped events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { 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 object { api_version, created_at, data, 5 more }

Complete webhook payload for phone_number.status_updated events

api_version: string

API version for the webhook payload format

created_at: string

When the event was created

formatdate-time

data: object { changed_at, new_status, phone_number, previous_status }

Payload for phone_number.status_updated webhook events

changed_at: string

When the status change occurred

formatdate-time

new_status: "ACTIVE" or "FLAGGED"

The new service status

One of the following:

"ACTIVE"

"FLAGGED"

phone_number: string

Phone number in E.164 format

previous_status: "ACTIVE" or "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" or "message.received" or "message.read" or 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.