---
title: "Send a message"
method: POST
path: "/v1/messages/text"
tags: ["Messages"]
---

# Send a message

`POST /v1/messages/text`

## Request

- Base URL: `https://www.chatrail.dev`
- URL: `https://www.chatrail.dev/v1/messages/text`
- Auth: HTTP bearer

Accepts a message for delivery and returns 202. **202 means accepted, never delivered** — the message is durably stored and queued, and only the `status` field ever claims delivery. Send `media` or `location` for an attachment, `send_at` to defer it. Supply `Idempotency-Key` so a retry cannot send twice.

## Request body

- object
  - `connection` string, required
  - `to` union, required
    - string
    - object
      - `phone` string, required
    - object
      - `group` string, required
  - `body` string
  - `media` object
    - `url` string, uri, required
    - `kind` 'image' | 'video' | 'audio' | 'document'
    - `mimetype` string
    - `filename` string
  - `location` object
    - `latitude` number, required
    - `longitude` number, required
    - `title` string
  - `contact` object
    - `name` string, required
    - `phone` string, required
    - `organization` string
  - `poll` object
    - `question` string, required
    - `options` string[], required
    - `multiple_answers` boolean
  - `reply_to` string, uuid
  - `mentions` string[]
  - `link_preview` boolean
  - `context` object
  - `metadata` object
  - `pause_ai` boolean
  - `context_sensitivity` 'normal' | 'sensitive' | 'restricted'
  - `send_at` string, date-time
  - `timezone` string

## Response `202`

Accepted and queued.

## Other responses

- `400`: The body, recipient or attachment was rejected.
- `402`: The plan does not include this. The message names what would allow it.
- `409`: The connection is not ready, or an identical Idempotency-Key is in flight.
- `422`: The Idempotency-Key was reused with a different body.
- `429`: Quota or rate limit.

---

[API](https://skmtc.dev/chatrail/apis/chatrail-api.md) · [All operations](https://skmtc.dev/chatrail/apis/chatrail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chatrail/apis/chatrail-api/revisions/acc5b88c6f59?raw)