Ir al contenido

Conectar canales

Conectar WhatsApp

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

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.

  • 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.
  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 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.

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.

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.

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.

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.

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.

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.

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.