Enviar mensajes
Enviar texto
Envía un mensaje de texto con POST /v1/messages por WhatsApp, Instagram o Messenger, con vista previa de enlace, respuesta, "escribiendo" y retraso.
POST /v1/messages con type: "text" envía texto libre. Funciona en WhatsApp, Instagram y Messenger.
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 que vas a usar.
- El mensaje libre solo sale dentro de las 24 horas posteriores al último mensaje del contacto (consulta Ventanas). Fuera de ella, usa una plantilla.
Enviar un texto
Sección titulada «Enviar un 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": "¡Hola! Tu pedido salió para la 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: "¡Hola! Tu pedido salió para la entrega." },});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": "text", "text": { "body": "¡Hola! Tu pedido salió para la entrega." }}Sustituye mj_... por tu clave de API.
Respuesta
Sección titulada «Respuesta»La respuesta es 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"}ides el id del mensaje en Messajo (msg_…);external_ides el de Meta.statussale comoqueued. La entrega y la lectura llegan después, en el eventomessage.status.meta_statusesaccepted,held_for_quality_assessment,pausedonull.
Vista previa de enlace
Sección titulada «Vista previa de enlace»En WhatsApp, text.preview_url: true pide que el enlace del mensaje se muestre con vista previa.
{ "type": "text", "text": { "body": "Sigue tu pedido en https://ejemplo.com/pedido/123", "preview_url": true } }Responder a un mensaje
Sección titulada «Responder a un mensaje»reply_to cita un mensaje anterior. Acepta el id de Messajo (msg_…) o el id de Meta. Un msg_… que no existe devuelve 404 not_found.
Escribiendo y retraso
Sección titulada «Escribiendo y retraso»typing: truemuestra el indicador de “escribiendo” antes de que salga el mensaje.delay_msespera de 0 a 20000 milisegundos antes de enviar (por defecto 0).
typing también gasta una ficha del balde del número (consulta Límites).
Campos comunes
Sección titulada «Campos comunes»Valen para todas las páginas de envío.
| Campo | Descripción |
|---|---|
connection_id |
Conexión que envía. Opcional con clave de conexión (mjc_…); obligatorio con clave de organización (mj_…). |
to |
Destino. WhatsApp: teléfono con código de país (solo cuentan los dígitos), BSUID, ctc_… (contacto) o grp_… (grupo). Instagram: IGSID o ctc_…. Messenger: PSID o ctc_…. |
type |
Tipo de mensaje. Aquí, text. |
reply_to |
Mensaje citado: msg_… o id de Meta. |
typing |
true muestra “escribiendo” antes del envío. Por defecto false. |
delay_ms |
Espera antes del envío, de 0 a 20000. Por defecto 0. |
biz_opaque_callback_data |
WhatsApp: texto de hasta 512 caracteres devuelto junto con el estado. |
tag |
"human_agent", solo en Instagram y Messenger. En WhatsApp devuelve 422 tag_not_supported_by_channel. |
Encabezado Idempotency-Key |
Evita envíos duplicados al repetir la llamada; vale 24 horas (consulta Idempotencia). |
Un campo desconocido en el cuerpo se rechaza con 400 validation_failed.
Límites y canales
Sección titulada «Límites y canales»| Canal | Tamaño del texto |
|---|---|
| de 1 a 4096 caracteres | |
| hasta 1.000 bytes | |
| Messenger | hasta 2.000 caracteres |
En Instagram y Messenger, text.quick_replies acepta de 1 a 13 elementos { "title", "payload" }, con title de hasta 20 y payload de hasta 1000 caracteres. text.preview_url es solo de WhatsApp.
Con to: "grp_…", WhatsApp acepta texto, multimedia y plantilla. Consulta Grupos.
Errores comunes
Sección titulada «Errores comunes»outside_service_window(422): fuera de las 24 horas. El fin de la ventana viene endetails[0].message.connection_rate_limited(429): sin fichas en el balde del número. Espera elRetry-After(oretry_after_ms) y repite.pair_rate_limited(429): demasiados mensajes al mismo contacto en poco tiempo.recipient_unavailable(422): Meta no pudo entregar a ese destino.type_not_supported_by_channel(422): el canal no acepta ese tipo.meta_unknown_outcome(502): no se sabe si el mensaje salió. No reenvíes a ciegas; comprueba primero.connection_needs_reconnect(409): la conexión perdió el acceso y debe reconectarse.