Webhooks
ModelsExpand Collapse
class MessageEventV2: …Unified payload for message webhooks when using webhook_version: "2026-02-03".
This schema is used for message.sent, message.received, message.delivered, and message.read
events when the subscription URL includes ?version=2026-02-03.
Key differences from V1 (2025-01-01):
direction: “inbound” or “outbound” instead of is_from_me booleansender_handle: Full handle object for the senderchat: 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=nullmessage.received: sent_at set, delivered_at=null, read_at=nullmessage.delivered: sent_at set, delivered_at set, read_at=nullmessage.read: sent_at set, delivered_at set, read_at set
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 ofis_from_mebooleansender_handle: Full handle object for the senderchat: Nested object withid,is_group, andowner_handle- Message fields (
id,parts,effect, etc.) are at the top level, not nested inmessage
Timestamps indicate the message state:
message.sent: sent_at set, delivered_at=null, read_at=nullmessage.received: sent_at set, delivered_at=null, read_at=nullmessage.delivered: sent_at set, delivered_at set, read_at=nullmessage.read: sent_at set, delivered_at set, read_at set
chat: ChatChat information
Chat information
health_status: ChatHealthStatus[BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.
Switch on status to 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.
[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.
status: Literal["HEALTHY", "AT_RISK", "CRITICAL", "OPTED_OUT"]Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.
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.
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.
direction: Literal["inbound", "outbound"]Message direction - “outbound” if sent by you, “inbound” if received
Message direction - “outbound” if sent by you, “inbound” if received
parts: List[Part]Message parts (text and/or media)
Message parts (text and/or media)
class SchemasTextPartResponse: …A text message part
A text message part
Handle (E.164 phone number or Apple ID email) of the @mentioned chat participant,
as sent. null when the part carries no mention.
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 applied to character ranges in the value
Text decorations applied to character ranges in the value
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.
class PartSchemasIMessageAppPartResponse: …An iMessage app card part.
An iMessage app card part.
When the message was delivered. Null if not yet delivered.
effect: Optional[SchemasMessageEffect]iMessage effect applied to a message (screen or bubble animation)
iMessage effect applied to a message (screen or bubble animation)
preferred_service: Optional[Literal["iMessage", "SMS", "RCS", "auto"]]Preferred messaging service type. Includes “auto” for default fallback behavior.
Preferred messaging service type. Includes “auto” for default fallback behavior.
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).
class MessagePayload: …Message content nested within webhook events
Message content nested within webhook events
effect: Optional[SchemasMessageEffect]iMessage effect applied to a message (screen or bubble animation)
iMessage effect applied to a message (screen or bubble animation)
parts: Optional[List[Part]]Message content parts (text and/or media)
Message content parts (text and/or media)
class SchemasTextPartResponse: …A text message part
A text message part
Handle (E.164 phone number or Apple ID email) of the @mentioned chat participant,
as sent. null when the part carries no mention.
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 applied to character ranges in the value
Text decorations applied to character ranges in the value
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.
class PartSchemasIMessageAppPartResponse: …An iMessage app card part.
An iMessage app card part.
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).
class ReactionEventBase: …
Whether this reaction was from the owner of the phone number (true) or from someone else (false)
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.
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.
The actual emoji when reaction_type is “custom”. Null for standard tapbacks.
DEPRECATED: Use from_handle instead. Phone number or email address of the person who added/removed the reaction.
from_handle: Optional[ChatHandle]The person who added/removed the reaction as a full handle object
The person who added/removed the reaction as a full handle object
class SchemasTextPartResponse: …A text message part
A text message part
Handle (E.164 phone number or Apple ID email) of the @mentioned chat participant,
as sent. null when the part carries no mention.
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 applied to character ranges in the value
Text decorations applied to character ranges in the value
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.