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

channelenumOptional

Optional transport override for numbers connected to multiple channels. Pass “whatsapp” to send via the number’s WhatsApp connection instead of its default SMS/iMessage transport. WhatsApp-only numbers use WhatsApp automatically.

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.

buttonslist of strings or nullOptional

WhatsApp only: up to 3 tappable reply buttons (each max 20 chars). The tapped button’s text arrives as a normal inbound message.

listobject or nullOptional

WhatsApp only: a tap-to-open list menu. {“button”: “View options”, “options”: [“Small”, “Medium”, “Large”]} (max 10 options, 24 chars each), or full form with sections: {“button”: str, “sections”: [{“title”: str, “rows”: [{“id”: str, “title”: str, “description”: str}]}]}.

Response

Successful Response

idstring

statusstring

channelstring

from_numberstring

to_numberstring

conversation_idstring or nullOptional

media_urlslist of stringsOptionalDefaults to []