# Conectar un número

URL: https://wa.genuka.com/es/docs/onboarding
Language: Spanish

> 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

1. ### 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.

2. ### 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.

3. ### 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.

> [!NOTE]
> **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.

> [!NOTE]
> **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í:

```bash title="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.

> [!NOTE]
> **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:

```json title="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:

1. ### 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.

2. ### Tu cliente pasa las verificaciones de Meta

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

3. ### 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.

4. ### 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.

5. ### 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.
