Send Message | AgentPhone

Send an outbound message (SMS or iMessage) via the provider assigned to the number.

Attach media by passing public HTTPS URLs in media_urls.

Single attachment

Pass a single-item array in media_urls. The URL must be publicly accessible.

Carousel / multi-image (iMessage)

To send a carousel of images on iMessage, pass 2-20 URLs in media_urls. Requirements:

Each URL must be a publicly accessible HTTPS link to an image (JPEG, PNG, GIF, etc.)
Minimum 2 URLs, maximum 20
body must be omitted or empty (text cannot be sent alongside a carousel)
Only supported on iMessage-capable lines

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, pass it as media_urls: ["https://..."].

Send an outbound message (SMS or iMessage) via the provider assigned to the number. Attach media by passing public HTTPS URLs in `media_urls`. ### Single attachment Pass a single-item array in `media_urls`. The URL must be publicly accessible. ### Carousel / multi-image (iMessage) To send a carousel of images on iMessage, pass 2-20 URLs in `media_urls`. Requirements: - Each URL must be a **publicly accessible HTTPS link** to an image (JPEG, PNG, GIF, etc.) - Minimum 2 URLs, maximum 20 - `body` must be omitted or empty (text cannot be sent alongside a carousel) - Only supported on iMessage-capable lines > **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, pass it as `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 null

media_urlslist of stringsDefaults to []

reply_to_message_idstring or null

reply_parent_unresolvedboolean or null

Errors

422

Unprocessable Entity Error