Send a message to an existing chat

client.chats.messages.send(, , ?): MessageSendResponse { chat_id, message }

POST/v3/chats/{chatId}/messages

Send a message to an existing chat. Use this endpoint when you already have a chat ID and want to send additional messages to it.

Message Effects

You can add iMessage effects to make your messages more expressive. Effects are optional and can be either screen effects (full-screen animations) or bubble effects (message bubble animations).

Screen Effects: confetti, fireworks, lasers, sparkles, celebration, hearts, love, balloons, happy_birthday, echo, spotlight

Bubble Effects: slam, loud, gentle, invisible

Only one effect type can be applied per message.

Inline Text Decorations (iMessage only)

Use the text_decorations array on a text part to apply styling and animations to character ranges.

Each decoration specifies a range: [start, end) and exactly one of style or animation.

Styles: bold, italic, strikethrough, underline Animations: big, small, shake, nod, explode, ripple, bloom, jitter

{
  "type": "text",
  "value": "Hello world",
  "text_decorations": [
    { "range": [0, 5], "style": "bold" },
    { "range": [6, 11], "animation": "shake" }
  ]
}

Note: Style ranges (bold, italic, etc.) may overlap, but animation ranges must not overlap with other animations or styles. Decorations render per recipient, not per message: in a group with both iMessage and SMS/RCS participants, iMessage recipients see the decorations and SMS/RCS recipients receive the same message as plain text.

Inline Stickers (iMessage only)

Use the inline_stickers array on a text part to place stickers inside the text. Each sticker replaces the characters in its range: [start, end) and takes its image from exactly one of url or attachment_id — an image uploaded with POST /v3/attachments.

{
  "type": "text",
  "value": "Happy birthday 🎂! 🎉🎉",
  "inline_stickers": [
    { "range": [15, 17], "attachment_id": "550e8400-e29b-41d4-a716-446655440000" },
    { "range": [19, 21], "attachment_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" },
    { "range": [21, 23], "attachment_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }
  ]
}

Note: A sticker takes the place of the characters it covers, so they are hidden on iMessage: "Sip cup" with a sticker on cup reads “Sip [sticker]”. Those characters are what SMS and RCS recipients receive (the stickers are dropped and value is sent as written) and what VoiceOver reads. To keep a word visible, give the sticker its own placeholder: "Sip cup 🥤" with the range on 🥤. Up to 100 stickers and 10 different images per part; copies of one image count as one.

ParametersExpand Collapse

chatID: string

formatuuid

body: MessageSendParams { message, override_optout }

message: MessageContent { effect, experience, idempotency_key, 3 more }

Message content container. Groups all message-related fields together, separating the “what” (message content) from the “where” (routing fields like from/to).

A message carries EITHER parts — text and attachments, which compose into one bubble — or a single experience invocation, which renders an experience inside Linq’s iMessage app. Never both: an app card is the whole message (Apple’s MSMessage cannot coexist with text), so copy and a card are two sends, not one.

effect?: MessageEffect { name, type }

iMessage effect to apply to this 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"

experience?: Experience { action, name, params }

Invokes an action on an experience — a third party that renders inside Linq’s iMessage app. Linq resolves the recipient’s connection, mints any session the action needs, composes the card and sends it; none of that is visible to you.

Call GET /v3/experiences/{experience} for the actions you may invoke and the fields each accepts.

action: string

Which of its actions, e.g. attach_card.

The experience to invoke, e.g. agentcard or agentpay.

params?: Record<string, unknown>

Values for the fields this action exposes. Keys are exactly the field names listed for the action — no mapping, no nesting.

Display copy only, except a url-type field — that value sets the destination, and must be an absolute https URL.

Some fields are read rather than sent: agentpay’s request_payment takes only a checkout_url and resolves the amount and reason from that payment request itself, so the card cannot state a figure the checkout will not charge.

idempotency_key?: string

Optional idempotency key for this message. Use this to prevent duplicate sends of the same message. Reusing a key whose message was deleted — or was an ephemeral message that has since expired — returns 404; the message is never resent.

maxLength255

parts?: Array<TextPart { type, value, inline_stickers, 3 more } | MediaPart { type, attachment_id, sticker, url } | LinkPart { type, value } | 2 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

App Clip Payment Cards:

Use an app_clip part to send a Linq checkout link as an Apple Pay App Clip card (the payment preview with the Open button)
An app_clip part must be the only part in the message
iMessage-only: unlike link, it never downgrades to SMS/RCS — the send fails instead of delivering a bare URL

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.
An app_clip part must be the only part in the message. Its value must be a Linq checkout link (e.g. from POST /v3/payment_requests); any other URL is rejected.
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.

One of the following:

TextPart { type, value, inline_stickers, 3 more }

type: "text"

Indicates this is a text message part

value: string

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

minLength1

maxLength10000

inline_stickers?: Array<InlineSticker { range, attachment_id, url } >

Optional stickers placed inside the text, in the line with the words (iMessage only).

Each sticker replaces the characters in its range [start, end) of value, and takes its image from exactly one of url or attachment_id — an image uploaded with POST /v3/attachments. The characters a sticker covers are hidden on iMessage and are what SMS and RCS recipients receive and VoiceOver reads, so cover something that stands in for the sticker ("🎂", "[cake]"). To keep a word visible, give the sticker its own placeholder: "Sip cup 🥤" with the range on 🥤.

Up to 100 stickers and 10 different images per part. Copies of one image count as one: twenty copies of one sticker use one of the 10. An animated image arrives as a still.

Stickers cannot overlap each other or a text_decorations range, cannot split a character, and cannot be combined with mention.

Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

Note: on SMS and RCS the stickers are dropped and value is sent as plain text.

range: Array<number>

Character range [start, end) in the value string that the sticker replaces. start is inclusive, end is exclusive. 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.

attachment_id?: string

Reference to a sticker image pre-uploaded via POST /v3/attachments.

Exactly one of url or attachment_id is required.

formatuuid

url?: string

Linq attachment URL of the sticker image — the download_url returned by POST /v3/attachments.

The image must already be stored with us. To use an image from elsewhere, upload it with POST /v3/attachments first and pass attachment_id.

Exactly one of url or attachment_id is required.

formaturi

mention?: string

Mention a chat participant. Group chats only — sending a mention to a direct chat is rejected with 409 / 2023. The chat’s service is not a constraint: a mention is accepted in any group, including one with SMS/RCS participants.

Set to their handle — E.164 phone number or Apple ID email. value is the display text; use the bare name ("Juan", not "@Juan"). By default the entire value renders as the mention; use mention_range to highlight only part of it.

Rendering is per recipient, not per message. iMessage recipients see the mention highlighted and are notified even if they have muted the chat. SMS and RCS recipients receive the same message as plain text — no highlight, and no mute override. One send, two experiences.

minLength1

maxLength320

mention_range?: Array<number>

Optional character range [start, end) in value that renders as the mention highlight (e.g. just the name in "Hey Kevin, can you look at this?"). Requires mention. Without it, the entire value is highlighted. start is inclusive, end is exclusive. Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.

Applies to iMessage recipients only, matching mention — SMS and RCS recipients receive the text with no highlight.

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

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: decorations render per recipient, not per message. In a group containing both iMessage and SMS/RCS participants, iMessage recipients see the decorations and SMS/RCS recipients receive the same message as plain text.

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"

MediaPart { type, attachment_id, sticker, url }

type: "media"

Indicates this is a media attachment part

attachment_id?: string

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.

formatuuid

sticker?: boolean

Send this image as a sticker rather than a photo. The recipient can peel it off and place it on any message in the conversation, and it renders without a bubble.

An ordinary photo is cut out automatically — the subject is lifted from its background. An image that has already been cut out is sent as-is. If no subject can be found, the image sends as an ordinary photo.

An animated image sends as an animated sticker, in whatever shape the file already has — the cut-out does not apply to it.

iMessage only. On SMS/RCS the flag is ignored and the image sends as a photo.

Stickers can be combined with a text part in the same message; the text arrives as its own bubble. To place a sticker onto an existing message instead, use POST /v3/messages/{messageId}/reactions with type: "sticker".

url?: string

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.

formaturi

LinkPart { type, value }

type: "link"

Indicates this is a rich link preview part

value: string

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.

formaturi

minLength1

maxLength2048

IMessageAppPart { 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.

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

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

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

type: "imessage_app"

Indicates this is an iMessage app card part.

fallback_text?: string

Text shown on surfaces that cannot render the card (notifications, lock screen). Defaults to the caption when omitted.

maxLength1024

interactive?: boolean

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.

url?: string

URL the recipient’s app opens when they tap the card. Either an absolute https:// URL (capped at 2048 characters) or a data: URL carrying inline app state, e.g. a game’s encoded state (capped at 16384 characters).

formaturi

maxLength16384

AppClipPart { type, value, caption }

Sends a registered App Clip — not only Linq’s Apple Pay checkout, but any partner’s own App Clip. caption is optional.

An app_clip part must be the only part in the message.

iMessage only, and it never downgrades. A service_preference of sms or rcs is rejected (AppClipServiceUnsupported, 2028). A recipient who can’t receive it fails the send rather than being sent a plain link in its place.

type: "app_clip"

Indicates this is an App Clip card

value: string

An https link whose page is a registered App Clip — Linq’s checkout link (e.g. the checkout_url from POST /v3/payment_requests) or a partner’s own App Clip URL. A URL that doesn’t resolve to a sendable App Clip page is rejected.

formaturi

minLength1

maxLength2048

caption?: string

Optional caption for the card’s Open button row. Omit it and the card uses the App Clip’s own default (Tap open). Set it to override that with your own short call to action.

maxLength56

preferred_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"

reply_to?: ReplyTo { message_id, part_index }

Reply to another message to create a threaded conversation

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

override_optout?: boolean

Send even though the recipient asked you to stop (403, error code 2024). Applies to this request only: the opt-out stays in place, so the next send without this flag is rejected again. Every override is recorded against your API key.

ReturnsExpand Collapse

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>

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"

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

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

LinkPartResponse { reactions, type, value }

A rich link preview 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"

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

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: "link"

Indicates this is a rich link preview part

value: string

The URL

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

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

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.

* Note - requires a trusted chat w/ inbound activity

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

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"

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

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"

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

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"

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"

Send a message to an existing chat

import LinqAPIV3 from '@linqapp/sdk';

const client = new LinqAPIV3({
  apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted
});

const response = await client.chats.messages.send('550e8400-e29b-41d4-a716-446655440000', {
  message: { parts: [{ type: 'text', value: 'Hello, world!' }] },
});

console.log(response.chat_id);

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
    "created_at": "2025-10-23T13:07:55.019-05:00",
    "delivery_status": "pending",
    "is_read": false,
    "parts": [
      {
        "reactions": [
          {
            "handle": {
              "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
              "handle": "+15551234567",
              "joined_at": "2025-05-21T15:30:00.000-05:00",
              "service": "iMessage",
              "is_me": false,
              "left_at": "2019-12-27T18:11:19.117Z",
              "line_type": "iMessage",
              "status": "active"
            },
            "is_me": false,
            "type": "love",
            "id": "9f8b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
            "custom_emoji": null,
            "sticker": {
              "file_name": "sticker.png",
              "height": 420,
              "mime_type": "image/png",
              "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
              "width": 420
            }
          }
        ],
        "type": "text",
        "value": "Hello!",
        "inline_stickers": [
          {
            "range": [
              15,
              17
            ],
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "file_name": "sticker.png",
            "mime_type": "image/png",
            "url": "https://cdn.linqapp.com/attachments/partners/acme/550e8400-e29b-41d4-a716-446655440000/sticker.png"
          }
        ],
        "mention": "+14155551234",
        "mention_range": [
          4,
          9
        ],
        "mentions": [
          {
            "handle": "+14155550123",
            "is_me": true,
            "range": [
              4,
              9
            ]
          }
        ],
        "text_decorations": [
          {
            "range": [
              0,
              5
            ],
            "animation": "shake",
            "style": "bold"
          }
        ]
      }
    ],
    "sent_at": null,
    "delivered_at": null,
    "effect": {
      "name": "confetti",
      "type": "screen"
    },
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "service": "iMessage",
      "is_me": false,
      "left_at": "2019-12-27T18:11:19.117Z",
      "line_type": "iMessage",
      "status": "active"
    },
    "preferred_service": "iMessage",
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "part_index": 0
    },
    "service": "iMessage"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2023,
    "message": "mentions are only supported in group chats",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2023/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2015,
    "message": "mention target +14155551234 is no longer a participant of this chat",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2015/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "cannot interact with a chat you have left",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2013/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
    "created_at": "2025-10-23T13:07:55.019-05:00",
    "delivery_status": "pending",
    "is_read": false,
    "parts": [
      {
        "reactions": [
          {
            "handle": {
              "id": "69a37c7d-af4f-4b5e-af42-e28e98ce873a",
              "handle": "+15551234567",
              "joined_at": "2025-05-21T15:30:00.000-05:00",
              "service": "iMessage",
              "is_me": false,
              "left_at": "2019-12-27T18:11:19.117Z",
              "line_type": "iMessage",
              "status": "active"
            },
            "is_me": false,
            "type": "love",
            "id": "9f8b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
            "custom_emoji": null,
            "sticker": {
              "file_name": "sticker.png",
              "height": 420,
              "mime_type": "image/png",
              "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/sticker.png?signature=...",
              "width": 420
            }
          }
        ],
        "type": "text",
        "value": "Hello!",
        "inline_stickers": [
          {
            "range": [
              15,
              17
            ],
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "file_name": "sticker.png",
            "mime_type": "image/png",
            "url": "https://cdn.linqapp.com/attachments/partners/acme/550e8400-e29b-41d4-a716-446655440000/sticker.png"
          }
        ],
        "mention": "+14155551234",
        "mention_range": [
          4,
          9
        ],
        "mentions": [
          {
            "handle": "+14155550123",
            "is_me": true,
            "range": [
              4,
              9
            ]
          }
        ],
        "text_decorations": [
          {
            "range": [
              0,
              5
            ],
            "animation": "shake",
            "style": "bold"
          }
        ]
      }
    ],
    "sent_at": null,
    "delivered_at": null,
    "effect": {
      "name": "confetti",
      "type": "screen"
    },
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "handle": "+15551234567",
      "joined_at": "2025-05-21T15:30:00.000-05:00",
      "service": "iMessage",
      "is_me": false,
      "left_at": "2019-12-27T18:11:19.117Z",
      "line_type": "iMessage",
      "status": "active"
    },
    "preferred_service": "iMessage",
    "reply_to": {
      "message_id": "550e8400-e29b-41d4-a716-446655440000",
      "part_index": 0
    },
    "service": "iMessage"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Resource not found",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2001/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2023,
    "message": "mentions are only supported in group chats",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2023/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2015,
    "message": "mention target +14155551234 is no longer a participant of this chat",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2015/"
  },
  "success": false
}

{
  "error": {
    "status": 409,
    "code": 2013,
    "message": "cannot interact with a chat you have left",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2013/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/3xxx/3006/"
  },
  "success": false
}