# Conceptos

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

## 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`](/es/errors#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](/es/api/authentication/).

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

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.

## 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](/es/connect/whatsapp/) |
| `instagram` | Una cuenta profesional de Instagram, sin necesidad de Página de Facebook | [Conectar Instagram](/es/connect/instagram/) |
| `messenger` | Una Página de Facebook | [Conectar Messenger](/es/connect/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

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`](/es/errors#connection_not_allowed). Toda clave tiene su propia validez y límite por minuto. Consulta [Tipos de clave](/es/api/authentication/#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

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](/es/webhooks/events/) y [Verificar la firma](/es/webhooks/verify-signature/).
- **RabbitMQ, SQS, Kafka y WebSocket**: opcionales, con el mismo sobre y la misma firma. Consulta [Tipos de destino](/es/webhooks/destinations/).

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

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](/es/reference) documenta la capa simple y las rutas de la plataforma.

## 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](/es/errors/).

## 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):

```http
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 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.
