Webhooks

ModelsExpand Collapse

type MessageEventV2 struct{…}

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 MessageEventV2Chat

Chat information

ID string

Chat identifier

formatuuid

HealthStatus MessageEventV2ChatHealthStatus

[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.

DocURL string

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

formaturi

Status string

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:

const MessageEventV2ChatHealthStatusStatusHealthy MessageEventV2ChatHealthStatusStatus = "HEALTHY"

const MessageEventV2ChatHealthStatusStatusAtRisk MessageEventV2ChatHealthStatusStatus = "AT_RISK"

const MessageEventV2ChatHealthStatusStatusCritical MessageEventV2ChatHealthStatusStatus = "CRITICAL"

const MessageEventV2ChatHealthStatusStatusOptedOut MessageEventV2ChatHealthStatusStatus = "OPTED_OUT"

UpdatedAt Time

When this status last changed.

formatdate-time

IsGroup boolOptional

Whether this is a group chat

OwnerHandle ChatHandleOptional

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

JoinedAt Time

When this participant joined the chat

formatdate-time

Service ServiceType

Messaging service type

One of the following:

const ServiceTypeIMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

IsMe boolOptional

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

LeftAt TimeOptional

When they left (if applicable)

formatdate-time

Status ChatHandleStatusOptional

Participant status

One of the following:

const ChatHandleStatusActive ChatHandleStatus = "active"

const ChatHandleStatusLeft ChatHandleStatus = "left"

const ChatHandleStatusRemoved ChatHandleStatus = "removed"

Direction MessageEventV2Direction

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

One of the following:

const MessageEventV2DirectionInbound MessageEventV2Direction = "inbound"

const MessageEventV2DirectionOutbound MessageEventV2Direction = "outbound"

Parts []MessageEventV2PartUnion

Message parts (text and/or media)

One of the following:

type SchemasTextPartResponse struct{…}

A text message part

Type SchemasTextPartResponseType

Indicates this is a text message part

Value string

The text content

Mention stringOptional

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

MentionRange []int64Optional

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.

TextDecorations []TextDecorationOptional

Text decorations applied to character ranges in the value

Range []int64

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 TextDecorationAnimationOptional

Animated text effect to apply. Mutually exclusive with style.

One of the following:

const TextDecorationAnimationBig TextDecorationAnimation = "big"

const TextDecorationAnimationSmall TextDecorationAnimation = "small"

const TextDecorationAnimationShake TextDecorationAnimation = "shake"

const TextDecorationAnimationNod TextDecorationAnimation = "nod"

const TextDecorationAnimationExplode TextDecorationAnimation = "explode"

const TextDecorationAnimationRipple TextDecorationAnimation = "ripple"

const TextDecorationAnimationBloom TextDecorationAnimation = "bloom"

const TextDecorationAnimationJitter TextDecorationAnimation = "jitter"

Style TextDecorationStyleOptional

Text style to apply. Mutually exclusive with animation.

One of the following:

const TextDecorationStyleBold TextDecorationStyle = "bold"

const TextDecorationStyleItalic TextDecorationStyle = "italic"

const TextDecorationStyleStrikethrough TextDecorationStyle = "strikethrough"

const TextDecorationStyleUnderline TextDecorationStyle = "underline"

type SchemasMediaPartResponse struct{…}

A media attachment part

ID string

Unique attachment identifier

formatuuid

Filename string

Original filename

MimeType string

MIME type of the file

SizeBytes int64

File size in bytes

Type SchemasMediaPartResponseType

Indicates this is a media attachment part

URL string

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

formaturi

MessageEventV2PartLink

Type Link

Indicates this is a rich link preview part

Value string

The URL

MessageEventV2PartIMessageApp

App MessageEventV2PartIMessageAppApp

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

BundleID string

Bundle identifier of the Messages app extension.

Name string

Display name of the app.

TeamID string

The app’s 10-character team identifier.

AppStoreID int64Optional

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

formatint64

Layout MessageEventV2PartIMessageAppLayout

Visible layout of the card.

Caption stringOptional

Primary label, top-left and bold.

Subcaption stringOptional

Secondary label, below caption on the left.

TrailingCaption stringOptional

Label shown top-right.

TrailingSubcaption stringOptional

Label shown below trailing_caption.

Type IMessageApp

Indicates this is an iMessage app card part.

URL string

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

formaturi

FallbackText stringOptional

Fallback text for surfaces that cannot render the card.

MessageEventV2PartAppClip

Type AppClip

Indicates this is an App Clip payment card part

Value string

The checkout link the card opens

Description stringOptional

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

ImageURL stringOptional

The card’s preview image

Title stringOptional

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

SenderHandle ChatHandle

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

JoinedAt Time

When this participant joined the chat

formatdate-time

Service ServiceType

Messaging service type

One of the following:

const ServiceTypeIMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

IsMe boolOptional

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

LeftAt TimeOptional

When they left (if applicable)

formatdate-time

Status ChatHandleStatusOptional

Participant status

One of the following:

const ChatHandleStatusActive ChatHandleStatus = "active"

const ChatHandleStatusLeft ChatHandleStatus = "left"

const ChatHandleStatusRemoved ChatHandleStatus = "removed"

Service ServiceType

Messaging service type

One of the following:

const ServiceTypeIMessage ServiceType = "iMessage"

const ServiceTypeSMS ServiceType = "SMS"

const ServiceTypeRCS ServiceType = "RCS"

DeliveredAt TimeOptional

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

formatdate-time

Effect SchemasMessageEffectOptional

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

Name stringOptional

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

Type SchemasMessageEffectTypeOptional

Effect category

One of the following:

const SchemasMessageEffectTypeScreen SchemasMessageEffectType = "screen"

const SchemasMessageEffectTypeBubble SchemasMessageEffectType = "bubble"

IdempotencyKey stringOptional

Idempotency key for deduplication of outbound messages.

PreferredService MessageEventV2PreferredServiceOptional

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

One of the following:

const MessageEventV2PreferredServiceIMessage MessageEventV2PreferredService = "iMessage"

const MessageEventV2PreferredServiceSMS MessageEventV2PreferredService = "SMS"

const MessageEventV2PreferredServiceRCS MessageEventV2PreferredService = "RCS"

const MessageEventV2PreferredServiceAuto MessageEventV2PreferredService = "auto"

ReadAt TimeOptional

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

formatdate-time

ReconciledAt TimeOptional

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

ReplyTo MessageEventV2ReplyToOptional

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

MessageID stringOptional

ID of the message being replied to

formatuuid

PartIndex int64Optional

Index of the part being replied to

formatint32

minimum0

SentAt TimeOptional

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

formatdate-time

type MessagePayload struct{…}

Message content nested within webhook events

ID stringOptional

Message identifier

formatuuid

CreatedAt TimeOptional

When the message record was created

formatdate-time

DeliveredAt TimeOptional

When the message was delivered

formatdate-time

Effect SchemasMessageEffectOptional

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

Name stringOptional

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

Type SchemasMessageEffectTypeOptional

Effect category

One of the following:

const SchemasMessageEffectTypeScreen SchemasMessageEffectType = "screen"

const SchemasMessageEffectTypeBubble SchemasMessageEffectType = "bubble"

IsDelivered boolOptional

Whether the message has been delivered

IsRead boolOptional

Whether the message has been read

Parts []MessagePayloadPartUnionOptional

Message content parts (text and/or media)