Webhooks

ModelsExpand Collapse

MessageEventV2 object { id, chat, direction, 11 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_status, is_group, owner_handle }

Chat information

id: string

Chat identifier

formatuuid

health_status: object { doc_url, status, updated_at }

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

Switch on status to surface chat and line health in your UI — the enum is the long-term contract. Each status carries a doc_url that deep-links to the relevant section of the Chat Health guide. To gate a send, act on the response rather than the status: a 403 is the authoritative answer.

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

doc_url: string

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

formaturi

status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"

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

OPTED_OUT — the recipient sent STOP, UNSUBSCRIBE, OPTOUT, CANCEL, END, or QUIT. The keyword must be the whole trimmed message, never part of a longer one: STOP counts, please stop does not. Most keywords must match exactly, including case. OPT OUT is the exception — it matches in any casing, with or without the space or a hyphen, so opt out, Opt-Out and optout all count. It clears as soon as they reply again: any later message from them that is not itself an opt-out keyword opts them back in immediately — a reply in any conversation with you counts, the same way the block does.

OPTED_OUT marks only the conversation the keyword arrived in. The block below is wider than the mark, so a conversation still reading HEALTHY can be blocked as well — gate on the 403, not on the status. Group threads are never marked and are never blocked.

Linq enforces this: while a recipient is opted out, every send to them is rejected with 403 (error code 2024) before the message is queued, across every chat and every line on your account. Nothing is delivered, including a final courtesy message — to send one, set override_optout: true on that single request.

One of the following:

"HEALTHY"

"AT_RISK"

"CRITICAL"

"OPTED_OUT"

updated_at: string

When this status last changed.

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, mention, 2 more } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value } or 2 more

Message parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, mention, 2 more }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

mention: optional string

Handle (E.164 phone number or Apple ID email) of the @mentioned chat participant, as sent. null when the part carries no mention.

mention_range: optional array of number

Character range [start, end) in value highlighted as the mention, as sent. null when the send omitted it (the whole value is highlighted) or the part carries no mention. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

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

IMessageApp object { app, layout, type, 2 more }

An iMessage app card part.

app: object { bundle_id, name, team_id, app_store_id }

Identifies the iMessage app (Messages app extension) that backs the card.

bundle_id: string

Bundle identifier of the Messages app extension.

Display name of the app.

team_id: string

The app’s 10-character team identifier.

app_store_id: optional number

The owning app’s App Store id, when known.

formatint64

Visible layout of the card.

caption: optional string

Primary label, top-left and bold.

subcaption: optional string

Secondary label, below caption on the left.

trailing_caption: optional string

Label shown top-right.

trailing_subcaption: optional string

Label shown below trailing_caption.

type: "imessage_app"

Indicates this is an iMessage app card part.

url: string

The URL the recipient’s app opens when the user taps the card.

formaturi

fallback_text: optional string

Fallback text for surfaces that cannot render the card.

AppClip object { type, value, description, 2 more }

An Apple Pay App Clip payment card part

type: "app_clip"

Indicates this is an App Clip payment card part

value: string

The checkout link the card opens

description: optional string

The card’s summary line, composed by Linq from the checkout session

image_url: optional string

The card’s preview image

title: optional string

The card’s headline, composed by Linq from the checkout session

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)

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

reconciled_at: optional string

Present only when this message was recovered by reconciliation rather than delivered live, and set to the time of that recovery. The field is omitted entirely for normally-delivered messages, which is the overwhelming majority. When present, expect sent_at to be substantially earlier than delivery of this event: the message is genuine but is arriving late and out of real-time order, so treat it as history rather than as a live inbound (for example, suppress auto-replies).

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, 9 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)

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, mention, 2 more } or SchemasMediaPartResponse { id, filename, mime_type, 3 more } or object { type, value } or 2 more

Message content parts (text and/or media)

One of the following:

SchemasTextPartResponse object { type, value, mention, 2 more }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

mention: optional string

Handle (E.164 phone number or Apple ID email) of the @mentioned chat participant, as sent. null when the part carries no mention.

mention_range: optional array of number

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

Text decorations applied to character ranges in the value

range: array of number

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

SchemasIMessageAppPartResponse object { app, layout, type, 2 more }

An iMessage app card part.

app: object { bundle_id, name, team_id, app_store_id }

Identifies the iMessage app (Messages app extension) that backs the card.

bundle_id: string

Bundle identifier of the Messages app extension.

Display name of the app.

team_id: string

The app’s 10-character team identifier.

app_store_id: optional number

The owning app’s App Store id, when known.

formatint64

Visible layout of the card.

caption: optional string

Primary label, top-left and bold.

subcaption: optional string

Secondary label, below caption on the left.

trailing_caption: optional string

Label shown top-right.

trailing_subcaption: optional string

Label shown below trailing_caption.

type: "imessage_app"

Indicates this is an iMessage app card part.

url: string

The URL the recipient’s app opens when the user taps the card.

formaturi

fallback_text: optional string

Fallback text for surfaces that cannot render the card.

SchemasAppClipPartResponse object { type, value, description, 2 more }

An Apple Pay App Clip payment card part

type: "app_clip"

Indicates this is an App Clip payment card part

value: string

The checkout link the card opens

description: optional string

The card’s summary line, composed by Linq from the checkout session

image_url: optional string

The card’s preview image

title: optional string

The card’s headline, composed by Linq from the checkout session

read_at: optional string

When the message was read

formatdate-time

reconciled_at: optional string

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)

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

type: optional "screen" or "bubble"

Effect category

One of the following:

"screen"

"bubble"

SchemasTextPartResponse object { type, value, mention, 2 more }

A text message part

type: "text"

Indicates this is a text message part

value: string

The text content

mention: optional string

Handle (E.164 phone number or Apple ID email) of the @mentioned chat participant, as sent. null when the part carries no mention.

mention_range: optional array of number

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

Text decorations applied to character ranges in the value

range: array of number

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"