Empezar
Empezar en 5 minutos
De una cuenta nueva a la primera llamada a la API y al primer mensaje, paso a paso.
Antes de empezar
Sección titulada «Antes de empezar»Necesitas una cuenta en app.messajo.com. También una terminal con curl.
En los ejemplos, la API está en https://api.messajo.com/v1.
1. Crear la cuenta y la organización
Sección titulada «1. Crear la cuenta y la organización»- Abre el panel y haz clic en Crear cuenta. Ingresa nombre, correo y contraseña.
- Confirma el correo con el enlace que llega a tu bandeja de entrada.
- Ponle un nombre a tu organización. Te conviertes en su propietario.
Todo en Messajo — conexiones, claves, destinos de eventos — pertenece a la organización, no a la persona. Consulta Conceptos.
2. Activar el 2FA
Sección titulada «2. Activar el 2FA»La verificación en dos pasos es obligatoria para propietario y admin. Sin ella, el panel bloquea las áreas de la organización, incluida la creación de claves.
- En Configuración → Seguridad, activa la Verificación en dos pasos (2FA).
- Escanea el código QR con una app autenticadora (Google Authenticator, 1Password, Authy…) y escribe el código de 6 dígitos.
- Guarda los códigos de respaldo en un lugar seguro: son la salida si pierdes el teléfono.
3. Crear una clave de API
Sección titulada «3. Crear una clave de API»- Abre Claves de API y haz clic en Crear clave.
- Ponle un nombre (por ejemplo,
prueba) y marca solo el permiso Leer (read), que basta para esta guía. - Deja Todas las conexiones, elige la validez y confirma.
La clave completa, que empieza con mj_, aparece una sola vez. Cópiala y guárdala en una variable de entorno:
export MESSAJO_API_KEY="mj_..."Detalles en Autenticación y claves de API.
4. Probar con GET /v1/me
Sección titulada «4. Probar con GET /v1/me»GET /v1/me acepta cualquier clave válida y devuelve la organización y la propia clave. Es la forma más rápida de confirmar que la autenticación funciona.
curl https://api.messajo.com/v1/me \ -H "Authorization: Bearer $MESSAJO_API_KEY"// npm install @messajo/sdkimport { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });const me = await messajo.me.get();console.log(me.organization.name, me.api_key.permissions);import os
import requests
response = requests.get( "https://api.messajo.com/v1/me", headers={"Authorization": f"Bearer {os.environ['MESSAJO_API_KEY']}"}, timeout=10,)response.raise_for_status()me = response.json()print(me["organization"]["name"], me["api_key"]["permissions"])Respuesta 200 OK:
{ "organization": { "id": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu", "name": "Acme", "slug": "acme" }, "api_key": { "id": "Zt5rB8wQ1nXc4LmV7pYd2sGf9hJk3aRe", "name": "prueba", "start": "mj_A1b2c3d", "permissions": ["read"], "connection_ids": null, "kind": "org", "connection_id": null, "connection": null, "expires_at": "2027-01-01T00:00:00.000Z" }, "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b"}startes el prefijo visible de la clave, el mismo que muestra el panel.kindesorg(clavemj_) oconnection(clavemjc_). En una clave de conexión,connection_idyconnection { id, channel, label }identifican su conexión; en una de organización sonnull.connection_ids: nullsignifica que la clave de organización vale para todas las conexiones; en una clave de conexión trae solo el id de su conexión.expires_atesnullcuando la clave no vence.
¿Recibiste 401? El cuerpo trae el code del error, por ejemplo missing_api_key (falta el encabezado) o invalid_api_key (clave incorrecta o revocada).
5. Conectar un número de WhatsApp
Sección titulada «5. Conectar un número de WhatsApp»- En el panel, abre Conexiones → Conectar WhatsApp.
- Elige el modo: Mantener mi WhatsApp Business (coexistencia: el número sigue en la app) o Número nuevo, solo por la API, y haz clic en Continuar.
- Haz clic en Abrir la ventana de Meta, sigue el registro oficial de Meta en la ventana que se abre y espera a que el panel muestre WhatsApp conectado.
La conexión aparece como Activa, con un id con formato conn_…, que se usa en las llamadas de envío (la lista también está en GET /v1/connections). El paso a paso completo está en Conectar WhatsApp.
6. Enviar el primer mensaje
Sección titulada «6. Enviar el primer mensaje»Crea una clave con el permiso send y llama a POST /v1/messages. Un mensaje libre solo sale hacia un contacto que te escribió en las últimas 24 horas; fuera de esa ventana, usa una plantilla aprobada (consulta Conceptos).
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": "5491122334455", "type": "text", "text": { "body": "¡Hola! Mensaje enviado con Messajo." } }'const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "¡Hola! Mensaje enviado con Messajo." },});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": "5491122334455", "type": "text", "text": { "body": "¡Hola! Mensaje enviado con Messajo." }}Sustituye mj_... por tu clave de API.
El SDK genera el Idempotency-Key solo y repite con seguridad cuando falla la red. Consulta SDK de TypeScript.
Con clave de conexión
Sección titulada «Con clave de conexión»Si tu código solo habla con un número, crea una clave de conexión (mjc_…) en el panel de la propia conexión, en Claves de API. Ya sabe a qué conexión pertenece: el connection_id del cuerpo desaparece y la clave no alcanza otras conexiones. Una clave de organización (mj_) sigue exigiendo el connection_id.
curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_CONNECTION_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "to": "5511999999999", "type": "text", "text": { "body": "¡Hola!" } }'const sent = await messajo.connection().messages.send({ to: "5511999999999", type: "text", text: { body: "¡Hola!" },});Ver Tipos de clave.
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"}external_id es el id de Meta (wamid). La entrega y la lectura llegan después, en el evento message.status. Fuera de la ventana, la respuesta es 422 outside_service_window. Cada tipo tiene su propia página en el grupo Enviar mensajes, empezando por Enviar texto; los campos de cada uno están también en la referencia de la API.
7. Recibir el webhook
Sección titulada «7. Recibir el webhook»- En Destinos de eventos, registra la URL HTTPS que va a recibir los eventos. El panel muestra el secreto (
whsec_…) una vez. - Responde
2xxen hasta 10 segundos. Si no, Messajo reintenta con esperas crecientes durante hasta 24 horas. - Envía un mensaje a tu número: llega un evento
message.received.
{ "id": "evt_...", "type": "message.received", "format": "normalized", "org": "Kq3vT9xZ2mWb7LpR4nYc8sDf1gHj6aEu", "connection": "conn_...", "channel": "whatsapp", "timestamp": "2026-11-09T12:00:00.000Z", "sequence": 1, "data": {}}El contenido de data depende del tipo de evento y del formato del destino. Antes de confiar en el cuerpo, verifica el encabezado Messajo-Signature con el secreto: consulta Verificar la firma. El catálogo completo está en Eventos.
Próximos pasos
Sección titulada «Próximos pasos»- Conceptos: organizaciones, conexiones, claves y las dos capas de la API.
- Autenticación y claves de API: permisos, validez y buenas prácticas.
- Errores y Límites: qué manejar en tu código.
- Verificar la firma: obligatorio antes de ir a producción.
- SDK de TypeScript, Historial y Campañas.
- Enviar texto: la primera de una página por tipo de mensaje.
- Construir con IA:
llms.txt, Markdown por página y el archivo OpenAPI.