Skip to content
API Docs
Linq Copy agent prompt
API Reference
Chats

Messages

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.

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 link part cannot be combined with other parts in the same message.
  • Maximum URL length: 2,048 characters.

App Clips

An app_clip part sends a registered App Clip — not only Linq’s Apple Pay checkout, but any partner’s own App Clip. Like a link part it must be the only part in the message, and it is iMessage only — it never downgrades to SMS or RCS. The payment-checkout use of this part is covered in the Payments section.

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 given a retention window configured for your account. After that window, the message’s text, formatting, and attachment references are no longer retrievable through the API — see the Attachments row below for how the attachment media itself is handled. Metadata about the message is retained: message identifiers, timestamps, phone numbers, and delivery state. Metadata retention is not bounded by this window. Bounded operational copies, such as backups and delivery queues, expire on their own separate schedules. There is no per-message flag; ephemerality is applied automatically based on your configuration.

The window can be set anywhere from 60 minutes to 24 hours, and defaults to 24 hours. Ask your Linq support contact to configure a shorter window; it cannot be changed through the API.

You can request it at two scopes:

ScopeEffect
Partner-wideEvery outbound and inbound message on every phone number under your account has its content removed from the API surface after your configured window. Metadata is retained.
Per phone numberOnly the specified phone numbers have message content removed from the API surface this way. The rest follow the standard message-retention policy.

Behavioral differences vs the standard default:

AspectStandardEphemeral
RetentionRetained per the standard message-retention policyHard backstop: your configured window (60 minutes – 24 hours, default 24 hours) from when the message is created
After expiryMessage stays retrievableMessage content is no longer retrievable — GET /v3/messages/{messageId} returns 404 and it no longer appears in GET /v3/chats/{chatId}/messages
Content on expiryN/AText, formatting, and attachment references are removed from the API surface, not blanked out in place. Metadata (identifiers, timestamps, phone numbers, delivery state) is retained; its retention is not bounded by this window
AttachmentsRetainedMedia sent on the ephemeral attachments tier is removed on its own storage backstop — within roughly 24–48 hours of upload — independently of the message window, so it can outlast a window shorter than a day. Attachments on the persistent tier (including pre-uploads via POST /v3/attachments) are kept until you DELETE them
Cross-partner isolationEnforcedEnforced

How the retention window works:

  • The window runs from message creation (created_at). It is configured for your account (60 minutes – 24 hours, default 24 hours) and cannot be set per message.
  • Attachment media follows its own storage backstop rather than the message window — see the Attachments row above.
  • Expiry is delivery-independent — the clock starts when the message is created, not when it is delivered or read.
  • Deletion happens shortly after the window, not exactly at it. A background sweep runs every ~5 minutes, so a message typically stops being retrievable within about 5 minutes of its expiry, and longer while a backlog is being worked through. Treat the window as the guaranteed minimum retention, never as an exact deletion time or an upper bound.

What you observe:

  • No expiry timestamp is exposed. API responses and webhook payloads do not include the deletion time, and they do not report your configured window either — so if you are on a window shorter than 24 hours you cannot derive a message’s expiry from the API today. Track the window you agreed with your Linq support contact and compute created_at + window yourself.
  • No deletion webhook is sent. There is no message.deleted event — a message simply stops being retrievable once its window passes.
  • The attachment backstop is separate from the message window. API retrievability (the 404 behavior above) ends at your configured window. Ephemeral-tier media objects are removed on their own storage backstop — within roughly 24–48 hours of upload — which is independent of the message window and can outlast a window shorter than a day. Removal of the corresponding entries from the sending device happens asynchronously and can complete after the backstop.
  • Delivery is unaffected. Ephemeral messages send, deliver, and fire the usual message.sent / message.received and 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 once its window passes, persist anything you need to keep from the webhook payload at the time it is delivered.

Send a message to an existing chat
client.chats.messages.send(stringchatID, MessageSendParams { message, override_optout } body, RequestOptionsoptions?): MessageSendResponse { chat_id, message }
POST/v3/chats/{chatId}/messages
Get messages from a chat
client.chats.messages.list(stringchatID, MessageListParams { cursor, limit } query?, RequestOptionsoptions?): ListMessagesPagination<Message { id, chat_id, created_at, 16 more } >
GET/v3/chats/{chatId}/messages
ModelsExpand Collapse
SentMessage { id, created_at, delivery_status, 9 more }

A message that was sent (used in CreateChat and SendMessage responses)

id: string

Message identifier (UUID)

formatuuid
created_at: string

When the message was created

formatdate-time
delivery_status: "pending" | "queued" | "sent" | 4 more

Current delivery status of a message

One of the following:
"pending"
"queued"
"sent"
"delivered"
"received"
"read"
"failed"
Deprecatedis_read: boolean

DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.

parts: Array<TextPartResponse { reactions, type, value, 5 more } | MediaPartResponse { id, filename, mime_type, 4 more } | LinkPartResponse { reactions, type, value } | 2 more>

Message parts in order (text, media, and link)

One of the following:
TextPartResponse { reactions, type, value, 5 more }

A text message part

reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

type: "text"

Indicates this is a text message part

value: string

The text content

inline_stickers?: Array<InlineStickerResponse { range, id, file_name, 2 more } > | null

Stickers placed inside the text, in the order they appear in value. null when the part has none.

Set on messages sent with inline_stickers. An inline sticker received over iMessage currently arrives as a separate media part.

range: Array<number>

Character range [start, end) in value that the sticker replaces. Those characters are hidden on iMessage and sent as written on SMS and RCS. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

id?: string | null

Attachment ID of the sticker image.

formatuuid
file_name?: string | null

Filename of the sticker

mime_type?: string | null

MIME type of the sticker image

url?: string | null

URL for downloading the sticker image. Permanent for a normal upload; a time-limited signed URL when the image is an ephemeral attachment.

formaturi
Deprecatedmention?: string | null

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.

Deprecatedmention_range?: Array<number> | null

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?: Array<Mention> | null

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.

handle: string

Address of the mentioned participant, exactly as the device recorded it — an E.164 phone number or an email address.

is_me: boolean

Whether the mentioned participant is this line.

range: Array<number>

Character range [start, end) in value highlighted as this mention. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

Character range [start, end) in the value string where the decoration applies. start is inclusive, end is exclusive. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:
"big"
"small"
"shake"
"nod"
"explode"
"ripple"
"bloom"
"jitter"
style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:
"bold"
"italic"
"strikethrough"
"underline"
MediaPartResponse { id, filename, mime_type, 4 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid
filename: string

Original filename

mime_type: string

MIME type of the file

reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

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

formaturi
handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

IMessageAppPartResponse { app, layout, reactions, 3 more }

An iMessage app card part.

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

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

bundle_id: string

Bundle identifier of the Messages app extension. Must not contain :.

minLength1
maxLength255
name: string

Display name of the app, shown by Messages’ fallback UI.

minLength1
maxLength64
team_id: string

The app’s 10-character uppercase alphanumeric team identifier.

app_store_id?: number

The owning app’s App Store id (optional). When set, recipients without the iMessage app installed see a “Get the app” affordance.

formatint64
minimum1
layout: Layout { 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.

caption?: string

Primary label, top-left and bold.

maxLength512
image_subtitle?: string

Text shown below image_title, overlaid on the card image. Requires image_url.

maxLength512
image_title?: string

Bold text overlaid on the card image. Requires image_url (rejected without it).

maxLength512
image_url?: string

URL of an image (JPEG, PNG, HEIF, or WebP) to display as the card’s preview image; an unreachable or non-image URL returns a validation error. Renders for all recipients regardless of whether they have the app. Note - requires a trusted chat w/ inbound activity. In responses, this is the re-hosted cdn.linqapp.com copy of the image you supplied, not your original URL.

formaturi
maxLength2048
subcaption?: string

Secondary label, below caption on the left.

maxLength512
trailing_caption?: string

Label shown top-right.

maxLength512
trailing_subcaption?: string

Label shown below trailing_caption, on the right.

maxLength512
reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

type: "imessage_app"

Indicates this is an iMessage app card part.

url: string

The URL delivered to the iMessage app on tap.

formaturi
fallback_text?: string | null

Fallback text for surfaces that cannot render the card.

AppClipPartResponse { reactions, type, value, 3 more }

An App Clip card part

reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

type: "app_clip"

Indicates this is an App Clip card part

value: string

The App Clip link the card opens

description?: string

The card’s summary line, composed by Linq from the App Clip page

image_url?: string

The card’s preview image

title?: string

The card’s headline, composed by Linq from the App Clip page

sent_at: string | null

When the message was actually sent (null if still queued)

formatdate-time
delivered_at?: string | null

When the message was delivered

formatdate-time
effect?: MessageEffect { name, type } | null

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

name?: string

Name of the effect. Common values:

  • Screen effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight
  • Bubble effects: slam, loud, gentle, invisible
type?: "screen" | "bubble"

Type of effect

One of the following:
"screen"
"bubble"
from_handle?: ChatHandle { id, handle, joined_at, 5 more } | null

The sender of this message as a full handle object

id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
preferred_service?: ServiceType | null

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.

One of the following:
"iMessage"
"SMS"
"RCS"
reply_to?: ReplyTo { message_id, part_index } | null

Indicates this message is a threaded reply to another message

message_id: string

The ID of the message to reply to

formatuuid
part_index?: number

The specific message part to reply to (0-based index). Defaults to 0 (first part) if not provided. Use this when replying to a specific part of a multipart message.

formatint32
minimum0
service?: ServiceType | null

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.

One of the following:
"iMessage"
"SMS"
"RCS"
MessageSendResponse { chat_id, message }

Response for sending a message to a chat

chat_id: string

Unique identifier of the chat this message was sent to

formatuuid
message: SentMessage { id, created_at, delivery_status, 9 more }

A message that was sent (used in CreateChat and SendMessage responses)

id: string

Message identifier (UUID)

formatuuid
created_at: string

When the message was created

formatdate-time
delivery_status: "pending" | "queued" | "sent" | 4 more

Current delivery status of a message

One of the following:
"pending"
"queued"
"sent"
"delivered"
"received"
"read"
"failed"
Deprecatedis_read: boolean

DEPRECATED: Use delivery_status == "read" instead. Whether the message has been read.

parts: Array<TextPartResponse { reactions, type, value, 5 more } | MediaPartResponse { id, filename, mime_type, 4 more } | LinkPartResponse { reactions, type, value } | 2 more>

Message parts in order (text, media, and link)

One of the following:
TextPartResponse { reactions, type, value, 5 more }

A text message part

reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

type: "text"

Indicates this is a text message part

value: string

The text content

inline_stickers?: Array<InlineStickerResponse { range, id, file_name, 2 more } > | null

Stickers placed inside the text, in the order they appear in value. null when the part has none.

Set on messages sent with inline_stickers. An inline sticker received over iMessage currently arrives as a separate media part.

range: Array<number>

Character range [start, end) in value that the sticker replaces. Those characters are hidden on iMessage and sent as written on SMS and RCS. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

id?: string | null

Attachment ID of the sticker image.

formatuuid
file_name?: string | null

Filename of the sticker

mime_type?: string | null

MIME type of the sticker image

url?: string | null

URL for downloading the sticker image. Permanent for a normal upload; a time-limited signed URL when the image is an ephemeral attachment.

formaturi
Deprecatedmention?: string | null

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.

Deprecatedmention_range?: Array<number> | null

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?: Array<Mention> | null

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.

handle: string

Address of the mentioned participant, exactly as the device recorded it — an E.164 phone number or an email address.

is_me: boolean

Whether the mentioned participant is this line.

range: Array<number>

Character range [start, end) in value highlighted as this mention. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

text_decorations?: Array<TextDecoration { range, animation, style } > | null

Text decorations applied to character ranges in the value

range: Array<number>

Character range [start, end) in the value string where the decoration applies. start is inclusive, end is exclusive. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

animation?: "big" | "small" | "shake" | 5 more

Animated text effect to apply. Mutually exclusive with style.

One of the following:
"big"
"small"
"shake"
"nod"
"explode"
"ripple"
"bloom"
"jitter"
style?: "bold" | "italic" | "strikethrough" | "underline"

Text style to apply. Mutually exclusive with animation.

One of the following:
"bold"
"italic"
"strikethrough"
"underline"
MediaPartResponse { id, filename, mime_type, 4 more }

A media attachment part

id: string

Unique attachment identifier

formatuuid
filename: string

Original filename

mime_type: string

MIME type of the file

reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

size_bytes: number

File size in bytes

type: "media"

Indicates this is a media attachment part

url: string

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

formaturi
handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

IMessageAppPartResponse { app, layout, reactions, 3 more }

An iMessage app card part.

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

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

bundle_id: string

Bundle identifier of the Messages app extension. Must not contain :.

minLength1
maxLength255
name: string

Display name of the app, shown by Messages’ fallback UI.

minLength1
maxLength64
team_id: string

The app’s 10-character uppercase alphanumeric team identifier.

app_store_id?: number

The owning app’s App Store id (optional). When set, recipients without the iMessage app installed see a “Get the app” affordance.

formatint64
minimum1
layout: Layout { 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.

caption?: string

Primary label, top-left and bold.

maxLength512
image_subtitle?: string

Text shown below image_title, overlaid on the card image. Requires image_url.

maxLength512
image_title?: string

Bold text overlaid on the card image. Requires image_url (rejected without it).

maxLength512
image_url?: string

URL of an image (JPEG, PNG, HEIF, or WebP) to display as the card’s preview image; an unreachable or non-image URL returns a validation error. Renders for all recipients regardless of whether they have the app. Note - requires a trusted chat w/ inbound activity. In responses, this is the re-hosted cdn.linqapp.com copy of the image you supplied, not your original URL.

formaturi
maxLength2048
subcaption?: string

Secondary label, below caption on the left.

maxLength512
trailing_caption?: string

Label shown top-right.

maxLength512
trailing_subcaption?: string

Label shown below trailing_caption, on the right.

maxLength512
reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

type: "imessage_app"

Indicates this is an iMessage app card part.

url: string

The URL delivered to the iMessage app on tap.

formaturi
fallback_text?: string | null

Fallback text for surfaces that cannot render the card.

AppClipPartResponse { reactions, type, value, 3 more }

An App Clip card part

reactions: Array<Reaction { handle, is_me, type, 3 more } > | null

Reactions on this message part

handle: ChatHandle { id, handle, joined_at, 5 more }
id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
is_me: boolean

Whether this reaction is from the current user

type: ReactionType

Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.

One of the following:
"love"
"like"
"dislike"
"laugh"
"emphasize"
"question"
"custom"
"sticker"
id?: string

Identifier for this reaction. Pass it to PATCH /v3/messages/{messageId}/reactions/{reactionId} to move a sticker.

Stickers placed before this API shipped can be read but not moved: the device-side reference needed to reposition them was never recorded, so PATCH returns 404 for those.

formatuuid
custom_emoji?: string | null

Custom emoji if type is “custom”, null otherwise

sticker?: Sticker | null

Sticker attachment details when reaction_type is “sticker”. Null for non-sticker reactions.

file_name?: string

Filename of the sticker

height?: number

Sticker image height in pixels

mime_type?: string

MIME type of the sticker image

url?: string

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

formaturi
width?: number

Sticker image width in pixels

type: "app_clip"

Indicates this is an App Clip card part

value: string

The App Clip link the card opens

description?: string

The card’s summary line, composed by Linq from the App Clip page

image_url?: string

The card’s preview image

title?: string

The card’s headline, composed by Linq from the App Clip page

sent_at: string | null

When the message was actually sent (null if still queued)

formatdate-time
delivered_at?: string | null

When the message was delivered

formatdate-time
effect?: MessageEffect { name, type } | null

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

name?: string

Name of the effect. Common values:

  • Screen effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight
  • Bubble effects: slam, loud, gentle, invisible
type?: "screen" | "bubble"

Type of effect

One of the following:
"screen"
"bubble"
from_handle?: ChatHandle { id, handle, joined_at, 5 more } | null

The sender of this message as a full handle object

id: string

Unique identifier for this handle

formatuuid
handle: string

Phone number (E.164) or email address of the participant

joined_at: string

When this participant joined the chat

formatdate-time
service: ServiceType

Messaging service type. 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.

One of the following:
"iMessage"
"SMS"
"RCS"
is_me?: boolean | null

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

left_at?: string | null

When they left (if applicable)

formatdate-time
line_type?: "iMessage" | "RCS"

The kind of line: iMessage for an iMessage-capable line, RCS for an RCS-only line, which sends RCS and SMS but never iMessage. Same values as the type parameter on GET /v3/available_number. A property of the line itself, so unlike service it does not change with the conversation: an iMessage-capable line can still carry an RCS or SMS conversation.

One of the following:
"iMessage"
"RCS"
status?: "active" | "left" | "removed" | null

Participant status

One of the following:
"active"
"left"
"removed"
preferred_service?: ServiceType | null

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.

One of the following:
"iMessage"
"SMS"
"RCS"
reply_to?: ReplyTo { message_id, part_index } | null

Indicates this message is a threaded reply to another message

message_id: string

The ID of the message to reply to

formatuuid
part_index?: number

The specific message part to reply to (0-based index). Defaults to 0 (first part) if not provided. Use this when replying to a specific part of a multipart message.

formatint32
minimum0
service?: ServiceType | null

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.

One of the following:
"iMessage"
"SMS"
"RCS"
© 2026 Linq, Inc. · linqapp.com