Genuka WA docs

Collegare un numero

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

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_8f3a91e4

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

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.

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:

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:

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.

In questa pagina