Ir al contenido

Empezar

Conceptos

Las piezas de Messajo: organización, conexiones, claves, destinos de eventos y las dos capas de la API.

Todo pertenece a una organización: conexiones, claves de API, destinos de eventos, plantillas y logs. Una persona puede ser miembro de varias organizaciones y cambia entre ellas en el panel. Cada miembro tiene un rol:

Rol Puede
Propietario Todo, incluida la facturación y eliminar la organización. Solo un propietario asciende o degrada a otro propietario, y la organización nunca se queda sin uno
Admin Conexiones, miembros e invitaciones, claves de API, destinos de eventos, plantillas, logs y auditoría
Dev Claves de API (sin el permiso admin), destinos de eventos, plantillas y logs. Ve las conexiones, pero no las crea ni las cambia
Lectura Solo ve: claves (sin el secreto), conexiones, destinos, plantillas y logs

Propietario y admin deben tener la verificación en dos pasos (2FA) activada para usar el panel de la organización.

El propietario puede restablecer el 2FA de otro miembro en Miembros: la persona se desconecta y configura un nuevo autenticador en el próximo inicio de sesión. Para el propietario único que perdió el autenticador, lo restablece quien administra la instancia. La invitación solo vale mientras quien la envió aún pueda conceder el rol (invitation_invalid).

Acceso por conexión. Dev y Lectura pueden tener acceso a todas las conexiones o solo a algunas (acceso restringido). El rol sigue siendo el mismo; el acceso solo define lo que el miembro ve. Propietario y admin siempre ven todo. El miembro restringido no ve las otras conexiones, ni los avisos que no son de una conexión suya (facturación, estado de la organización, miembros), y solo crea claves de las conexiones a las que tiene acceso. Las claves que creó y que quedan fuera del nuevo acceso se revocan, salvo que quien cambia el acceso elija conservarlas. Consulta Autenticación y claves de API.

Cuando la organización cambia de slug, el anterior queda reservado por 90 días: otra organización no puede usarlo y la propia organización puede volver a él.

Cada pantalla de la organización lleva el slug en la dirección: /<slug>/api-keys, /<slug>/members. Las pestañas abiertas en organizaciones distintas no se mezclan. La cuenta de la persona está en /account.

  • Cambiar el slug (solo el dueño, con contraseña y código 2FA): la dirección anterior sigue redirigiendo durante 90 días.
  • Límite de organizaciones por usuario: ORG_LIMIT_PER_USER (por defecto 5). Pasado el límite, crear otra organización falla con org_limit_reached.
  • Zona horaria de la organización: las fechas de los correos (invitaciones, avisos) usan la zona configurada en Organización.
  • Correo de los miembros: solo dueño y admin lo ven; los demás roles ven el nombre.

Una conexión es una cuenta de Meta vinculada a la organización. Cada conexión tiene un canal:

Canal La conexión es Cómo se vincula
whatsapp Un número de WhatsApp Business, en coexistencia con la app o solo API Conectar WhatsApp
instagram Una cuenta profesional de Instagram, sin necesidad de Página de Facebook Conectar Instagram
messenger Una Página de Facebook Conectar Messenger

La conexión tiene un id (conn_…) que se usa en las llamadas de envío y aparece en todo evento. Quien no tiene cuenta en Messajo puede vincular su propia cuenta con una invitación de conexión; a partir de ahí, la administra la organización.

La clave autentica la API /v1 con el encabezado Authorization: Bearer. Es de la organización, no de quien la creó, y tiene:

Permiso Habilita
send Enviar mensajes
read Leer conexiones, conversaciones y logs
templates Crear y editar plantillas
admin Todo, incluidos los permisos anteriores

Hay dos tipos: la clave de organización (mj_), válida para cualquier conexión y que exige connection_id en las rutas de mensajes, y la clave de conexión (mjc_), creada en la pestaña Claves de API de la conexión, que solo ve su propia conexión y no necesita connection_id. Usar una conexión fuera de su alcance devuelve connection_not_allowed. Toda clave tiene su propia validez y límite por minuto. Consulta Tipos de clave.

La jerarquía es organización → conexión → WABA. Las plantillas, flows y catálogos pertenecen a la WABA, que pueden compartir conexiones hermanas: cambiarlos desde una conexión afecta a las demás de la misma WABA.

Todo lo que pasa en las conexiones — mensaje recibido, estado de entrega, plantilla aprobada, conexión caída — se convierte en un evento y sale por un destino:

  • Webhook (predeterminado): POST HTTPS firmado con el encabezado Messajo-Signature. Consulta Eventos y Verificar la firma.
  • RabbitMQ, SQS, Kafka y WebSocket: opcionales, con el mismo sobre y la misma firma. Consulta Tipos de destino.

Cada destino es global (recibe eventos de toda la organización) o de una conexión (solo los de ella). Filtra por tipo de evento y elige el formato:

  • normalized: el mismo formato de Messajo en los 3 canales, ideal si atiendes WhatsApp, Instagram y Messenger con un solo código;
  • meta: el contenido crudo que envió Meta, si ya tienes código que entiende su formato.

La misma clave usa las dos capas, y eliges en cada llamada:

Capa Ejemplo Para qué
Espejo de Meta, por canal POST /v1/whatsapp/{phone_number_id}/messages con el cuerpo idéntico al de Meta Cubre el 100% de las funciones de Meta desde el primer día. Quien migra de otro proveedor cambia solo la URL y la clave. Cada campo lo documenta la documentación oficial de Meta
Simple, unificada POST /v1/messages con connection_id, to, type… El día a día (texto, multimedia, plantillas, botones), igual en los 3 canales

La referencia de la API documenta la capa simple y las rutas de la plataforma.

Meta solo permite enviar mensajes libres dentro de una ventana de atención abierta por el contacto: 24 horas desde el último mensaje que envió. Fuera de la ventana:

  • en WhatsApp, solo sale una plantilla aprobada por Meta (marketing, utilidad o autenticación), que reabre la conversación cuando el contacto responde;
  • en Instagram y Messenger, el envío fuera de la ventana se rechaza, salvo las excepciones que prevé Meta.

Enviar fuera de la ventana devuelve el error de Meta, con el código original en meta_code. Consulta Errores.

La red falla, y repetir un envío a ciegas manda el mensaje dos veces. Para evitarlo, envía el encabezado Idempotency-Key con un valor único por operación (un UUID, por ejemplo):

POST /v1/messages
Idempotency-Key: 6f1c0f3e-9b1a-4c55-9a3e-2d8c1b7e4a10

La misma clave repetida en hasta 24 horas devuelve la respuesta original, sin enviar de nuevo. Genera la clave antes del primer intento y reutilízala en todos los reintentos.

Quién Cobra A quién
Messajo Una suscripción mensual por conexión A tu organización
Meta Las conversaciones y mensajes, según su tarifa oficial Directamente a tu cuenta de Meta, con el método de pago registrado allí

Messajo no revende mensajes ni cobra margen sobre lo que cobra Meta.