Enviar mensajes
Enviar botones
Envía botones de respuesta o de enlace en WhatsApp, y botones de acción en Instagram y Messenger, con POST /v1/messages.
POST /v1/messages con type: "interactive" envía botones de respuesta o de enlace en WhatsApp. En Instagram y Messenger el equivalente es type: "buttons". Los campos comunes a todos los envíos están en Campos comunes.
Antes de empezar
Sección titulada «Antes de empezar»- Una clave de API con el permiso
send(consulta Autenticación). - Una conexión Activa del canal.
- Un mensaje interactivo es un mensaje libre: solo sale dentro de las 24 horas posteriores al último mensaje del contacto (consulta Ventanas). Fuera de ella, usa una plantilla.
Botones de respuesta (WhatsApp)
Sección titulada «Botones de respuesta (WhatsApp)»interactive.type: "button" muestra de 1 a 3 botones. Cuando el contacto toca uno, el id del botón te vuelve.
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": "Tu pedido" }, "body": { "text": "Tu pedido #123 llegó. ¿Todo salió bien?" }, "footer": { "text": "Responde con un toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sí" } }, { "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": "Tu pedido" }, "body": { "text": "Tu pedido #123 llegó. ¿Todo salió bien?" }, "footer": { "text": "Responde con un toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sí" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } }});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "button", "header": { "type": "text", "text": "Tu pedido" }, "body": { "text": "Tu pedido #123 llegó. ¿Todo salió bien?" }, "footer": { "text": "Responde con un toque" }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "sim", "title": "Sí" } }, { "type": "reply", "reply": { "id": "nao", "title": "Não" } } ] } }}Sustituye mj_... por tu clave de API.
| Campo | Regla |
|---|---|
interactive.body.text |
Obligatorio, de 1 a 1024 caracteres. |
interactive.header |
Opcional. { "type": "text", "text": "…" } con hasta 60 caracteres. El tipo también puede ser image, video o document. |
interactive.footer.text |
Opcional, hasta 60 caracteres. |
interactive.action.buttons |
De 1 a 3 elementos { "type": "reply", "reply": { "id", "title" } }. |
reply.id |
De 1 a 256 caracteres. Es lo que recibes de vuelta. |
reply.title |
De 1 a 20 caracteres. Es el texto del botón. |
Botón con enlace (cta_url)
Sección titulada «Botón con enlace (cta_url)»interactive.type: "cta_url" muestra un único botón que abre una URL. header y footer son opcionales, igual que en los botones de respuesta.
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": "Sigue la entrega con el enlace." }, "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": "Sigue la entrega con el enlace." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } }});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "interactive", "interactive": { "type": "cta_url", "body": { "text": "Sigue la entrega con el enlace." }, "action": { "name": "cta_url", "parameters": { "display_text": "Rastrear pedido", "url": "https://exemplo.com/pedido/123" } } }}Sustituye mj_... por tu clave de API.
display_text tiene de 1 a 20 caracteres y url es la página que abre.
Recibir el toque
Sección titulada «Recibir el toque»El toque llega como un evento message.received, con data.message.content de tipo reply:
{ "type": "message.received", "data": { "message": { "direction": "inbound", "content": { "type": "reply", "kind": "button", "id": "sim", "title": "Sí", "description": null, "payload": null } } }}id y title son los del botón tocado. Enlaza tu lógica al id, no al texto, que puedes cambiar.
Instagram y Messenger
Sección titulada «Instagram y Messenger»En estos canales usa type: "buttons": un texto de 1 a 640 caracteres y de 1 a 3 botones. Cada botón es postback (title de 1 a 20 y payload de 1 a 1000 caracteres, devuelto cuando el contacto toca) o web_url (title de 1 a 20 y url con https). También se acepta quick_replies.
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": "¿Cómo podemos ayudar?", "buttons": [ { "type": "postback", "title": "Hablar con ventas", "payload": "vendas" }, { "type": "web_url", "title": "Ver sitio", "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": "¿Cómo podemos ayudar?", "buttons": [ { "type": "postback", "title": "Hablar con ventas", "payload": "vendas" }, { "type": "web_url", "title": "Ver sitio", "url": "https://exemplo.com" } ] }});Ajustes del nodo HTTP Request de n8n
- Método:
POST - URL:
https://api.messajo.com/v1/messages - Autenticación: Generic Credential Type, luego Header Auth. Nombre:
Authorization; Valor:Bearer mj_... - Encabezados: activa Send Headers y añade
Idempotency-Key(un valor único por ítem) - Cuerpo: activa Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "17841400000000000", "type": "buttons", "buttons": { "text": "¿Cómo podemos ayudar?", "buttons": [ { "type": "postback", "title": "Hablar con ventas", "payload": "vendas" }, { "type": "web_url", "title": "Ver sitio", "url": "https://exemplo.com" } ] }}Sustituye mj_... por tu clave de API.
Para varias tarjetas con imagen, título y botones, usa type: "cards": de 1 a 10 tarjetas, con title de hasta 80 caracteres y, si quieres, subtitle, image_url, default_url y buttons. Consulta Tipos de mensaje.
Otros tipos interactivos
Sección titulada «Otros tipos interactivos»- Flujos (Flows): Flows.
- Catálogo, productos y pedido con Pix: Ventas en WhatsApp.
- Solicitud de permiso de llamada: Llamadas.
- Lista de opciones: Enviar lista.
Errores comunes
Sección titulada «Errores comunes»outside_service_window(422): fuera de las 24 horas (ventanas). El fin de la ventana viene endetails[0].message.type_not_supported_by_channel(422): el canal no acepta ese tipo. Por ejemplo,interactiveen Instagram o Messenger, obuttonsen WhatsApp.validation_failed(400): el cuerpo incumple las reglas, como más de 3 botones o un título por encima del límite.