---
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
  - `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 in iMessage.

## 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/versions/5724ccaa33d8/schema)