Enviar mensagens
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
Seção intitulada “Antes de começar”- Uma chave de API com a permissão
send(veja Autenticação). - 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). Fora dela, use um template.
Enviar um texto
Seção intitulada “Enviar um texto”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." } }'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." },});Configurações do nó HTTP Request do n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticação: Generic Credential Type, depois Header Auth. Nome:
Authorization; Valor:Bearer mj_... - Cabeçalhos: ative Send Headers e adicione
Idempotency-Key(um valor único por item) - Corpo: ative Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Olá! Seu pedido saiu para entrega." }}Substitua mj_... pela sua chave de API.
Resposta
Seção intitulada “Resposta”A resposta é 201:
{ "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.statussai comoqueued. A entrega e a leitura chegam depois, no eventomessage.status.meta_statuséaccepted,held_for_quality_assessment,pausedounull.
Prévia de link
Seção intitulada “Prévia de link”No WhatsApp, text.preview_url: true pede que o link da mensagem apareça com prévia.
{ "type": "text", "text": { "body": "Acompanhe em https://exemplo.com/pedido/123", "preview_url": true } }Responder a uma mensagem
Seção intitulada “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.
Digitando e atraso
Seção intitulada “Digitando e atraso”typing: truemostra o indicador de “digitando” antes de a mensagem sair.delay_msespera 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).
Campos comuns
Seção intitulada “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. |
Cabeçalho Idempotency-Key |
Evita envio duplicado ao repetir a chamada; vale 24 horas (veja Idempotência). |
Campo desconhecido no corpo é recusado com 400 validation_failed.
Limites e canais
Seção intitulada “Limites e canais”| Canal | Tamanho do texto |
|---|---|
| 1 a 4096 caracteres | |
| 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.
Com to: "grp_…" o WhatsApp aceita texto, mídia e template. Veja Grupos.
Erros comuns
Seção intitulada “Erros comuns”outside_service_window(422): fora das 24 horas. O fim da janela vem emdetails[0].message.connection_rate_limited(429): sem ficha no balde do número. Espere oRetry-After(ouretry_after_ms) e repita.pair_rate_limited(429): mensagens demais para o mesmo contato em pouco tempo.recipient_unavailable(422): a Meta não conseguiu entregar a esse destino.type_not_supported_by_channel(422): o canal não aceita esse tipo.meta_unknown_outcome(502): não se sabe se a mensagem saiu. Não reenvie às cegas; confira antes.connection_needs_reconnect(409): a conexão perdeu o acesso e precisa ser reconectada.