Chats
Create a new chat
List all chats
Get a chat by ID
Update a chat
Mark chat as read
Leave a group chat
Share your contact card with a chat
Send a voice memo to a chat
ModelsExpand Collapse
Chat object { id, created_at, display_name, 7 more }
Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.
List 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).
health_status: object { doc_url, status, updated_at } [BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.
Switch on status to gate sends or surface 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.
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 gate sends or surface 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.
See the Chat Health guide for what each status means and how to react.
status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.
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.
DEPRECATED: This field is deprecated and will be removed in a future API version.
URL of the group chat icon. Only set for group chats that have an icon; null otherwise.
LinkPart object { type, value }
URL to send with a rich link preview. The recipient will see an inline card with the page’s title, description, and preview image (when available).
A link part must be the only part in the message. To send a URL as plain
text (no preview card), use a text part instead.
MediaPart object { type, attachment_id, url }
Reference to a file pre-uploaded via POST /v3/attachments (optional).
The file is already stored, so sends using this ID skip the download step —
useful when sending the same file to many recipients.
Either url or attachment_id must be provided, but not both.
Any publicly accessible HTTPS URL to the media file. The server downloads and sends the file automatically — no pre-upload step required.
Size limit: 10MB maximum for URL-based downloads. For larger files (up to 100MB),
use the pre-upload flow: POST /v3/attachments to get a presigned URL, upload directly,
then reference by attachment_id.
Requirements:
- URL must use HTTPS
- File content must be a supported format (the server validates the actual file content)
Supported formats:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Tip: Audio sent here appears as a regular file attachment. To send audio as an
iMessage voice memo bubble (with inline playback), use /v3/chats/{chatId}/voicememo.
For repeated sends of the same file, use attachment_id to avoid redundant downloads.
Either url or attachment_id must be provided, but not both.
MessageContent object { parts, effect, idempotency_key, 2 more } Message content container. Groups all message-related fields together,
separating the “what” (message content) from the “where” (routing fields like from/to).
Message content container. Groups all message-related fields together, separating the “what” (message content) from the “where” (routing fields like from/to).
parts: array of TextPart { type, value, text_decorations } or MediaPart { type, attachment_id, url } or LinkPart { type, value } or object { app, layout, type, 3 more } Array of message parts. Each part can be text, media, or link.
Parts are displayed in order. Text and media can be mixed freely,
but a link part must be the only part in the message.
Rich Link Previews:
- Use a
link part to send a URL with a rich preview card
- A
link part must be the only part in the message
- To send a URL as plain text (no preview), use a
text part instead
Supported Media:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Audio:
- Audio files (.m4a, .mp3, .aac, .caf, .wav, .aiff, .amr) are fully supported as media parts
- To send audio as an iMessage voice memo bubble (inline playback UI), use the dedicated
/v3/chats/{chatId}/voicememo endpoint instead
Validation Rules:
- A
link part must be the only part in the message. It cannot be combined
with text or media parts.
- Consecutive text parts are not allowed. Text parts must be separated by
media parts. For example, [text, text] is invalid, but [text, media, text] is valid.
- Maximum of 100 parts total.
- Media parts using a public
url (downloaded by the server on send) are
capped at 40. Parts using attachment_id or presigned URLs
are exempt from this sub-limit. For bulk media sends exceeding 40 files,
pre-upload via POST /v3/attachments and reference by attachment_id or download_url.
Array of message parts. Each part can be text, media, or link.
Parts are displayed in order. Text and media can be mixed freely,
but a link part must be the only part in the message.
Rich Link Previews:
- Use a
linkpart to send a URL with a rich preview card - A
linkpart must be the only part in the message - To send a URL as plain text (no preview), use a
textpart instead
Supported Media:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Audio:
- Audio files (.m4a, .mp3, .aac, .caf, .wav, .aiff, .amr) are fully supported as media parts
- To send audio as an iMessage voice memo bubble (inline playback UI), use the dedicated
/v3/chats/{chatId}/voicememoendpoint instead
Validation Rules:
- A
linkpart must be the only part in the message. It cannot be combined with text or media parts. - Consecutive text parts are not allowed. Text parts must be separated by media parts. For example, [text, text] is invalid, but [text, media, text] is valid.
- Maximum of 100 parts total.
- Media parts using a public
url(downloaded by the server on send) are capped at 40. Parts usingattachment_idor presigned URLs are exempt from this sub-limit. For bulk media sends exceeding 40 files, pre-upload viaPOST /v3/attachmentsand reference byattachment_idordownload_url.
TextPart object { type, value, text_decorations }
The text content of the message. This value is sent as-is with no parsing or transformation — Markdown syntax will be delivered as plain text. Use text_decorations to apply inline formatting and animations (iMessage only).
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
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.
MediaPart object { type, attachment_id, url }
Reference to a file pre-uploaded via POST /v3/attachments (optional).
The file is already stored, so sends using this ID skip the download step —
useful when sending the same file to many recipients.
Either url or attachment_id must be provided, but not both.
Any publicly accessible HTTPS URL to the media file. The server downloads and sends the file automatically — no pre-upload step required.
Size limit: 10MB maximum for URL-based downloads. For larger files (up to 100MB),
use the pre-upload flow: POST /v3/attachments to get a presigned URL, upload directly,
then reference by attachment_id.
Requirements:
- URL must use HTTPS
- File content must be a supported format (the server validates the actual file content)
Supported formats:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Tip: Audio sent here appears as a regular file attachment. To send audio as an
iMessage voice memo bubble (with inline playback), use /v3/chats/{chatId}/voicememo.
For repeated sends of the same file, use attachment_id to avoid redundant downloads.
Either url or attachment_id must be provided, but not both.
LinkPart object { type, value }
URL to send with a rich link preview. The recipient will see an inline card with the page’s title, description, and preview image (when available).
A link part must be the only part in the message. To send a URL as plain
text (no preview card), use a text part instead.
IMessageApp object { app, layout, type, 3 more } An iMessage app card, backed by a Messages app extension. iMessage only —
an imessage_app part must be the only part in the message and is never delivered over
SMS/RCS. See the IMessageAppServiceUnsupported (2018) and RecipientUnsupportedMessageType
(4005) error codes.
An iMessage app card, backed by a Messages app extension. iMessage only —
an imessage_app part must be the only part in the message and is never delivered over
SMS/RCS. See the IMessageAppServiceUnsupported (2018) and RecipientUnsupportedMessageType
(4005) error codes.
app: object { bundle_id, name, team_id, app_store_id } Identifies the iMessage app (Messages app extension) that backs the card.
Identifies the iMessage app (Messages app extension) that backs the card.
layout: object { caption, image_subtitle, image_title, 4 more } Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Text shown below image_title, overlaid on the card image. Requires image_url.
Bold text overlaid on the card image. Requires image_url (rejected without it).
Text shown on surfaces that cannot render the card (notifications, lock screen). Defaults to the caption when omitted.
Whether the card renders as your app’s interactive balloon for recipients who have your
iMessage app installed. true (default) lets your installed extension draw its live,
interactive view for those recipients; everyone else sees the static card built from
layout. false always shows the static layout card, even to recipients who have the
app installed. Recipients without your app always see the static card regardless of this
flag.
iMessage effect to apply to this message (screen or bubble effect)
iMessage effect to apply to this message (screen or bubble effect)
Optional idempotency key for this message. Use this to prevent duplicate sends of the same message.
TextPart object { type, value, text_decorations }
The text content of the message. This value is sent as-is with no parsing or transformation — Markdown syntax will be delivered as plain text. Use text_decorations to apply inline formatting and animations (iMessage only).
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
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.
ChatCreateResponse object { chat } Response for creating a new chat with an initial message
Response for creating a new chat with an initial message
chat: object { id, display_name, handles, 4 more }
Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.
List of participants in the chat. Always contains at least two handles (your phone number and the other participant).
List of participants in the chat. Always contains at least two handles (your phone number and the other participant).
health_status: object { doc_url, status, updated_at } [BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.
Switch on status to gate sends or surface 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.
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 gate sends or surface 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.
See the Chat Health guide for what each status means and how to react.
status: "HEALTHY" or "AT_RISK" or "CRITICAL" or "OPTED_OUT"Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.
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.
A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.
parts: array of TextPartResponse { reactions, type, value, text_decorations } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value } or object { app, layout, reactions, 3 more } Message parts in order (text, media, and link)
Message parts in order (text, media, and link)
TextPartResponse object { reactions, type, value, text_decorations } A text message part
A text message part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
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.
MediaPartResponse object { id, filename, mime_type, 4 more } A media attachment part
A media attachment part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
LinkPartResponse object { reactions, type, value } A rich link preview part
A rich link preview part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
IMessageAppPartResponse object { app, layout, reactions, 3 more } An iMessage app card part.
An iMessage app card part.
app: object { bundle_id, name, team_id, app_store_id } Identifies the iMessage app (Messages app extension) that backs the card.
Identifies the iMessage app (Messages app extension) that backs the card.
layout: object { caption, image_subtitle, image_title, 4 more } Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Text shown below image_title, overlaid on the card image. Requires image_url.
Bold text overlaid on the card image. Requires image_url (rejected without it).
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)
ChatSendVoicememoResponse object { voice_memo } Response for sending a voice memo to a chat
Response for sending a voice memo to a chat
ChatsParticipants
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
user@example.com - No spaces, dashes, or parentheses in phone numbers
Add a participant to a chat
Remove a participant from a chat
ChatsTyping
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
user@example.com - No spaces, dashes, or parentheses in phone numbers
Start typing indicator
Stop typing indicator
ChatsMessages
Messages are individual communications within a chat thread.
Messages can include text, media attachments, rich link previews, special effects (like confetti or fireworks), and reactions. All messages are associated with a specific chat and sent from a phone number you own.
Messages support delivery status tracking, read receipts, and editing capabilities.
Rich Link Previews
Send a URL as a link part to deliver it with a rich preview card showing the
page’s title, description, and image (when available). A link part must be the
only part in the message — it cannot be combined with text or media parts.
To send a URL without a preview card, include it in a text part instead.
Limitations:
- A
linkpart cannot be combined with other parts in the same message. - Maximum URL length: 2,048 characters.
Ephemeral Messages (Privacy Tier)
For regulated or sensitive conversations, opt in to the ephemeral messages tier by contacting your Linq support contact. When enabled, every message on the covered phone numbers is automatically given a fixed 24-hour retention window — after that window the platform permanently deletes the message from Linq storage. There is no per-message flag; ephemerality is applied automatically based on your configuration.
You can request it at two scopes:
| Scope | Effect |
|---|---|
| Partner-wide | Every outbound and inbound message on every phone number under your account is retained for 24 hours, then deleted. |
| Per phone number | Only the specified phone numbers have their messages auto-deleted. The rest follow the standard message-retention policy. |
Behavioral differences vs the standard default:
| Aspect | Standard | Ephemeral |
|---|---|---|
| Retention | Retained per the standard message-retention policy | Hard backstop: 24 hours from when the message is created |
| After expiry | Message stays retrievable | Message is permanently deleted — GET /v3/messages/{messageId} returns 404 and it no longer appears in GET /v3/chats/{chatId}/messages |
| Content on expiry | N/A | Text, formatting, and attachment references are scrubbed; the message is gone, not blanked out |
| Cross-partner isolation | Enforced | Enforced |
How the 24-hour window works:
- The window is fixed at 24 hours from message creation (
created_at) and cannot be configured per message. - It mirrors the ephemeral attachments 1-day backstop, so a message and any media it carries expire together.
- Expiry is delivery-independent — the clock starts when the message is created, not when it is delivered or read.
What you observe:
- No expiry timestamp is exposed. API responses and webhook payloads do not include the deletion time. If you need it, compute
created_at + 24hyourself. - No deletion webhook is sent. There is no
message.deletedevent — a message simply stops being retrievable once its window passes. - Delivery is unaffected. Ephemeral messages send, deliver, and fire the usual
message.sent/message.receivedand status webhooks exactly like standard messages. Only retention changes.
When to choose ephemeral:
- You have a compliance requirement that the platform must not retain message content beyond a short window.
- The conversation is high-sensitivity (PHI, financial, identity verification) and you do not want it sitting in storage long-term.
- Your application is the system of record — you capture what you need from the delivery webhook in real time and do not rely on reading message history back from Linq later.
Important: ephemeral applies in both directions — messages you send and messages received by the phone numbers in that scope. Because Linq can no longer return the message after 24 hours, persist anything you need to keep from the webhook payload at the time it is delivered.
Send a message to an existing chat
Get messages from a chat
ModelsExpand Collapse
SentMessage object { id, created_at, delivery_status, 9 more } A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.
parts: array of TextPartResponse { reactions, type, value, text_decorations } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value } or object { app, layout, reactions, 3 more } Message parts in order (text, media, and link)
Message parts in order (text, media, and link)
TextPartResponse object { reactions, type, value, text_decorations } A text message part
A text message part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
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.
MediaPartResponse object { id, filename, mime_type, 4 more } A media attachment part
A media attachment part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
LinkPartResponse object { reactions, type, value } A rich link preview part
A rich link preview part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
IMessageAppPartResponse object { app, layout, reactions, 3 more } An iMessage app card part.
An iMessage app card part.
app: object { bundle_id, name, team_id, app_store_id } Identifies the iMessage app (Messages app extension) that backs the card.
Identifies the iMessage app (Messages app extension) that backs the card.
layout: object { caption, image_subtitle, image_title, 4 more } Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Text shown below image_title, overlaid on the card image. Requires image_url.
Bold text overlaid on the card image. Requires image_url (rejected without it).
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)
MessageSendResponse object { chat_id, message } Response for sending a message to a chat
Response for sending a message to a chat
A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.
parts: array of TextPartResponse { reactions, type, value, text_decorations } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value } or object { app, layout, reactions, 3 more } Message parts in order (text, media, and link)
Message parts in order (text, media, and link)
TextPartResponse object { reactions, type, value, text_decorations } A text message part
A text message part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
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.
MediaPartResponse object { id, filename, mime_type, 4 more } A media attachment part
A media attachment part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
LinkPartResponse object { reactions, type, value } A rich link preview part
A rich link preview part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
IMessageAppPartResponse object { app, layout, reactions, 3 more } An iMessage app card part.
An iMessage app card part.
app: object { bundle_id, name, team_id, app_store_id } Identifies the iMessage app (Messages app extension) that backs the card.
Identifies the iMessage app (Messages app extension) that backs the card.
layout: object { caption, image_subtitle, image_title, 4 more } Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Visible layout of the card. At least one of
caption, subcaption, trailing_caption, trailing_subcaption, or image_url must be
set, otherwise the card renders as an empty bubble.
image_url displays a preview image at the top of the card. The image renders on the
recipient’s card whether or not they have your app installed. The small icon beside the
caption is the app’s own icon and is not settable here.
* Note - requires a trusted chat w/ inbound activity
image_title and image_subtitle render as text overlaid on the image (title bold, subtitle
beneath it). They only appear when image_url is set — without an image there is nothing to
overlay — so setting either without image_url is rejected.
Text shown below image_title, overlaid on the card image. Requires image_url.
Bold text overlaid on the card image. Requires image_url (rejected without it).
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)
ChatsLocation
Request and retrieve real-time location data via iMessage.
Use these endpoints to request a contact’s location, retrieve location data for contacts who are sharing with you, and subscribe to webhooks when someone starts or stops sharing their location.
Coordinates are returned in GeoJSON format:
[longitude, latitude] or [longitude, latitude, altitude] if altitude is available.