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_8f3a91e4La referencia se guarda en la Company creada al final del flujo, y la recuperas así:
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:
{
"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.