Conectar canales
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
Sección titulada «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
Sección titulada «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
Sección titulada «Paso a paso en el panel»- Abre Conexiones y haz clic en Conectar WhatsApp.
- 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 antes de seguir. Haz clic en Continuar.
- 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.
- En la ventana, inicia sesión en Facebook, elige (o crea) el portafolio y la cuenta de mensajes, y elige el número.
- 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.
- 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.
Cuando falta un paso
Sección titulada «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
Sección titulada «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). - Un enlace de un solo uso ya usado responde
link_used; uno vencido,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.
Límites de la coexistencia
Sección titulada «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
Sección titulada «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
Sección titulada «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:
- Haz una copia de seguridad de los chats en la app.
- En la app, ve a Ajustes > Cuenta > Plataforma de negocios > Desconectar.
- 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.
Después de conectar
Sección titulada «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);
- 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, 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
Sección titulada «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) 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. 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.