Chats
Create a new chat
List all chats
Get a chat by ID
Update a chat
Mark chat as read
Leave a group chat
Share your contact card with a chat
Send a voice memo to a chat
ModelsExpand Collapse
Chat object { id, created_at, display_name, 6 more }
Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.
List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).
List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).
health_score: optional object { reason, score, updated_at } [BETA] Health assessment for a chat. Higher score is healthier.
null when a score isn’t available yet. Scoring may change during beta.
[BETA] Health assessment for a chat. Higher score is healthier.
null when a score isn’t available yet. Scoring may change during beta.
LinkPart object { type, value }
URL to send with a rich link preview. The recipient will see an inline card with the page’s title, description, and preview image (when available).
A link part must be the only part in the message. To send a URL as plain
text (no preview card), use a text part instead.
MediaPart object { type, attachment_id, url }
Reference to a file pre-uploaded via POST /v3/attachments (optional).
The file is already stored, so sends using this ID skip the download step —
useful when sending the same file to many recipients.
Either url or attachment_id must be provided, but not both.
Any publicly accessible HTTPS URL to the media file. The server downloads and sends the file automatically — no pre-upload step required.
Size limit: 10MB maximum for URL-based downloads. For larger files (up to 100MB),
use the pre-upload flow: POST /v3/attachments to get a presigned URL, upload directly,
then reference by attachment_id.
Requirements:
- URL must use HTTPS
- File content must be a supported format (the server validates the actual file content)
Supported formats:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Tip: Audio sent here appears as a regular file attachment. To send audio as an
iMessage voice memo bubble (with inline playback), use /v3/chats/{chatId}/voicememo.
For repeated sends of the same file, use attachment_id to avoid redundant downloads.
Either url or attachment_id must be provided, but not both.
MessageContent object { parts, effect, idempotency_key, 2 more } Message content container. Groups all message-related fields together,
separating the “what” (message content) from the “where” (routing fields like from/to).
Message content container. Groups all message-related fields together, separating the “what” (message content) from the “where” (routing fields like from/to).
parts: array of TextPart { type, value, text_decorations } or MediaPart { type, attachment_id, url } or LinkPart { type, value } Array of message parts. Each part can be text, media, or link.
Parts are displayed in order. Text and media can be mixed freely,
but a link part must be the only part in the message.
Rich Link Previews:
- Use a
link part to send a URL with a rich preview card
- A
link part must be the only part in the message
- To send a URL as plain text (no preview), use a
text part instead
Supported Media:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Audio:
- Audio files (.m4a, .mp3, .aac, .caf, .wav, .aiff, .amr) are fully supported as media parts
- To send audio as an iMessage voice memo bubble (inline playback UI), use the dedicated
/v3/chats/{chatId}/voicememo endpoint instead
Validation Rules:
- A
link part must be the only part in the message. It cannot be combined
with text or media parts.
- Consecutive text parts are not allowed. Text parts must be separated by
media parts. For example, [text, text] is invalid, but [text, media, text] is valid.
- Maximum of 100 parts total.
- Media parts using a public
url (downloaded by the server on send) are
capped at 40. Parts using attachment_id or presigned URLs
are exempt from this sub-limit. For bulk media sends exceeding 40 files,
pre-upload via POST /v3/attachments and reference by attachment_id or download_url.
Array of message parts. Each part can be text, media, or link.
Parts are displayed in order. Text and media can be mixed freely,
but a link part must be the only part in the message.
Rich Link Previews:
- Use a
linkpart to send a URL with a rich preview card - A
linkpart must be the only part in the message - To send a URL as plain text (no preview), use a
textpart instead
Supported Media:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Audio:
- Audio files (.m4a, .mp3, .aac, .caf, .wav, .aiff, .amr) are fully supported as media parts
- To send audio as an iMessage voice memo bubble (inline playback UI), use the dedicated
/v3/chats/{chatId}/voicememoendpoint instead
Validation Rules:
- A
linkpart must be the only part in the message. It cannot be combined with text or media parts. - Consecutive text parts are not allowed. Text parts must be separated by media parts. For example, [text, text] is invalid, but [text, media, text] is valid.
- Maximum of 100 parts total.
- Media parts using a public
url(downloaded by the server on send) are capped at 40. Parts usingattachment_idor presigned URLs are exempt from this sub-limit. For bulk media sends exceeding 40 files, pre-upload viaPOST /v3/attachmentsand reference byattachment_idordownload_url.
TextPart object { type, value, text_decorations }
The text content of the message. This value is sent as-is with no parsing or transformation — Markdown syntax will be delivered as plain text. Use text_decorations to apply inline formatting and animations (iMessage only).
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
Character range [start, end) in the value string where the decoration applies.
start is inclusive, end is exclusive.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
MediaPart object { type, attachment_id, url }
Reference to a file pre-uploaded via POST /v3/attachments (optional).
The file is already stored, so sends using this ID skip the download step —
useful when sending the same file to many recipients.
Either url or attachment_id must be provided, but not both.
Any publicly accessible HTTPS URL to the media file. The server downloads and sends the file automatically — no pre-upload step required.
Size limit: 10MB maximum for URL-based downloads. For larger files (up to 100MB),
use the pre-upload flow: POST /v3/attachments to get a presigned URL, upload directly,
then reference by attachment_id.
Requirements:
- URL must use HTTPS
- File content must be a supported format (the server validates the actual file content)
Supported formats:
- Images: .jpg, .jpeg, .png, .gif, .heic, .heif, .tif, .tiff, .bmp
- Videos: .mp4, .mov, .m4v, .mpeg, .mpg, .3gp
- Audio: .m4a, .mp3, .aac, .caf, .wav, .aiff, .amr
- Documents: .pdf, .txt, .rtf, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .pages, .numbers, .key, .epub, .zip, .html, .htm
- Contact & Calendar: .vcf, .ics
Tip: Audio sent here appears as a regular file attachment. To send audio as an
iMessage voice memo bubble (with inline playback), use /v3/chats/{chatId}/voicememo.
For repeated sends of the same file, use attachment_id to avoid redundant downloads.
Either url or attachment_id must be provided, but not both.
LinkPart object { type, value }
URL to send with a rich link preview. The recipient will see an inline card with the page’s title, description, and preview image (when available).
A link part must be the only part in the message. To send a URL as plain
text (no preview card), use a text part instead.
iMessage effect to apply to this message (screen or bubble effect)
iMessage effect to apply to this message (screen or bubble effect)
Optional idempotency key for this message. Use this to prevent duplicate sends of the same message.
TextPart object { type, value, text_decorations }
The text content of the message. This value is sent as-is with no parsing or transformation — Markdown syntax will be delivered as plain text. Use text_decorations to apply inline formatting and animations (iMessage only).
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
Optional array of text decorations applied to character ranges in the value field (iMessage only).
Each decoration specifies a character range [start, end) and exactly one of style or animation.
Styles: bold, italic, strikethrough, underline
Animations: big, small, shake, nod, explode, ripple, bloom, jitter
Style ranges may overlap (e.g. bold + italic on the same text), but animation ranges must not overlap with other animations or styles.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Note: Text decorations only render for iMessage recipients. For SMS/RCS, text decorations are not applied.
Character range [start, end) in the value string where the decoration applies.
start is inclusive, end is exclusive.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
ChatCreateResponse object { chat } Response for creating a new chat with an initial message
Response for creating a new chat with an initial message
chat: object { id, display_name, handles, 4 more }
Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.
List of participants in the chat. Always contains at least two handles (your phone number and the other participant).
List of participants in the chat. Always contains at least two handles (your phone number and the other participant).
A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
parts: array of TextPartResponse { reactions, type, value, text_decorations } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value } Message parts in order (text, media, and link)
Message parts in order (text, media, and link)
TextPartResponse object { reactions, type, value, text_decorations } A text message part
A text message part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Text decorations applied to character ranges in the value
Text decorations applied to character ranges in the value
Character range [start, end) in the value string where the decoration applies.
start is inclusive, end is exclusive.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
MediaPartResponse object { id, filename, mime_type, 4 more } A media attachment part
A media attachment part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
LinkPartResponse object { reactions, type, value } A rich link preview part
A rich link preview part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)
ChatSendVoicememoResponse object { voice_memo } Response for sending a voice memo to a chat
Response for sending a voice memo to a chat
ChatsParticipants
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
[email protected] - No spaces, dashes, or parentheses in phone numbers
Add a participant to a chat
Remove a participant from a chat
ChatsTyping
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
[email protected] - No spaces, dashes, or parentheses in phone numbers
Start typing indicator
Stop typing indicator
ChatsMessages
Messages are individual communications within a chat thread.
Messages can include text, media attachments, rich link previews, special effects (like confetti or fireworks), and reactions. All messages are associated with a specific chat and sent from a phone number you own.
Messages support delivery status tracking, read receipts, and editing capabilities.
Rich Link Previews
Send a URL as a link part to deliver it with a rich preview card showing the
page’s title, description, and image (when available). A link part must be the
only part in the message — it cannot be combined with text or media parts.
To send a URL without a preview card, include it in a text part instead.
Limitations:
- A
linkpart cannot be combined with other parts in the same message. - Maximum URL length: 2,048 characters.
Send a message to an existing chat
Get messages from a chat
ModelsExpand Collapse
SentMessage object { id, created_at, delivery_status, 9 more } A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
parts: array of TextPartResponse { reactions, type, value, text_decorations } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value } Message parts in order (text, media, and link)
Message parts in order (text, media, and link)
TextPartResponse object { reactions, type, value, text_decorations } A text message part
A text message part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Text decorations applied to character ranges in the value
Text decorations applied to character ranges in the value
Character range [start, end) in the value string where the decoration applies.
start is inclusive, end is exclusive.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
MediaPartResponse object { id, filename, mime_type, 4 more } A media attachment part
A media attachment part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
LinkPartResponse object { reactions, type, value } A rich link preview part
A rich link preview part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)
MessageSendResponse object { chat_id, message } Response for sending a message to a chat
Response for sending a message to a chat
A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
parts: array of TextPartResponse { reactions, type, value, text_decorations } or MediaPartResponse { id, filename, mime_type, 4 more } or LinkPartResponse { reactions, type, value } Message parts in order (text, media, and link)
Message parts in order (text, media, and link)
TextPartResponse object { reactions, type, value, text_decorations } A text message part
A text message part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Text decorations applied to character ranges in the value
Text decorations applied to character ranges in the value
Character range [start, end) in the value string where the decoration applies.
start is inclusive, end is exclusive.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
MediaPartResponse object { id, filename, mime_type, 4 more } A media attachment part
A media attachment part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
LinkPartResponse object { reactions, type, value } A rich link preview part
A rich link preview part
Reactions on this message part
Reactions on this message part
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)