Chats
Update a chat
Leave a group chat
Share your contact card with a chat
Send a voice memo to a chat
ModelsExpand Collapse
type Chat struct{…}
Display name for the chat. Defaults to a comma-separated list of recipient handles. Can be updated for group chats.
Handles []ChatHandleList of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).
List of chat participants with full handle details. Always contains at least two handles (your phone number and the other participant).
Service ServiceTypeMessaging service type
Messaging service type
HealthStatus ChatHealthStatus[BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.
Switch on status to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a doc_url that deep-links to the relevant section of the Chat Health guide.
See the Chat Health guide for what each status means and how to react.
[BETA] Current health for a chat. Always present — chats start at HEALTHY and may shift based on engagement and delivery signals on the conversation. Many AT_RISK or CRITICAL chats on a single line increase the risk of line flagging.
Switch on status to gate sends or surface line health in your UI — the enum is the long-term contract. Each status carries a doc_url that deep-links to the relevant section of the Chat Health guide.
See the Chat Health guide for what each status means and how to react.
Status stringCurrent health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.
Current health bucket for the chat. See the Chat Health guide for what each value means and how to react. doc_url deep-links to the relevant section.
DEPRECATED: This field is deprecated and will be removed in a future API version.
type LinkPart struct{…}
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.
type MediaPart struct{…}
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.
type MessageContent struct{…}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 []MessageContentPartUnionArray 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.
type TextPart struct{…}
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MediaPart struct{…}
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.
type LinkPart struct{…}
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.
type TextPart struct{…}
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.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
ChatsParticipants
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
user@example.com - No spaces, dashes, or parentheses in phone numbers
Add a participant to a chat
Remove a participant from a chat
ChatsTyping
A Chat is a conversation thread with one or more participants.
To begin a chat, you must create a Chat with at least one recipient handle. Including multiple handles creates a group chat.
When creating a chat, the from field specifies which of your
authorized phone numbers the message originates from. Your authentication token grants
access to one or more phone numbers, but the from field determines the actual sender.
Handle Format:
- Handles can be phone numbers or email addresses
- Phone numbers MUST be in E.164 format (starting with +)
- Phone format:
+[country code][subscriber number] - Example phone:
+12223334444(US),+442071234567(UK),+81312345678(Japan) - Example email:
user@example.com - No spaces, dashes, or parentheses in phone numbers
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
type SentMessage struct{…}A message that was sent (used in CreateChat and SendMessage responses)
A message that was sent (used in CreateChat and SendMessage responses)
Parts []SentMessagePartUnionMessage parts in order (text, media, and link)
Message parts in order (text, media, and link)
type TextPartResponse struct{…}A text message part
A text message part
Reactions []ReactionReactions on this message part
Reactions on this message part
Handle ChatHandle
Service ServiceTypeMessaging service type
Messaging service type
Type ReactionTypeType of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Text decorations applied to character ranges in the value
Text decorations applied to character ranges in the value
Character range [start, end) in the value string where the decoration applies.
start is inclusive, end is exclusive.
Characters are measured as UTF-16 code units. Most characters count as 1; some emoji count as 2.
Animation TextDecorationAnimationOptionalAnimated text effect to apply. Mutually exclusive with style.
Animated text effect to apply. Mutually exclusive with style.
type MediaPartResponse struct{…}A media attachment part
A media attachment part
Reactions []ReactionReactions on this message part
Reactions on this message part
Handle ChatHandle
Service ServiceTypeMessaging service type
Messaging service type
Type ReactionTypeType of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
type LinkPartResponse struct{…}A rich link preview part
A rich link preview part
Reactions []ReactionReactions on this message part
Reactions on this message part
Handle ChatHandle
Service ServiceTypeMessaging service type
Messaging service type
Type ReactionTypeType of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question.
Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field.
Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
Type of reaction. Standard iMessage tapbacks are love, like, dislike, laugh, emphasize, question. Custom emoji reactions have type “custom” with the actual emoji in the custom_emoji field. Sticker reactions have type “sticker” with sticker attachment details in the sticker field.
iMessage effect applied to a message (screen or bubble effect)
iMessage effect applied to a message (screen or bubble effect)
The sender of this message as a full handle object
The sender of this message as a full handle object
Service ServiceTypeMessaging service type
Messaging service type