For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HomeGet API key
DocumentationIntegrationsAPI Reference
DocumentationIntegrationsAPI Reference
  • API Reference
      • POSTSend Message
      • POSTSend Reaction
LogoLogo
HomeGet API key
API Referencemessages

Send Message

POST
https://api.agentphone.ai/v1/messages
POST
/v1/messages
1const url = 'https://api.agentphone.ai/v1/messages';
2const options = {
3  method: 'POST',
4  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
5  body: '{"agent_id":"agent_12345abcde","to_number":"+14155552671","body":"Hello! Your appointment is confirmed for tomorrow at 3 PM."}'
6};
7
8try {
9  const response = await fetch(url, options);
10  const data = await response.json();
11  console.log(data);
12} catch (error) {
13  console.error(error);
14}
1{
2  "id": "msg_98765zyxwv",
3  "status": "sent",
4  "channel": "sms",
5  "from_number": "+14155550001",
6  "to_number": "+14155552671",
7  "media_urls": [],
8  "reply_to_message_id": "msg_12345abcde",
9  "reply_parent_unresolved": false
10}
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://..."]`.
Was this page helpful?
Previous

Send Reaction

Next
Built with

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.
agent_idstringRequired
to_numberstringRequired
bodystringRequired
media_urlstring or nullOptional
media_urlslist of strings or nullOptional
number_idstring 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
media_urlslist of stringsDefaults to []
reply_to_message_idstring or null
reply_parent_unresolvedboolean or null

Errors

422
Unprocessable Entity Error