# Collegare un numero

URL: https://wa.genuka.com/it/docs/onboarding
Language: Italian

> I numeri si collegano tramite l'Embedded Signup di Meta; nessuna credenziale passa mai da noi, né da te.

## Il link di connessione

Ogni account ha un link pubblico unico su `/connect/{your-slug}`. Aprilo tu stesso per collegare il
tuo numero, oppure condividilo (via email, chat o con un pulsante sul tuo sito) con un'azienda di
cui gestisci i numeri. Mostra il nome del tuo brand e un pulsante **Collega WhatsApp**.

## Cosa succede durante la registrazione

1. ### Si apre l'Embedded Signup di Meta

   La persona che si collega si autentica con Facebook e seleziona (o crea) il WhatsApp Business
   Account e il numero di telefono da usare.

2. ### Viene scambiata l'autorizzazione

   Al termine, la piattaforma scambia un codice monouso con un token di accesso a lunga durata, che
   viene conservato **cifrato**. Il token non lascia mai il server.

3. ### Il numero compare nella tua dashboard

   Nel tuo account vengono create una `Company` (con il nome dell'azienda restituito da Meta) e la sua
   `Connection` (la WABA più il numero di telefono). La WABA viene iscritta ai webhook in modo che gli
   stati arrivino, e il numero viene registrato sulla Cloud API per poter inviare subito.

> [!NOTE]
> **Numeri già presenti sull'app WhatsApp Business**
>
> Un numero in coesistenza resta sull'app WhatsApp Business e viene registrato da Meta stessa,
> quindi non tocchiamo la sua registrazione: si collega e invia esattamente allo stesso modo. Se una
> registrazione dovesse fallire (per esempio per un PIN di verifica in due passaggi già esistente),
> la connessione viene comunque salvata e il numero diventa utilizzabile non appena è registrato
> lato Meta.

> [!NOTE]
> **Cosa puoi vedere dopo**
>
> Per ogni azienda collegata: la WABA, il suo o i suoi numeri di telefono con punteggio di qualità e
> stato, ogni modello con il suo stato di approvazione e le statistiche di consegna dei messaggi
> (inviati / consegnati / letti / falliti, con i motivi).

## Sapere QUALE cliente ha collegato QUALE numero

Se condividi il tuo link con più clienti, inserisci al suo interno il tuo identificativo per quel
cliente:

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

Il riferimento viene salvato sulla `Company` creata alla fine del flusso, e lo rileggi così:

```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 riga: quella di quel cliente. Ti evita entrambe le risposte sbagliate a questa domanda:
prendere la connessione più recente, che prima o poi assegna il numero di un cliente a un altro il
giorno in cui due di loro si collegano nello stesso minuto; oppure mostrare la lista e chiedere al
tuo cliente di indicare il proprio, il che rivela di passaggio il numero e la ragione sociale di
tutti gli altri clienti.

> [!NOTE]
> **Scegli un riferimento impossibile da indovinare**
>
> Viaggia in un URL. Un identificativo sequenziale (`client-42`) si può indovinare, e chi lo indovina
> può associare il proprio numero a quel cliente. Usa un UUID o una casualità equivalente.

Caratteri accettati: lettere, cifre, `.` `_` `:` `-`, 128 al massimo. Un riferimento assente o
malformato non viene mai esteso silenziosamente all'intera lista: la ricerca restituisce
semplicemente zero righe. Inviare di nuovo lo stesso riferimento in una riconnessione lo sposta sul
numero appena collegato: è il tuo registro, non il nostro.

## Sapere di una connessione nel momento in cui avviene

Invece di interrogare continuamente `GET /api/v1/connections?externalRef=`, iscrivi un webhook
all'evento `connection.connected` (tramite l'API, o spuntando "Number connected through your link"
nella dashboard). Si attiva alla fine di ogni connessione riuscita, riconnessioni comprese, tranne
che per un cliente sospeso, e il suo `data` è la riga che restituirebbe la ricerca, con il
riferimento salvato per quel 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` è `null` quando quel cliente non ne ha uno. Una riconnessione senza `?ref=` mantiene
quello che aveva. `isNewNumber` è falso quando un numero che il tuo account conosce già ripassa nel
flusso, compreso un numero rilasciato che ritorna. `setupIssue` vale `"registration_unconfirmed"`
quando la registrazione del numero sulla Cloud API non è stata confermata: la connessione esiste, ma
l'invio attende che Meta finisca.

L'evento arriva solo agli endpoint che lo richiedono, o che ricevono tutti gli eventi (`events`
vuoto). Un endpoint creato prima che esistesse, con una lista di eventi esplicita, non lo riceve:
aggiungilo.

## Caso d'uso: collegare i numeri dei tuoi clienti senza intervento manuale

Pubblichi un software (fatturazione, prenotazioni, e-commerce…) e i tuoi clienti vogliono che i tuoi
messaggi partano dal **loro** numero WhatsApp. Con un piano che include la gestione dei numeri dei
clienti (Scale o superiore), tutto avviene dalla tua applicazione:

1. ### Un pulsante "Collega il mio WhatsApp" nella tua app

   Apre `https://wa.genuka.com/connect/{your-slug}?ref={reference}`, dove il riferimento è
   l'identificativo **impossibile da indovinare** che hai assegnato a quel cliente e che conservi dal
   tuo lato.

2. ### Il tuo cliente supera le verifiche di Meta

   Accede con Facebook e sceglie il numero. Non gli viene chiesto nient'altro.

3. ### Ricevi `connection.connected`

   Trova il tuo cliente tramite `data.externalRef` e conserva `connection_id`: è ciò che passerai per
   inviare e per creare modelli. Ignora qualsiasi evento il cui riferimento non corrisponda a nessuno
   dei tuoi clienti. Il link è pubblico, quindi chiunque può seguirlo.

4. ### Crei i suoi modelli

   Un `POST /api/v1/templates` per modello e per lingua, con quel `connectionId`. I tuoi modelli devono
   esistere sul **suo** account WhatsApp Business: quelli del tuo numero non lo seguono. Non ti serve
   mai il suo token Meta: basta la tua chiave API, e la piattaforma usa il token che conserva per quel
   numero.

5. ### Segui l'approvazione, poi fai il passaggio

   `template.status_changed` ti porta il verdetto di Meta, e
   `GET /api/v1/templates?companyId={company_id}&sync=true` fa da rete di sicurezza. La revisione di
   solito richiede qualche ora, fino a 48 h. Continua a inviare dal tuo numero finché tutti i modelli
   del cliente non sono approvati.

## Più numeri, limiti e riconnessione

Puoi collegare tanti numeri quanti ne paga il tuo abbonamento, distribuiti su tutte le aziende che
vuoi. Collegare un numero nuovo occupa uno slot libero; superare il numero di numeri pagati viene
rifiutato con `402 plan_limit_numbers`, e aumentarlo richiede un nuovo pagamento dalla pagina
Fatturazione. Rieseguire il flusso di connessione per un numero già collegato ne aggiorna il token e
i dati invece di creare un duplicato, e non consuma mai uno slot.
