Empezar
Conceptos
Las piezas de Messajo: organización, conexiones, claves, destinos de eventos y las dos capas de la API.
Organización, miembros y roles
Sección titulada «Organización, miembros y roles»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.
Panel: la organización en la URL
Sección titulada «Panel: la organización en la URL»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 conorg_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.
Conexión y canal
Sección titulada «Conexión y canal»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.
Clave de API
Sección titulada «Clave de API»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.
Destinos de eventos
Sección titulada «Destinos de eventos»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):
POSTHTTPS firmado con el encabezadoMessajo-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.
Dos capas de la API
Sección titulada «Dos capas de la API»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.
Ventanas de conversación
Sección titulada «Ventanas de conversación»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.
Idempotencia
Sección titulada «Idempotencia»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/messagesIdempotency-Key: 6f1c0f3e-9b1a-4c55-9a3e-2d8c1b7e4a10La 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 qué
Sección titulada «Quién cobra qué»| 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.