Collegare un numero
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
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.
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.
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.
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.
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_8f3a91e4Il riferimento viene salvato sulla Company creata alla fine del flusso, e lo rileggi così:
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.
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:
{
"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:
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.
Il tuo cliente supera le verifiche di Meta
Accede con Facebook e sceglie il numero. Non gli viene chiesto nient'altro.
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.
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.
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.