API Referencemessages

Send Message

Send an outbound message (SMS or iMessage) via the provider assigned to the number. Attach media by passing public HTTPS URLs in `media_urls` (1-20 per message). Text and media can be combined: pass `body` alongside any number of attachments. Every message needs text, media, or both; for a media-only message, pass an empty `body` (`""`). Media rules: - Each URL must be a **publicly accessible HTTPS link** - Group chats and WhatsApp support one attachment per message - On iMessage-capable numbers, 2-20 image URLs are delivered as an image carousel > **Deprecation notice:** The `media_url` field (singular) is deprecated and will be removed in a future version. Use `media_urls` (array) instead, even for a single attachment: `media_urls: ["https://..."]`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
bodystringRequired
agent_idstring or nullOptional
to_numberstring or nullOptional

Recipient of an existing chat: a phone (any format, normalized to E.164), US short code, email, or a group id (grp_…). Provide this OR recipients (to start a new group), not both.

recipientslist of strings or nullOptional

Start a NEW iMessage group by listing 2 or more recipients (phones or emails). The first message is delivered to all of them, an iMessage group is created, and the response to_number returns the new group id (grp_…) to use for follow-up sends. iMessage numbers only.

media_urlstring or nullOptional
media_urlslist of strings or nullOptional
number_idstring or nullOptional
from_numberstring or nullOptional
send_styleenumOptional

Optional iMessage expressive effect. Only valid on iMessage-capable numbers. Supported values: celebration, fireworks, lasers, love, confetti, balloons, spotlight, echo, invisible, gentle, loud, slam.

reply_to_message_idstring or nullOptional

Optional parent message ID (AgentPhone Message.id) to send this message as an inline reply in iMessage.

Response

Successful Response
idstring
statusstring
channelstring
from_numberstring
to_numberstring
conversation_idstring or nullOptional
media_urlslist of stringsOptionalDefaults to []
reply_to_message_idstring or nullOptional
reply_parent_unresolvedboolean or nullOptional

Errors

422
Unprocessable Entity Error