Ir al contenido

Empezar

Empezar en 5 minutos

De una cuenta nueva a la primera llamada a la API y al primer mensaje, paso a paso.

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. Abre el panel y haz clic en Crear cuenta. Ingresa nombre, correo y contraseña.
  2. Confirma el correo con el enlace que llega a tu bandeja de entrada.
  3. 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.

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.

  1. En Configuración → Seguridad, activa la Verificación en dos pasos (2FA).
  2. Escanea el código QR con una app autenticadora (Google Authenticator, 1Password, Authy…) y escribe el código de 6 dígitos.
  3. Guarda los códigos de respaldo en un lugar seguro: son la salida si pierdes el teléfono.
  1. Abre Claves de API y haz clic en Crear clave.
  2. Ponle un nombre (por ejemplo, prueba) y marca solo el permiso Leer (read), que basta para esta guía.
  3. 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:

Ventana de terminal
export MESSAJO_API_KEY="mj_..."

Detalles en Autenticación y claves de API.

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.

Ventana de terminal
curl https://api.messajo.com/v1/me \
-H "Authorization: Bearer $MESSAJO_API_KEY"

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"
}
  • start es el prefijo visible de la clave, el mismo que muestra el panel.
  • kind es org (clave mj_) o connection (clave mjc_). En una clave de conexión, connection_id y connection { id, channel, label } identifican su conexión; en una de organización son null.
  • connection_ids: null significa 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_at es null cuando 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).

  1. En el panel, abre Conexiones → Conectar WhatsApp.
  2. 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.
  3. 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.

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).

Ventana de terminal
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." }
}'

El SDK genera el Idempotency-Key solo y repite con seguridad cuando falla la red. Consulta SDK de TypeScript.

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.

Ventana de terminal
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!" } }'

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.

  1. En Destinos de eventos, registra la URL HTTPS que va a recibir los eventos. El panel muestra el secreto (whsec_…) una vez.
  2. Responde 2xx en hasta 10 segundos. Si no, Messajo reintenta con esperas crecientes durante hasta 24 horas.
  3. 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.