---
title: "Send Message"
method: POST
path: "/v1/messages"
tags: ["messages"]
---

# Send Message

`POST /v1/messages`

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

## Request body

- SendMessageRequest
  - `agent_id` string, nullable
  - `to_number` string, 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.
  - `recipients` string[], 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.
  - `body` string, required
  - `media_url` string, nullable
  - `media_urls` string[], nullable
  - `number_id` string, nullable
  - `from_number` string, 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_id` string, 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.
  - `buttons` string[], 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).
  - `list` object, 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}]}]}.
  - `cta` object, 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.
  - `template` object, 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.

## Response `200`

Successful Response

- SendMessageResponse
  - `id` string, required
  - `status` string, required
  - `channel` string, required
  - `from_number` string, required
  - `to_number` string, required
  - `conversation_id` string, nullable
  - `media_urls` string[]
  - `reply_to_message_id` string, nullable
  - `reply_parent_unresolved` boolean, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentphone/apis/agentphone-api.md) · [All operations](https://skmtc.net/agentphone/apis/agentphone-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentphone/agentphone-api/revisions/e4bbf7040a0e/schema)