AGagentphone
messages

Send Message

Changed on

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

post/v1/messages

Request

  • Base URL
    https://api.agentphone.ai
  • URL
    https://api.agentphone.ai/v1/messages
  • Auth
    HTTP bearer

Request body

agent_idstring nullable
to_numberstring nullable

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.

recipientsstring[] nullable

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.

bodystring required
media_urlstring nullable
media_urlsstring[] nullable
number_idstring nullable
from_numberstring nullable
channel'whatsapp' nullable

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_style'celebration' | 'fireworks' | 'lasers' | 'love' | 'confetti' | 'balloons' | 'spotlight' | 'echo' | 'invisible' | 'gentle' | 'loud' | 'slam' nullable

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 nullable

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.

buttonsstring[] nullable

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 nullable

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 nullable

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 nullable

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.

Example request

{
  "recipients": [
    "+14155551234",
    "+16505551234"
  ],
  "channel": "whatsapp",
  "send_style": "confetti",
  "reply_to_message_id": "cmat9x3i20000a2m6y3d9r1u2",
  "buttons": [
    "Confirm",
    "Reschedule",
    "Cancel"
  ],
  "cta": {
    "display_text": "Track order",
    "url": "https://example.com/track/123"
  },
  "template": {
    "language": "en_US",
    "name": "order_shipped",
    "variables": [
      "1234"
    ]
  }
}

Response

Successful Response

idstring required
statusstring required
channelstring required
from_numberstring required
to_numberstring required
conversation_idstring nullable
media_urlsstring[]
reply_to_message_idstring nullable
reply_parent_unresolvedboolean nullable

Changes

  • e4bbf7040a0eRevision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

  • 5724ccaa33d8Revision changes
    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property