# Enviar texto

> Envie uma mensagem de texto com POST /v1/messages por WhatsApp, Instagram ou Messenger, com prévia de link, resposta, "digitando" e atraso.

`POST /v1/messages` com `type: "text"` envia texto livre. Funciona no WhatsApp, no Instagram e no Messenger.

## Antes de começar

- Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)).
- Uma conexão **Ativa** do canal que você vai usar.
- Mensagem livre só sai dentro da janela de 24 horas depois da última mensagem do contato (veja [Janelas](/api/limits/#janelas)). Fora dela, use um template.

## Enviar um texto

**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": "Olá! Seu pedido saiu para entrega." }
  }'
```

**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: "Olá! Seu pedido saiu para entrega." },
});
```

**n8n**

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

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "text",
  "text": { "body": "Olá! Seu pedido saiu para entrega." }
}
```

## Resposta

A resposta é `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` é o id da mensagem no Messajo (`msg_…`); `external_id` é o da Meta.
- `status` sai como `queued`. A entrega e a leitura chegam depois, no evento `message.status`.
- `meta_status` é `accepted`, `held_for_quality_assessment`, `paused` ou `null`.

## Prévia de link

No WhatsApp, `text.preview_url: true` pede que o link da mensagem apareça com prévia.

```json
{ "type": "text", "text": { "body": "Acompanhe em https://exemplo.com/pedido/123", "preview_url": true } }
```

## Responder a uma mensagem

`reply_to` cita uma mensagem anterior. Aceita o id do Messajo (`msg_…`) ou o id da Meta. Um `msg_…` que não existe volta `404` [`not_found`](/errors#not_found).

## Digitando e atraso

- `typing: true` mostra o indicador de "digitando" antes de a mensagem sair.
- `delay_ms` espera de 0 a 20000 milissegundos antes de enviar (padrão 0).

O `typing` também gasta uma ficha do balde do número (veja [Limites](/api/limits/)).

## Campos comuns

Valem para todas as páginas de envio.

| Campo | Descrição |
|---|---|
| `connection_id` | Conexão que envia. Opcional com chave de conexão (`mjc_…`); obrigatório com chave de organização (`mj_…`). |
| `to` | Destino. WhatsApp: telefone com código do país (só dígitos contam), BSUID, `ctc_…` (contato) ou `grp_…` (grupo). Instagram: IGSID ou `ctc_…`. Messenger: PSID ou `ctc_…`. |
| `type` | Tipo da mensagem. Aqui, `text`. |
| `reply_to` | Mensagem citada: `msg_…` ou id da Meta. |
| `typing` | `true` mostra "digitando" antes do envio. Padrão `false`. |
| `delay_ms` | Espera antes do envio, de 0 a 20000. Padrão 0. |
| `biz_opaque_callback_data` | WhatsApp: texto de até 512 caracteres devolvido junto do status. |
| `tag` | `"human_agent"`, só no Instagram e no Messenger. No WhatsApp volta `422` [`tag_not_supported_by_channel`](/errors#tag_not_supported_by_channel). |
| Cabeçalho `Idempotency-Key` | Evita envio duplicado ao repetir a chamada; vale 24 horas (veja [Idempotência](/start/concepts/#idempotência)). |

Campo desconhecido no corpo é recusado com `400` [`validation_failed`](/errors#validation_failed).

## Limites e canais

| Canal | Tamanho do texto |
|---|---|
| WhatsApp | 1 a 4096 caracteres |
| Instagram | até 1.000 bytes |
| Messenger | até 2.000 caracteres |

No Instagram e no Messenger, `text.quick_replies` aceita de 1 a 13 itens `{ "title", "payload" }`, com `title` de até 20 e `payload` de até 1000 caracteres. `text.preview_url` é do WhatsApp.

## Grupos

Com `to: "grp_…"` o WhatsApp aceita texto, mídia e template. Veja [Grupos](/guides/groups/).

## Erros comuns

- [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas. O fim da janela vem em `details[0].message`.
- [`connection_rate_limited`](/errors#connection_rate_limited) (429): sem ficha no balde do número. Espere o `Retry-After` (ou `retry_after_ms`) e repita.
- [`pair_rate_limited`](/errors#pair_rate_limited) (429): mensagens demais para o mesmo contato em pouco tempo.
- [`recipient_unavailable`](/errors#recipient_unavailable) (422): a Meta não conseguiu entregar a esse destino.
- [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel) (422): o canal não aceita esse tipo.
- [`meta_unknown_outcome`](/errors#meta_unknown_outcome) (502): não se sabe se a mensagem saiu. Não reenvie às cegas; confira antes.
- [`connection_needs_reconnect`](/errors#connection_needs_reconnect) (409): a conexão perdeu o acesso e precisa ser reconectada.
