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 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 MessageEventV2ChatChat information
Chat information
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.
[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 stringCurrent 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.
Your phone number’s handle. Always has is_me=true.
Your phone number’s handle. Always has is_me=true.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Direction MessageEventV2DirectionMessage direction - “outbound” if sent by you, “inbound” if received
Message direction - “outbound” if sent by you, “inbound” if received
Parts []MessageEventV2PartUnionMessage parts (text and/or media)
Message parts (text and/or media)
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MessageEventV2PartIMessageApp struct{…}An iMessage app card part.
An iMessage app card part.
SenderHandle ChatHandleThe handle that sent this message
The handle that sent this message
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
PreferredService MessageEventV2PreferredServiceOptionalPreferred 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).
type MessagePayload struct{…}Message content nested within webhook events
Message content nested within webhook events
Parts []MessagePayloadPartUnionOptionalMessage content parts (text and/or media)
Message content parts (text and/or media)
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
MessagePayloadPartSchemasIMessageAppPartResponse
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).
type ReactionEventBase struct{…}
Whether this reaction was from the owner of the phone number (true) or from someone else (false)
ReactionType ReactionTypeType 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.
The person who added/removed the reaction as a full handle object
The person who added/removed the reaction as a full handle object
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Identifier for this reaction. Pass it to
PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.
Stickers stack, so this is what distinguishes one sticker from another on the
same message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MessageSentWebhookEvent struct{…}Complete webhook payload for message.sent events (2026-02-03 format)
Complete webhook payload for message.sent events (2026-02-03 format)
Data MessageEventV2Unified 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 MessageEventV2ChatChat information
Chat information
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.
[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 stringCurrent 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.
Your phone number’s handle. Always has is_me=true.
Your phone number’s handle. Always has is_me=true.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Direction MessageEventV2DirectionMessage direction - “outbound” if sent by you, “inbound” if received
Message direction - “outbound” if sent by you, “inbound” if received
Parts []MessageEventV2PartUnionMessage parts (text and/or media)
Message parts (text and/or media)
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MessageEventV2PartIMessageApp struct{…}An iMessage app card part.
An iMessage app card part.
SenderHandle ChatHandleThe handle that sent this message
The handle that sent this message
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
PreferredService MessageEventV2PreferredServiceOptionalPreferred 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).
EventType WebhookEventTypeValid 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.
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.
type MessageReceivedWebhookEvent struct{…}Complete webhook payload for message.received events (2026-02-03 format)
Complete webhook payload for message.received events (2026-02-03 format)
Data MessageEventV2Unified 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 MessageEventV2ChatChat information
Chat information
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.
[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 stringCurrent 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.
Your phone number’s handle. Always has is_me=true.
Your phone number’s handle. Always has is_me=true.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Direction MessageEventV2DirectionMessage direction - “outbound” if sent by you, “inbound” if received
Message direction - “outbound” if sent by you, “inbound” if received
Parts []MessageEventV2PartUnionMessage parts (text and/or media)
Message parts (text and/or media)
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MessageEventV2PartIMessageApp struct{…}An iMessage app card part.
An iMessage app card part.
SenderHandle ChatHandleThe handle that sent this message
The handle that sent this message
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
PreferredService MessageEventV2PreferredServiceOptionalPreferred 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).
EventType WebhookEventTypeValid 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.
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.
type MessageReadWebhookEvent struct{…}Complete webhook payload for message.read events (2026-02-03 format)
Complete webhook payload for message.read events (2026-02-03 format)
Data MessageEventV2Unified 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 MessageEventV2ChatChat information
Chat information
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.
[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 stringCurrent 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.
Your phone number’s handle. Always has is_me=true.
Your phone number’s handle. Always has is_me=true.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Direction MessageEventV2DirectionMessage direction - “outbound” if sent by you, “inbound” if received
Message direction - “outbound” if sent by you, “inbound” if received
Parts []MessageEventV2PartUnionMessage parts (text and/or media)
Message parts (text and/or media)
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MessageEventV2PartIMessageApp struct{…}An iMessage app card part.
An iMessage app card part.
SenderHandle ChatHandleThe handle that sent this message
The handle that sent this message
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
PreferredService MessageEventV2PreferredServiceOptionalPreferred 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).
EventType WebhookEventTypeValid 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.
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.
type MessageDeliveredWebhookEvent struct{…}Complete webhook payload for message.delivered events (2026-02-03 format)
Complete webhook payload for message.delivered events (2026-02-03 format)
Data MessageEventV2Unified 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 MessageEventV2ChatChat information
Chat information
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.
[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 stringCurrent 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.
Your phone number’s handle. Always has is_me=true.
Your phone number’s handle. Always has is_me=true.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Direction MessageEventV2DirectionMessage direction - “outbound” if sent by you, “inbound” if received
Message direction - “outbound” if sent by you, “inbound” if received
Parts []MessageEventV2PartUnionMessage parts (text and/or media)
Message parts (text and/or media)
type SchemasTextPartResponse struct{…}A text message part
A text message part
DEPRECATED: Use mentions instead. Handle (E.164 phone number or Apple ID email)
of the first mention on this part. A part may carry several mentions; this
field shows only the first in value order, so it cannot be used to determine
whether a given participant was mentioned. null when the part carries no mention.
DEPRECATED: Use mentions[].range instead. Character range [start, end) in
value highlighted as the first mention only. null when the range was
omitted (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.
Mentions []SchemasTextPartResponseMentionOptionalEvery mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
Every mention on this part, in the order they appear in value. null when the
part carries no mention. A part can carry several mentions of different people —
check is_me to tell whether this line was one of them.
Only iMessage carries mentions. On a received message this is populated when the
sender was on iMessage; SMS and RCS have no way to mark a mention, so a message
from an SMS or RCS participant arrives as plain text with mentions null, even in
a group where other participants are on iMessage.
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MessageEventV2PartIMessageApp struct{…}An iMessage app card part.
An iMessage app card part.
SenderHandle ChatHandleThe handle that sent this message
The handle that sent this message
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
PreferredService MessageEventV2PreferredServiceOptionalPreferred 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).
EventType WebhookEventTypeValid 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.
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.
type MessageFailedWebhookEvent struct{…}Complete webhook payload for message.failed events
Complete webhook payload for message.failed events
Data MessageFailedWebhookEventDataError details for message.failed webhook events.
See WebhookErrorCode for the full error code reference.
In rare cases the message can still be delivered after this event fires — a message.delivered webhook for the same message ID may follow.
Error details for message.failed webhook events. See WebhookErrorCode for the full error code reference.
In rare cases the message can still be delivered after this event fires — a message.delivered webhook for the same message ID may follow.
Error codes in webhook failure events. The possible set varies by event: message.failed and poll.failed can carry 3007, 4001, 4002, 4005, 4006, 4007, or 4008; the group update failure events (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007 or 4001; chat.background_update_failed carries 1005, 2011, 4001, or 5002.
Opaque diagnostic code identifying the specific failure class within code.
Values are not enumerated and may change without notice — log it and include
it in support requests, but do not branch on it.
PreferredService stringOptionalPreferred messaging service type. Includes “auto” for default fallback behavior.
Preferred messaging service type. Includes “auto” for default fallback behavior.
EventType WebhookEventTypeValid 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.
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.
type MessageEditedWebhookEvent struct{…}Complete webhook payload for message.edited events (2026-02-03 format only)
Complete webhook payload for message.edited events (2026-02-03 format only)
Data MessageEditedWebhookEventDataPayload 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".
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".
Chat MessageEditedWebhookEventDataChatChat context
Chat context
HealthStatus MessageEditedWebhookEventDataChatHealthStatus[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 stringCurrent 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.
OwnerHandle ChatHandleThe handle that owns this chat (your phone number)
The handle that owns this chat (your phone number)
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
SenderHandle ChatHandleThe handle that sent (and edited) this message
The handle that sent (and edited) this message
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when the edited message is on a zero-day-retention line. Behavior differs by direction: on an outbound edit, part.text is empty — you already saw the real edited text once, synchronously, in the edit API response, and Linq never persists it. On an inbound edit, part.text is still the real text as received; zero-day-retention only means Linq never persists it.
EventType WebhookEventTypeValid 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.
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.
type ReactionAddedWebhookEvent struct{…}Complete webhook payload for reaction.added events
Complete webhook payload for reaction.added events
Data ReactionEventBasePayload for reaction.added webhook events
Payload for reaction.added webhook events
Whether this reaction was from the owner of the phone number (true) or from someone else (false)
ReactionType ReactionTypeType 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.
The person who added/removed the reaction as a full handle object
The person who added/removed the reaction as a full handle object
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Identifier for this reaction. Pass it to
PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.
Stickers stack, so this is what distinguishes one sticker from another on the
same message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type ReactionRemovedWebhookEvent struct{…}Complete webhook payload for reaction.removed events
Complete webhook payload for reaction.removed events
Data ReactionEventBasePayload for reaction.removed webhook events
Payload for reaction.removed webhook events
Whether this reaction was from the owner of the phone number (true) or from someone else (false)
ReactionType ReactionTypeType 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.
The person who added/removed the reaction as a full handle object
The person who added/removed the reaction as a full handle object
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Identifier for this reaction. Pass it to
PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.
Stickers stack, so this is what distinguishes one sticker from another on the
same message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type PollReceivedWebhookEvent struct{…}Complete webhook payload for poll.received events
Complete webhook payload for poll.received events
Data PollReceivedWebhookEventDataPayload for poll.received — a poll created by someone else and delivered to your line.
Carries the full poll snapshot (options, no voters yet) at receipt time.
Payload for poll.received — a poll created by someone else and delivered to your line. Carries the full poll snapshot (options, no voters yet) at receipt time.
Chat PollReceivedWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Poll PollReceivedWebhookEventDataPoll
Options []PollReceivedWebhookEventDataPollOption
CreatorHandle ChatHandleThe participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
The participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
The line that created the poll (is_me=false for an inbound poll).
The line that created the poll (is_me=false for an inbound poll).
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when your line has zero-day-retention enabled. Unlike other poll webhooks, option text here is still the real, unstripped text as received — Linq never persists it in the database, but this webhook fires from the live inbound event, not a database read, so this is the one place it’s shown.
EventType WebhookEventTypeValid 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.
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.
type PollSentWebhookEvent struct{…}Complete webhook payload for poll.sent events
Complete webhook payload for poll.sent events
Data PollSentWebhookEventDataPayload for poll.sent, poll.delivered, and poll.read webhook events. Timestamps indicate
state (null = not yet happened): sent → sent_at; delivered → +delivered_at; read → +read_at.
Payload for poll.sent, poll.delivered, and poll.read webhook events. Timestamps indicate state (null = not yet happened): sent → sent_at; delivered → +delivered_at; read → +read_at.
Chat PollSentWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Poll PollSentWebhookEventDataPoll
Options []PollSentWebhookEventDataPollOption
CreatorHandle ChatHandleThe participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
The participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
The handle that sent the poll.
The handle that sent the poll.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when this poll was sent on a zero-day-retention line. Every option’s text is empty in that case — Linq never persists poll option text, so there is nothing to include here. The real text was only ever shown once, synchronously, in the API response when the poll was created or added to.
EventType WebhookEventTypeValid 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.
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.
type PollDeliveredWebhookEvent struct{…}Complete webhook payload for poll.delivered events
Complete webhook payload for poll.delivered events
Data PollDeliveredWebhookEventDataPayload for poll.sent, poll.delivered, and poll.read webhook events. Timestamps indicate
state (null = not yet happened): sent → sent_at; delivered → +delivered_at; read → +read_at.
Payload for poll.sent, poll.delivered, and poll.read webhook events. Timestamps indicate state (null = not yet happened): sent → sent_at; delivered → +delivered_at; read → +read_at.
Chat PollDeliveredWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Poll PollDeliveredWebhookEventDataPoll
Options []PollDeliveredWebhookEventDataPollOption
CreatorHandle ChatHandleThe participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
The participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
The handle that sent the poll.
The handle that sent the poll.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when this poll was sent on a zero-day-retention line. Every option’s text is empty in that case — Linq never persists poll option text, so there is nothing to include here. The real text was only ever shown once, synchronously, in the API response when the poll was created or added to.
EventType WebhookEventTypeValid 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.
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.
type PollReadWebhookEvent struct{…}Complete webhook payload for poll.read events
Complete webhook payload for poll.read events
Data PollReadWebhookEventDataPayload for poll.sent, poll.delivered, and poll.read webhook events. Timestamps indicate
state (null = not yet happened): sent → sent_at; delivered → +delivered_at; read → +read_at.
Payload for poll.sent, poll.delivered, and poll.read webhook events. Timestamps indicate state (null = not yet happened): sent → sent_at; delivered → +delivered_at; read → +read_at.
Chat PollReadWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Poll PollReadWebhookEventDataPoll
Options []PollReadWebhookEventDataPollOption
CreatorHandle ChatHandleThe participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
The participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
The handle that sent the poll.
The handle that sent the poll.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when this poll was sent on a zero-day-retention line. Every option’s text is empty in that case — Linq never persists poll option text, so there is nothing to include here. The real text was only ever shown once, synchronously, in the API response when the poll was created or added to.
EventType WebhookEventTypeValid 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.
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.
type PollUpdatedWebhookEvent struct{…}Complete webhook payload for poll.updated events
Complete webhook payload for poll.updated events
Data PollUpdatedWebhookEventDataPayload for poll.updated (option(s) added — add-only).
Payload for poll.updated (option(s) added — add-only).
AddedOptions []PollUpdatedWebhookEventDataAddedOptionOnly the options this update added — never the ones the poll already had. Fetch the poll to read its full option set.
Only the options this update added — never the ones the poll already had. Fetch the poll to read its full option set.
CreatorHandle ChatHandleThe participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
The participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Chat PollUpdatedWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
SenderHandle ChatHandleYour line — the one that received or sent this update. Always present. On an inbound
update this is NOT who added the option: use added_options[].creator_handle for
that, which will be the remote participant.
Your line — the one that received or sent this update. Always present. On an inbound
update this is NOT who added the option: use added_options[].creator_handle for
that, which will be the remote participant.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when zero-day-retention applies to this update. Behavior differs by direction: on an inbound update, added_options[].text is the real text a participant just added; on an outbound update, it is empty — you already saw the real text once, synchronously, in the API response when you made the add, and this webhook is built from a database read, which never stored it.
EventType WebhookEventTypeValid 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.
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.
type PollFailedWebhookEvent struct{…}Complete webhook payload for poll.failed events
Complete webhook payload for poll.failed events
Data PollFailedWebhookEventDataPayload for poll.failed — an outbound poll (or poll action) that failed to send. Carries the
poll snapshot at failure time plus the error and when it failed.
Payload for poll.failed — an outbound poll (or poll action) that failed to send. Carries the poll snapshot at failure time plus the error and when it failed.
Chat PollFailedWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Error PollFailedWebhookEventDataError
Error codes in webhook failure events. The possible set varies by event: message.failed and poll.failed can carry 3007, 4001, 4002, 4005, 4006, 4007, or 4008; the group update failure events (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007 or 4001; chat.background_update_failed carries 1005, 2011, 4001, or 5002.
Poll PollFailedWebhookEventDataPoll
Options []PollFailedWebhookEventDataPollOption
CreatorHandle ChatHandleThe participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
The participant who added this option (poll creator for the initial options; whoever
added later ones). On a poll.updated this differs from the event’s sender_handle
whenever a remote participant added the option. Null when unknown.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Null on failure (the send never landed).
Null on failure (the send never landed).
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type PollVoteAddedWebhookEvent struct{…}Complete webhook payload for poll.vote.added events
Complete webhook payload for poll.vote.added events
Data PollVoteAddedWebhookEventDataPayload for poll.vote.added and poll.vote.removed (one option toggled).
Payload for poll.vote.added and poll.vote.removed (one option toggled).
Chat PollVoteAddedWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
SenderHandle ChatHandleThe voter — always present.
The voter — always present.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when this poll is on a zero-day-retention line. Votes are unaffected by zero-day-retention — a vote choice is always persisted and delivered regardless — this flag is informational only, telling you why this poll’s other webhooks (poll.sent, poll.updated, etc.) may carry empty option text.
EventType WebhookEventTypeValid 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.
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.
type PollVoteRemovedWebhookEvent struct{…}Complete webhook payload for poll.vote.removed events
Complete webhook payload for poll.vote.removed events
Data PollVoteRemovedWebhookEventDataPayload for poll.vote.added and poll.vote.removed (one option toggled).
Payload for poll.vote.added and poll.vote.removed (one option toggled).
Chat PollVoteRemovedWebhookEventDataChatChat info for poll webhook events.
Chat info for poll webhook events.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
SenderHandle ChatHandleThe voter — always present.
The voter — always present.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
True when this poll is on a zero-day-retention line. Votes are unaffected by zero-day-retention — a vote choice is always persisted and delivered regardless — this flag is informational only, telling you why this poll’s other webhooks (poll.sent, poll.updated, etc.) may carry empty option text.
EventType WebhookEventTypeValid 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.
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.
type PollReactionAddedWebhookEvent struct{…}Complete webhook payload for poll.reaction.added events
Complete webhook payload for poll.reaction.added events
Data ReactionEventBasePayload for poll.reaction.added — a reaction on a poll message. Same shape as
reaction.added; message_id is the poll-definition message’s ID. Poll reactions are
stickers, which iMessage cannot remove, so there is no removal counterpart.
Payload for poll.reaction.added — a reaction on a poll message. Same shape as
reaction.added; message_id is the poll-definition message’s ID. Poll reactions are
stickers, which iMessage cannot remove, so there is no removal counterpart.
Whether this reaction was from the owner of the phone number (true) or from someone else (false)
ReactionType ReactionTypeType 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.
The person who added/removed the reaction as a full handle object
The person who added/removed the reaction as a full handle object
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Identifier for this reaction. Pass it to
PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.
Stickers stack, so this is what distinguishes one sticker from another on the
same message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type ParticipantAddedWebhookEvent struct{…}Complete webhook payload for participant.added events
Complete webhook payload for participant.added events
Data ParticipantAddedWebhookEventDataPayload for participant.added webhook events
Payload for participant.added webhook events
DEPRECATED: Use participant instead. Handle (phone number or email address) of the added participant.
The added participant as a full handle object
The added participant as a full handle object
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type ParticipantRemovedWebhookEvent struct{…}Complete webhook payload for participant.removed events
Complete webhook payload for participant.removed events
Data ParticipantRemovedWebhookEventDataPayload for participant.removed webhook events
Payload for participant.removed webhook events
DEPRECATED: Use participant instead. Handle (phone number or email address) of the removed participant.
The removed participant as a full handle object
The removed participant as a full handle object
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type ChatCreatedWebhookEvent struct{…}Complete webhook payload for chat.created events
Complete webhook payload for chat.created events
Data ChatCreatedWebhookEventDataPayload for chat.created webhook events. Matches GET /v3/chats/{chatId} response.
Payload for chat.created webhook events. Matches GET /v3/chats/{chatId} response.
Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.
Handles []ChatHandleList of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).
List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
HealthStatus ChatCreatedWebhookEventDataHealthStatus[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 stringCurrent 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.
EventType WebhookEventTypeValid 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.
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.
type ChatGroupNameUpdatedWebhookEvent struct{…}Complete webhook payload for chat.group_name_updated events
Complete webhook payload for chat.group_name_updated events
Data ChatGroupNameUpdatedWebhookEventDataPayload for chat.group_name_updated webhook events
Payload for chat.group_name_updated webhook events
The handle who made the change.
The handle who made the change.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type ChatGroupIconUpdatedWebhookEvent struct{…}Complete webhook payload for chat.group_icon_updated events
Complete webhook payload for chat.group_icon_updated events
Data ChatGroupIconUpdatedWebhookEventDataPayload for chat.group_icon_updated webhook events
Payload for chat.group_icon_updated webhook events
The handle who made the change.
The handle who made the change.
Service ServiceTypeMessaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
Messaging service type. Where this names the transport a message used,
it is per-message: a chat’s own service can differ from a message in
it, and Apple can downgrade an individual message.
EventType WebhookEventTypeValid 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.
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.
type ChatGroupNameUpdateFailedWebhookEvent struct{…}Complete webhook payload for chat.group_name_update_failed events
Complete webhook payload for chat.group_name_update_failed events
Data ChatGroupNameUpdateFailedWebhookEventDataError details for chat.group_name_update_failed webhook events.
See WebhookErrorCode for the full error code reference.
Error details for chat.group_name_update_failed webhook events. See WebhookErrorCode for the full error code reference.
Error codes in webhook failure events. The possible set varies by event: message.failed and poll.failed can carry 3007, 4001, 4002, 4005, 4006, 4007, or 4008; the group update failure events (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007 or 4001; chat.background_update_failed carries 1005, 2011, 4001, or 5002.
EventType WebhookEventTypeValid 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.
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.
type ChatGroupIconUpdateFailedWebhookEvent struct{…}Complete webhook payload for chat.group_icon_update_failed events
Complete webhook payload for chat.group_icon_update_failed events
Data ChatGroupIconUpdateFailedWebhookEventDataError details for chat.group_icon_update_failed webhook events.
See WebhookErrorCode for the full error code reference.
Error details for chat.group_icon_update_failed webhook events. See WebhookErrorCode for the full error code reference.
Error codes in webhook failure events. The possible set varies by event: message.failed and poll.failed can carry 3007, 4001, 4002, 4005, 4006, 4007, or 4008; the group update failure events (chat.group_name_update_failed, chat.group_icon_update_failed) carry 3007 or 4001; chat.background_update_failed carries 1005, 2011, 4001, or 5002.
EventType WebhookEventTypeValid 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.
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.
type ChatTypingIndicatorStartedWebhookEvent struct{…}Complete webhook payload for chat.typing_indicator.started events
Complete webhook payload for chat.typing_indicator.started events
Data ChatTypingIndicatorStartedWebhookEventDataPayload for chat.typing_indicator.started webhook events
Payload for chat.typing_indicator.started webhook events
EventType WebhookEventTypeValid 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.
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.