# Send text

> Send a text message with POST /v1/messages over WhatsApp, Instagram or Messenger, with link preview, reply, typing indicator and delay.

`POST /v1/messages` with `type: "text"` sends a free-form text message. It works on WhatsApp, Instagram and Messenger.

## Before you start

- An API key with the `send` permission (see [Authentication](/en/api/authentication/)).
- An **Active** connection for the channel you will use.
- Free-form messages only go out within 24 hours of the contact's last message (see [Windows](/en/api/limits/#windows)). Outside it, use a template.

## Send a text

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "connection_id": "conn_...",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Hi! Your order is out for delivery." }
  }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "text",
  text: { body: "Hi! Your order is out for delivery." },
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "text",
  "text": { "body": "Hi! Your order is out for delivery." }
}
```

## Response

The response is `201`:

```json
{
  "id": "msg_...",
  "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ",
  "status": "queued",
  "meta_status": "accepted",
  "conversation_id": "cnv_...",
  "contact_id": "ctc_...",
  "created_at": "2026-11-09T12:00:00.000Z"
}
```

- `id` is the Messajo message id (`msg_…`); `external_id` is Meta's.
- `status` comes back as `queued`. Delivery and read arrive later, in the `message.status` event.
- `meta_status` is `accepted`, `held_for_quality_assessment`, `paused` or `null`.

## Link preview

On WhatsApp, `text.preview_url: true` asks for the link in the message to show a preview.

```json
{ "type": "text", "text": { "body": "Track it at https://example.com/order/123", "preview_url": true } }
```

## Reply to a message

`reply_to` quotes an earlier message. It accepts the Messajo id (`msg_…`) or the Meta id. A `msg_…` that does not exist returns `404` [`not_found`](/en/errors#not_found).

## Typing and delay

- `typing: true` shows the typing indicator before the message goes out.
- `delay_ms` waits 0 to 20000 milliseconds before sending (default 0).

`typing` also spends one token from the number's bucket (see [Limits](/en/api/limits/)).

## Common fields

They apply to every send page.

| Field | Description |
|---|---|
| `connection_id` | Connection that sends. Optional with a connection key (`mjc_…`); required with an organization key (`mj_…`). |
| `to` | Recipient. WhatsApp: phone with country code (only digits count), BSUID, `ctc_…` (contact) or `grp_…` (group). Instagram: IGSID or `ctc_…`. Messenger: PSID or `ctc_…`. |
| `type` | Message type. Here, `text`. |
| `reply_to` | Quoted message: `msg_…` or Meta id. |
| `typing` | `true` shows the typing indicator before sending. Default `false`. |
| `delay_ms` | Wait before sending, 0 to 20000. Default 0. |
| `biz_opaque_callback_data` | WhatsApp: text of up to 512 characters returned with the status. |
| `tag` | `"human_agent"`, Instagram and Messenger only. On WhatsApp it returns `422` [`tag_not_supported_by_channel`](/en/errors#tag_not_supported_by_channel). |
| `Idempotency-Key` header | Prevents duplicate sends when you repeat the call; valid for 24 hours (see [Idempotency](/en/start/concepts/#idempotency)). |

An unknown field in the body is rejected with `400` [`validation_failed`](/en/errors#validation_failed).

## Limits and channels

| Channel | Text length |
|---|---|
| WhatsApp | 1 to 4096 characters |
| Instagram | up to 1,000 bytes |
| Messenger | up to 2,000 characters |

On Instagram and Messenger, `text.quick_replies` takes 1 to 13 items `{ "title", "payload" }`, with `title` up to 20 and `payload` up to 1000 characters. `text.preview_url` is WhatsApp only.

## Groups

With `to: "grp_…"`, WhatsApp accepts text, media and template. See [Groups](/en/guides/groups/).

## Common errors

- [`outside_service_window`](/en/errors#outside_service_window) (422): outside the 24 hours. The window end is in `details[0].message`.
- [`connection_rate_limited`](/en/errors#connection_rate_limited) (429): no token left in the number's bucket. Wait for `Retry-After` (or `retry_after_ms`) and retry.
- [`pair_rate_limited`](/en/errors#pair_rate_limited) (429): too many messages to the same contact in a short time.
- [`recipient_unavailable`](/en/errors#recipient_unavailable) (422): Meta could not deliver to that recipient.
- [`type_not_supported_by_channel`](/en/errors#type_not_supported_by_channel) (422): the channel does not accept this type.
- [`meta_unknown_outcome`](/en/errors#meta_unknown_outcome) (502): it is unknown whether the message went out. Do not resend blindly; check first.
- [`connection_needs_reconnect`](/en/errors#connection_needs_reconnect) (409): the connection lost access and must be reconnected.
