# Conectar WhatsApp

> Cómo vincular un número de WhatsApp en coexistencia o solo por API, con el registro oficial de Meta.

## Elige el modo

Messajo conecta números con el registro oficial de Meta (Embedded Signup), en dos modos. Eliges uno al conectar y cambia lo que el número puede hacer:

| | Coexistencia ("Mantener mi WhatsApp Business") | Solo API ("Número nuevo, solo por la API") |
|---|---|---|
| App WhatsApp Business en el celular | Sigue funcionando, y los mensajes enviados desde el celular llegan a la API (`message.echo`) | El número queda dedicado a la integración |
| Velocidad de envío | Fija en 20 msg/s | 80 msg/s, o 1.000 msg/s cuando Meta libera el rendimiento alto |
| Historial de 6 meses y contactos | Se sincronizan una vez, dentro de 24 h | No hay |
| Perfil, nombre visible y username | Se editan en la app del celular | Se editan en el panel o por la API |
| Registro del número | El número no se registra de nuevo | Se registra con un PIN aleatorio de 6 dígitos, guardado cifrado |
| Socios a la vez | Solo uno | Varios |

Usa la coexistencia cuando la atención sigue en el celular. Usa solo API para volumen o para un número nuevo.

## Requisitos

- Un portafolio comercial en Meta y acceso de administrador a él.
- Un número de teléfono para conectar.
- En coexistencia: el número ya activo en la app WhatsApp Business **2.24.17 o más reciente**.
- En solo API: un número que pueda recibir el código de verificación por SMS o llamada y que no esté en uso en la app.
- En el panel, el rol de dueño o admin, con el 2FA activado.

## Paso a paso en el panel

1. Abre **Conexiones** y haz clic en **Conectar WhatsApp**.
2. Elige el modo: **Mantener mi WhatsApp Business** (coexistencia) o **Número nuevo, solo por la API**. En coexistencia, el panel muestra la lista de [límites](#límites-de-la-coexistencia) antes de seguir. Haz clic en **Continuar**.
3. Haz clic en **Abrir la ventana de Meta**. La ventana se abre aparte: no cierres la página del panel. Si el navegador la bloquea, permite ventanas emergentes en la dirección del panel y vuelve a intentarlo.
4. En la ventana, inicia sesión en Facebook, elige (o crea) el portafolio y la cuenta de mensajes, y elige el número.
5. En coexistencia, confirma en la app del celular leyendo el código QR que muestra Meta. En solo API, confirma el número con el código por SMS o llamada.
6. Al cerrarse la ventana, el panel muestra **Completando la conexión…** y luego **WhatsApp conectado.** La conexión aparece como **Activa** y sale el evento `connection.created`.

Al completar, el servidor cambia el código de la ventana por el token de la cuenta (guardado cifrado), confirma que la cuenta elegida es la que la ventana autorizó, suscribe la app a los webhooks de la cuenta, registra el número (solo API) y lee el estado del número. Las cuentas baneadas o señaladas por Meta se rechazan antes de cualquier cambio en Meta, con el error [`account_flagged`](/es/errors#account_flagged).

### Cuando falta un paso

Si falla un paso posterior a la suscripción, la conexión queda **Pendiente** y el panel muestra el motivo, por ejemplo "Falló el registro del número en Meta.". En la página de la conexión:

- **Reintentar registro** rehace solo el registro del número (solo API). Meta acepta hasta 10 registros por número en 72 h.
- **Completar conexión** rehace lo que faltó, sin abrir la ventana otra vez.

Cada paso, de la ventana y del servidor, queda grabado en la pestaña **Historial** de la conexión. Una cancelación en la ventana aparece ahí con la etapa en que la persona se detuvo.

## Invitar al cliente por enlace

Las agencias pueden conectar el número de un cliente sin que cree una cuenta en Messajo. En **Enlaces de conexión**, haz clic en **Crear enlace** y completa el formulario (el botón **Crear enlace de conexión**, en **Conexiones**, lleva ahí):

| Campo | Qué es |
|---|---|
| **Etiqueta** | Nombre del enlace, solo lo ve tu equipo |
| **Canal** | WhatsApp. Instagram y Messenger llegan en la `0.2.0-alpha` |
| **Modo** | Coexistencia, solo API o "lo elige quien lo abra" |
| **Vigencia** | 1 hora, 24 horas, 3, 7, 14 o 30 días. Por defecto: 7 días |
| **Reutilizable** | Desactivado, el enlace vale para un solo número; activado, para varios |
| **Contraseña (opcional)** | De 8 a 128 caracteres, se pide antes de abrir el registro |
| **Idioma de la página** | Idioma de la página y del correo: portugués, inglés o español |
| **Reconectar una conexión (opcional)** | Convierte el enlace en una reconexión: hereda el modo de la conexión y vale una sola vez |
| **Enviar por correo a (opcional)** | Envía el enlace por correo al crearlo |

La URL del enlace (`https://<panel>/c/<token>`) aparece **una sola vez**, al crearlo: Messajo guarda solo el hash del token. Cópiala y envíala por donde quieras, o mándala con el correo de la plataforma. **Enviar por correo** genera un token nuevo, y la URL anterior deja de valer. La contraseña nunca va en el correo: compártela con el cliente por otro medio.

La página de la invitación no pide inicio de sesión. Muestra el nombre y el logo de tu organización, deja cambiar el idioma, explica los modos y los límites de la coexistencia y abre la misma ventana de Meta. Al terminar, muestra "Conexión hecha. Puedes cerrar esta página." La conexión queda en tu organización: el cliente no obtiene acceso a nada.

- Cinco contraseñas incorrectas seguidas bloquean el enlace por 15 minutos ([`link_locked`](/es/errors#link_locked)).
- Un enlace de un solo uso ya usado responde [`link_used`](/es/errors#link_used); uno vencido, [`link_expired`](/es/errors#link_expired). Para dar de baja un enlace antes del plazo, usa **Revocar**.
- El logo viene de **Configuración → Organización**.

Los enlaces también se pueden crear por la API, en `POST /v1/connection-links` (permiso `admin`). Consulta la [referencia de la API](/es/reference).

## Límites de la coexistencia

Meta impone estas reglas a todo número en coexistencia:

- velocidad fija de 20 msg/s;
- los grupos no se sincronizan;
- las listas de difusión quedan de solo lectura;
- los mensajes temporales y de una sola vista se desactivan;
- hay que abrir la app cada ~14 días;
- requiere WhatsApp Business 2.24.17 o más reciente;
- solo un socio a la vez.

## Sincronización de la coexistencia

Justo después de conectar en coexistencia, Messajo le pide a Meta los contactos de la app y, después, hasta 6 meses de chats. La pestaña **Sincronización** de la conexión muestra cada uno:

| Estado | Qué quiere decir |
|---|---|
| **En cola** | Aún no se pidió, o se va a pedir de nuevo después de un fallo |
| **Pedida a Meta** | Meta aceptó el pedido y está enviando los datos |
| **Completada** | Llegó todo. El historial muestra el progreso en % por fase |
| **Rechazada** | La persona rechazó compartir el historial en el celular |
| **Venció el plazo de 24 h** | Meta solo acepta el pedido hasta 24 h después de la conexión |

Cada sincronización ocurre una sola vez. Si el pedido falla, Messajo vuelve a intentarlo a los 1 min, 5 min, 15 min, 1 h, 3 h y 6 h, siempre dentro de las 24 h. Un fallo aquí nunca tumba la conexión. Los contactos llegan como evento `contacts.sync` y los chats como `history.batch`, y los mensajes importados aparecen en los registros con el origen `history`.

## Cambiar de socio en coexistencia

En coexistencia el número acepta un socio a la vez. Para traer un número que ya está con otro proveedor:

1. Haz una copia de seguridad de los chats en la app.
2. En la app, ve a **Ajustes > Cuenta > Plataforma de negocios > Desconectar**.
3. Conecta de nuevo con Messajo, como en el paso a paso de arriba.

El socio anterior recibe el aviso `PARTNER_REMOVED` de Meta. Si aparece un error de línea de crédito del socio anterior, sigue la [guía de Meta para la coexistencia](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users).

## Después de conectar

La pestaña **Resumen** de la conexión muestra el **Estado** del número:

- **Calidad**: Alta, Media, Baja o Sin calificación, como la mide Meta;
- **Nivel de envío**: cuántos contactos nuevos por 24 h puede alcanzar el portafolio (consulta [Límites](/es/api/limits#límite-de-mensajes-de-meta));
- **Velocidad**: 20, 80 o 1.000 msg/s, el rendimiento usado al enviar;
- **Envío**: Disponible, Limitado o Bloqueado;
- la restricción, cuando Meta restringe la cuenta, con el plazo.

Messajo lee el estado cada 15 minutos. **Actualizar estado** lo lee en el momento. La pestaña **Perfil** edita el perfil del negocio, pide el cambio del nombre visible y define el username (solo API).

Cada cambio de estado genera un evento `connection.*` en tus [destinos de eventos](/es/webhooks/events/), con el motivo en `reason`, y un correo para dueños y admins, en el idioma de cada uno.

## Cuando la conexión se cae

| Estado | Cuándo | Qué hacer |
|---|---|---|
| **Necesita reconectar** | Meta invalidó el token (error `190`), en una lectura de estado o en un envío | Reconectar |
| **Restringida** | Meta restringió la cuenta por un plazo, o bloqueó el envío por política | Esperar el plazo y corregir la causa en el Administrador de WhatsApp. El envío sigue donde Meta lo permita |
| **Desactivada** | Violación de política o baneo | Apelar en Meta. Si Meta la reactiva, la conexión vuelve a **Activa** sola |
| **Desconectada** | Se quitó la app de la cuenta, se eliminó la cuenta o el número, o alguien la desconectó en el panel | Conectar de nuevo |

En el error `190`, el correo para dueños y admins trae un **enlace de reconexión**. En la página de la conexión, **Reconectar** abre la ventana otra vez, y **Crear enlace de reconexión** crea un enlace para enviar a quien administra el número. La reconexión tiene que ser del **mismo número** ([`reconnect_mismatch`](/es/errors#reconnect_mismatch)) y mantiene el `id` de la conexión, el historial y los destinos.

Reconectar una conexión **Desconectada** cuenta como conexión nueva en la facturación; reconectar una que **Necesita reconectar** no. Una cuenta de WhatsApp Business (WABA) pertenece a una sola organización: conectarla en otra devuelve [`waba_owned_by_other_org`](/es/errors#waba_owned_by_other_org). Una conexión **Desconectada** nunca vuelve a **Activa** sola: solo reconectando en el panel.

**Desconectar** deja de recibir y enviar por el número. En solo API, también puedes dar de baja el registro del número en Meta. En coexistencia, el panel muestra cómo quitar el acceso en la app del celular.
