Skip to navigation
API Referencemessages

Send Message

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

WhatsApp sends need channel: "whatsapp" and are subject to Meta’s 24-hour customer service window: a free-form message only reaches someone who messaged you in the last 24 hours, and outside that window you need an approved template. WhatsApp also unlocks buttons, list, and cta. See the WhatsApp guide for the full rules.

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
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.

Allowed values:
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. Supported on iMessage and WhatsApp; the parent must be in the same chat and sent from the same number.

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. Pass media_urls alongside buttons to render that image, video, or document as a header above the text, in the same bubble as the buttons (audio has no header form and is rejected).

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}]}]}.

ctaobject or nullOptional

WhatsApp only: a single tappable link button on an ordinary message. {"display_text": "Track order", "url": "https://example.com/t/123", "footer": "Tap to see live status"} — footer is optional. The url must be absolute and https. Unlike a URL button on a template this needs no Meta review, but as an ordinary message it only reaches someone inside the 24h window.

templateobject or nullOptional

WhatsApp only: send a Meta-approved message template. This is the only way to reach someone outside the 24h customer service window. {"name": "order_shipped", "language": "en_US", "variables": ["1234"]} — variables fill the template body, and header_variables does the same for a text header. Pass an array for a POSITIONAL template ({{1}}, {{2}}) or an object for a NAMED one, e.g. {"variables": {"first_name": "Pablo"}} for a body reading "Thanks {{first_name}}!". The shape must match how the template was authored. language defaults to en_US. The template must already be APPROVED (see the templates endpoints). body is NOT delivered for template sends — WhatsApp renders the approved template content — it is kept only as a fallback label if we can't render the template for your message history.

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