Genuka WA docs

Conectar un número

Los números se conectan mediante el Embedded Signup de Meta; ninguna credencial pasa nunca por nosotros, ni por ti.

El enlace de conexión

Cada cuenta tiene un enlace público único en /connect/{your-slug}. Ábrelo tú mismo para conectar tu propio número, o compártelo (por correo, por chat o con un botón en tu propio sitio) con una empresa cuyos números gestionas. Muestra el nombre de tu marca y un botón Conectar WhatsApp.

Qué ocurre durante el registro

Se abre el Embedded Signup de Meta

La persona que conecta se autentica con Facebook y selecciona (o crea) la WhatsApp Business Account y el número de teléfono que se usarán.

Se intercambia la autorización

Al finalizar, la plataforma intercambia un código de un solo uso por un token de acceso de larga duración, que se almacena cifrado. El token nunca sale del servidor.

El número aparece en tu panel

Se crean en tu cuenta una Company (con el nombre de la empresa que devuelve Meta) y su Connection (la WABA más el número de teléfono). La WABA se suscribe a los webhooks para que lleguen los estados, y el número se registra en la Cloud API para que pueda enviar de inmediato.

Números que ya están en la app WhatsApp Business

Un número en coexistencia permanece en la app WhatsApp Business y lo registra la propia Meta, así que no tocamos su registro: se conecta y envía exactamente de la misma manera. Si alguna vez falla un registro (por ejemplo, por un PIN de verificación en dos pasos existente), la conexión se guarda de todos modos y el número queda utilizable en cuanto se registra del lado de Meta.

Lo que puedes ver después

Para cada empresa conectada: la WABA, su(s) número(s) de teléfono con su calificación de calidad y su estado, cada plantilla con su estado de aprobación y las estadísticas de entrega de mensajes (enviados / entregados / leídos / fallidos, con sus motivos).

Saber QUÉ cliente conectó QUÉ número

Si compartes tu enlace con varios clientes, incluye en él tu propio identificador de ese cliente:

https://wa.genuka.com/connect/{your-slug}?ref=cli_8f3a91e4

La referencia se guarda en la Company creada al final del flujo, y la recuperas así:

GET /api/v1/connections?externalRef=cli_8f3a91e4
curl "https://wa.genuka.com/api/v1/connections?externalRef=cli_8f3a91e4" \
  -H "Authorization: Bearer pk_live_xxx"

{ "data": [ { "id": "con_1", "companyId": "cmp_123", "companyName": "Acme Coffee",
              "displayPhoneNumber": "+237 6 90 …", "externalRef": "cli_8f3a91e4",
              "qualityRating": "GREEN", "status": "connected" } ] }

Una sola fila: la de ese cliente. Te evita las dos respuestas equivocadas a esta pregunta: tomar la conexión más reciente, lo que tarde o temprano le asigna el número de un cliente a otro el día en que dos de ellos se conectan en el mismo minuto; o mostrar la lista y pedirle a tu cliente que señale el suyo, lo que revela de paso el número y el nombre comercial de todos los demás clientes.

Elige una referencia imposible de adivinar

Viaja en una URL. Un identificador secuencial (client-42) se puede adivinar, y quien lo adivine puede asociar su propio número a ese cliente. Usa un UUID o una aleatoriedad equivalente.

Caracteres aceptados: letras, dígitos, . _ : -, 128 como máximo. Una referencia ausente o mal formada nunca se amplía discretamente a la lista completa: la búsqueda simplemente devuelve cero filas. Enviar la misma referencia en una reconexión la traslada al número que se acaba de conectar: es tu registro, no el nuestro.

Enterarte de una conexión en el momento

En lugar de consultar GET /api/v1/connections?externalRef= una y otra vez, suscribe un webhook al evento connection.connected (a través de la API, o marcando "Number connected through your link" en el panel). Se dispara al final de cada conexión exitosa, reconexiones incluidas, salvo para un cliente suspendido, y su data es la fila que devolvería la búsqueda, con la referencia guardada para ese cliente:

POST https://your-app.com/webhooks/genuka
{
  "id": "cmh2…",
  "type": "connection.connected",
  "field": "connection.connected",
  "company_id": "cmp_123",
  "connection_id": "con_1",
  "waba_id": "102290129340398",
  "phone_number_id": "106540352242922",
  "data": {
    "id": "con_1", "companyId": "cmp_123", "companyName": "Acme Coffee",
    "externalRef": "cli_8f3a91e4",
    "wabaId": "102290129340398", "wabaName": "Acme Coffee",
    "phoneNumberId": "106540352242922", "displayPhoneNumber": "+237 6 90 …",
    "verifiedName": "Acme Coffee", "qualityRating": "GREEN", "status": "connected",
    "isNewNumber": true, "setupIssue": null,
    "connectedAt": "2026-10-31T10:00:00.000Z"
  }
}

externalRef es null cuando ese cliente no tiene ninguna. Una reconexión sin ?ref= conserva la que tenía. isNewNumber es falso cuando un número que tu cuenta ya conoce vuelve a pasar por el flujo, incluido un número liberado que regresa. setupIssue es "registration_unconfirmed" cuando no se confirmó el registro del número en la Cloud API: la conexión existe, pero el envío espera a que Meta termine.

El evento solo llega a los endpoints que lo piden, o que reciben todos los eventos (events vacío). Un endpoint creado antes de que existiera, con una lista de eventos explícita, no lo recibe: agrégalo.

Caso de uso: conectar los números de tus clientes sin intervención

Publicas un software (facturación, reservas, e-commerce…) y tus clientes quieren que tus mensajes salgan desde su número de WhatsApp. Con un plan que incluye la gestión de números de clientes (Scale o superior), todo ocurre desde tu aplicación:

Un botón "Conectar mi WhatsApp" en tu app

Abre https://wa.genuka.com/connect/{your-slug}?ref={reference}, donde la referencia es el identificador imposible de adivinar que le asignaste a ese cliente y que guardas de tu lado.

Tu cliente pasa las verificaciones de Meta

Inicia sesión con Facebook y elige el número. No se le pide nada más.

Recibes connection.connected

Encuentra a tu cliente por data.externalRef y guarda connection_id: es lo que pasarás para enviar y para crear plantillas. Ignora cualquier evento cuya referencia no corresponda a ninguno de tus clientes. El enlace es público, así que cualquiera puede seguirlo.

Creas sus plantillas

Un POST /api/v1/templates por plantilla y por idioma, con ese connectionId. Tus plantillas deben existir en su cuenta de WhatsApp Business: las de tu propio número no se trasladan. Nunca necesitas su token de Meta: basta con tu clave API, y la plataforma usa el token que guarda para ese número.

Sigues la aprobación y luego haces el cambio

template.status_changed te trae el veredicto de Meta, y GET /api/v1/templates?companyId={company_id}&sync=true sirve de red de seguridad. La revisión suele tardar unas horas, hasta 48 h. Sigue enviando desde tu propio número hasta que todas las plantillas del cliente estén aprobadas.

Varios números, límites y reconexión

Puedes conectar tantos números como cubra tu suscripción, repartidos entre tantas empresas como quieras. Conectar un número nuevo ocupa un espacio libre; superar la cantidad de números que pagaste se rechaza con 402 plan_limit_numbers, y ampliarla requiere un nuevo pago desde la página de Facturación. Volver a ejecutar el flujo de conexión para un número ya conectado actualiza su token y sus datos en lugar de crear un duplicado, y nunca consume un espacio.

En esta página