Enviar mensagens
Enviar botões
Envie botões de resposta ou de link no WhatsApp, e botões de ação no Instagram e no Messenger, com POST /v1/messages.
POST /v1/messages com type: "interactive" envia botões de resposta ou de link no WhatsApp. No Instagram e no Messenger, o equivalente é type: "buttons". Os campos que valem para todos os envios estão em Campos comuns.
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.
- Mensagem interativa é mensagem livre: só sai dentro da janela de 24 horas depois da última mensagem do contato (veja Janelas). Fora dela, use um template.
Botões de resposta (WhatsApp)
Seção intitulada “Botões de resposta (WhatsApp)”interactive.type: "button" mostra de 1 a 3 botões. Quando o contato toca em um, o id do botão volta para você.
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": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Seu pedido" }, "body": { "text": "Seu pedido #123 chegou. Deu tudo certo?" }, "footer": { "text": "Responda em um toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } } }'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": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Seu pedido" }, "body": { "text": "Seu pedido #123 chegou. Deu tudo certo?" }, "footer": { "text": "Responda em um toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } }});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": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Seu pedido" }, "body": { "text": "Seu pedido #123 chegou. Deu tudo certo?" }, "footer": { "text": "Responda em um toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sim" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } }}Substitua mj_... pela sua chave de API.
| Campo | Regra |
|---|---|
interactive.body.text |
Obrigatório, de 1 a 1024 caracteres. |
interactive.header |
Opcional. { "type": "text", "text": "…" } com até 60 caracteres. O tipo também pode ser image, video ou document. |
interactive.footer.text |
Opcional, até 60 caracteres. |
interactive.action.buttons |
De 1 a 3 itens { "type": "reply", "reply": { "id", "title" } }. |
reply.id |
De 1 a 256 caracteres. É o que você recebe de volta. |
reply.title |
De 1 a 20 caracteres. É o texto do botão. |
Botão com link (cta_url)
Seção intitulada “Botão com link (cta_url)”interactive.type: "cta_url" mostra um único botão que abre uma URL. header e footer são opcionais, como nos botões de resposta.
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": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe a entrega pelo link." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } } }'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": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe a entrega pelo link." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } }});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": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Acompanhe a entrega pelo link." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } }}Substitua mj_... pela sua chave de API.
display_text tem de 1 a 20 caracteres e url é a página que abre.
Receber o clique
Seção intitulada “Receber o clique”O toque chega como um evento message.received, com data.message.content do tipo reply:
{ "type": "message.received", "data": { "message": { "direction": "inbound", "content": { "type": "reply", "kind": "button", "id": "sim", "title": "Sim", "description": null, "payload": null } } }}id e title são os do botão tocado. Ligue o id à sua lógica, e não o texto, que você pode mudar.
Instagram e Messenger
Seção intitulada “Instagram e Messenger”Nesses canais use type: "buttons": um texto de 1 a 640 caracteres e de 1 a 3 botões. Cada botão é postback (title de 1 a 20 e payload de 1 a 1000 caracteres, devolvido quando o contato toca) ou web_url (title de 1 a 20 e url com https). quick_replies também é aceito.
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": "17841400000000000", "type": "buttons", "buttons": { "text": "Como podemos ajudar?", "buttons": [ { "type": "postback", "title": "Falar com vendas", "payload": "vendas" }, { "type": "web_url", "title": "Ver site", "url": "https://exemplo.com" } ] } }'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": "17841400000000000", "type": "buttons", "buttons": { "text": "Como podemos ajudar?", "buttons": [ { "type": "postback", "title": "Falar com vendas", "payload": "vendas" }, { "type": "web_url", "title": "Ver site", "url": "https://exemplo.com" } ] }});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": "17841400000000000", "type": "buttons", "buttons": { "text": "Como podemos ajudar?", "buttons": [ { "type": "postback", "title": "Falar com vendas", "payload": "vendas" }, { "type": "web_url", "title": "Ver site", "url": "https://exemplo.com" } ] }}Substitua mj_... pela sua chave de API.
Para vários cartões com imagem, título e botões, use type: "cards": de 1 a 10 cartões, com title de até 80 caracteres e, se quiser, subtitle, image_url, default_url e buttons. Veja Tipos de mensagem.
Outros tipos interativos
Seção intitulada “Outros tipos interativos”- Fluxos (Flows): Flows.
- Catálogo, produtos e pedido com Pix: Vendas no WhatsApp.
- Pedido de permissão de ligação: Ligações.
- Lista de opções: Enviar lista.
Erros comuns
Seção intitulada “Erros comuns”outside_service_window(422): fora das 24 horas (janelas). O fim da janela vem emdetails[0].message.type_not_supported_by_channel(422): o canal não aceita esse tipo. Exemplo:interactiveno Instagram ou no Messenger, oubuttonsno WhatsApp.validation_failed(400): corpo fora das regras, como mais de 3 botões ou título acima do limite.