Send Message
Send a message through the selected number’s transport. Use channel=“whatsapp” for a WhatsApp connection; see the WhatsApp guide for its 24-hour window and template requirements. Enabled branded RCS senders have separate onboarding and content rules; see /documentation/guides/rcs.
Use media_urls for public HTTPS attachments, not both media_url and media_urls. WhatsApp and group sends accept one attachment; other eligible transports accept up to 20. Use an empty body for media-only messages. Some iMessage lines reject text with multi-image carousels; native iMessage voice memos require one audio file and no text. Branded RCS cannot mix body text with media_urls; see RCS rich cards for the HTTP payload.
Use to_number for an existing recipient/group, or recipients to create a supported group. Unsupported feature/number combinations return errors. A send response is not proof of delivery; inspect message history for status, failureReason, and deliveredChannel. See /documentation/guides/messages.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Request
Message text. Use an empty string for media-only sends. Text plus media is transport-dependent: voice memos, some iMessage carousels, and branded RCS media messages cannot include body text.
Recipient phone/address or an existing group identifier. Preserve group identifiers returned by the API. Supply to_number or recipients, not both.
Create a new group on a supported number. Use 2–32 distinct recipients on eligible iMessage lines, or 2–10 phone numbers on supported carrier MMS lines. Mutually exclusive with to_number; response to_number is the group address for later sends. Group sends accept at most one attachment. WhatsApp and branded RCS groups are unsupported.
Single public HTTPS attachment URL. Prefer media_urls and do not supply both fields.
Public HTTPS attachments, 1–20 on eligible transports. WhatsApp and groups accept one. Some iMessage lines reject text alongside multiple images. Native iMessage voice memos require one audio file and an empty body. Branded RCS media sends accept one file and no body text; see RCS rich cards for an image with text.
Select an attached sending number explicitly. When omitted, an eligible number is chosen automatically; attachment order is not a default-number guarantee.
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.
Optional iMessage expressive effect. Only valid on iMessage-capable numbers. Supported values: celebration, fireworks, lasers, love, confetti, balloons, spotlight, echo, invisible, gentle, loud, slam.
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.
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}]}]}.
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.
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.