Skip to main content

​
Collega WhatsApp

Questa guida ti accompagna attraverso il processo completo di collegamento di un numero WhatsApp Business a Switchbord. Copre cosa configurare in Meta Business Suite, cosa inserire nelle impostazioni di Switchbord e come diagnosticare gli errori più comuni.
Questo processo coinvolge sia Meta (developers.facebook.com / business.facebook.com) che la UI delle impostazioni di Switchbord. Tienile entrambe aperte in tab separate. La configurazione completa richiede 15–30 minuti la prima volta.

​
Configurazione Completa — Passo per Passo

Segui questi passaggi in ordine. Saltarli o riordinarli (specialmente i passaggi 5–7) è la fonte più comune di errori.
1

Crea un'App Meta

Vai su developers.facebook.com → My Apps → Create App.
  • Tipo di app: Business
  • Aggiungi il tuo Business Portfolio quando richiesto
  • Dopo la creazione, clicca Add Product → trova WhatsApp → clicca Set Up
Se hai già un’app Meta con WhatsApp aggiunto, puoi saltare questo passaggio. Assicurati solo che sia in modalità Live (non Development) prima di passare in produzione.
2

Crea o collega un Account WhatsApp Business (WABA)

Durante la configurazione del prodotto WhatsApp nella tua app, Meta ti chiederà di selezionare o creare un Account WhatsApp Business. Puoi:
  • Creare un nuovo WABA — segui le indicazioni per impostare un nuovo account, oppure
  • Collegare un WABA esistente — selezionalo dal menu a discesa se ne hai già uno
Una volta collegato, il WABA apparirà in Meta Business Settings sotto Accounts → WhatsApp Accounts.
3

Ottieni il tuo WABA ID

In Meta Business Settings:Accounts → WhatsApp Accounts → [il tuo WABA] → tab SettingsCopia l’Account ID — è una stringa numerica di 15 cifre. Questo è il tuo WABA ID.
Non inserire il nome del WABA (ad es. “My Business”). Ti serve l’Account ID numerico. Ha l’aspetto di 123456789012345.
4

Ottieni il tuo Phone Number ID

In Meta Business Settings:Accounts → WhatsApp Accounts → [il tuo WABA] → tab Phone NumbersClicca sul tuo numero di telefono e copia il Phone Number ID — una stringa numerica di 15 cifre.
Questo NON è il numero di telefono visualizzato come +1 555 123 4567. È l’ID interno Meta per quel numero, una lunga stringa numerica. Usare il numero visualizzato causerà errori meta_graph_100.
5

Crea un System User

In Meta Business Settings:Users → System Users → Add
  • Ruolo: Admin
  • Nome: qualcosa di riconoscibile, ad es. switchbord
Clicca Create System User.
I token System User sono permanenti (non scadono) e non sono legati all’account di nessuna persona specifica. Questo è il motivo per cui sono fortemente preferiti rispetto ai token utente personali o ai token pagina per le integrazioni di produzione. Se la persona che ha creato un token utente lascia l’organizzazione, il token smette di funzionare. I token System User non hanno questo problema.
6

Assegna il System User al tuo WABA

Questo è il passaggio più comunemente saltato. Saltarlo causa meta_graph_190 (OAuthException) anche quando il tuo token è valido, ha gli scope corretti e non è mai scaduto. Il token è a posto — il System User semplicemente non è ancora autorizzato per il WABA.
In Meta Business Settings:Accounts → WhatsApp Accounts → [il tuo WABA] → tab Settings → Assigned system users
  1. Clicca Add people
  2. Seleziona il tuo System User (ad es. switchbord)
  3. Imposta il livello di permesso su Full control
  4. Clicca Save
Dovresti ora vedere il tuo System User elencato tra gli utenti assegnati per il WABA.
7

Genera un token di accesso System User

In Meta Business Settings:Users → System Users → [il tuo system user] → Generate new token
  • Seleziona la tua App Meta (quella creata nel Passaggio 1)
  • Concedi questi scope:
    • whatsapp_business_messaging
    • whatsapp_business_management
  • Imposta la scadenza del token su Never
  • Clicca Generate Token e copia immediatamente il token completo
Potrai vedere questo token solo una volta. Copialo in un password manager sicuro prima di chiudere la finestra di dialogo. Se lo perdi, dovrai generarne uno nuovo.
Genera il token dopo aver assegnato il System User al WABA (Passaggio 6). Alcuni utenti generano prima il token e poi assegnano — il token stesso non ottiene automaticamente il nuovo accesso al WABA in tutti i casi. In caso di dubbio, genera un token nuovo dopo l’assegnazione.
8

Ottieni il tuo App Secret

Vai su developers.facebook.com → My Apps → la tua app → Settings → Basic → App Secret → Show.Copia l’App Secret. Ti servirà per la validazione della firma dei webhook in Switchbord.
9

Configura Switchbord — Impostazioni del canale

In Switchbord, apri Settings → Channel:
  • Phone Number ID: incolla l’ID numerico di 15 cifre dal Passaggio 4
  • WABA ID: incolla l’ID numerico di 15 cifre dal Passaggio 3
Salva le impostazioni del canale.
10

Configura Switchbord — Credenziali del provider

In Switchbord, apri Settings → Provider:
  • Meta access token: incolla il token System User dal Passaggio 7
  • Meta App Secret: incolla l’App Secret dal Passaggio 8
  • Verify Token: clicca Generate per creare un token di verifica casuale (oppure inseriscine uno tuo)
Salva le impostazioni del provider. Copia il Verify Token generato — ti servirà nel passaggio successivo.
11

Configura il webhook Meta

Vai su developers.facebook.com → My Apps → la tua app → WhatsApp → Configuration → Webhook.
  • Callback URL: https://api.switchbord.ai/webhooks/meta
  • Verify Token: incolla il valore esatto dalle impostazioni Switchbord → Provider
Clicca Verify and Save. Meta effettuerà una richiesta di challenge all’URL del webhook per confermare che risponde correttamente.
Se la verifica del webhook fallisce, le cause più probabili sono:
  1. Il WABA non è ancora collegato (torna indietro e completa i Passaggi 3–6)
  2. Il Verify Token non corrisponde esattamente (controlla spazi iniziali/finali)
  3. L’URL di callback ha un errore di digitazione
12

Sottoscrivi i campi del webhook

Dopo aver verificato il webhook, clicca Manage vicino alle sottoscrizioni webhook e abilita almeno:
  • messages
  • message_deliveries
  • messaging_optins
Clicca Done.
13

Valida la configurazione in Switchbord

In Switchbord, apri Settings ed esegui Validate configuration.Tutti gli indicatori dovrebbero diventare verdi. Se qualcuno è rosso, vedi la sezione Risoluzione dei Problemi qui sotto.
Invia un messaggio di prova al tuo numero WhatsApp da un telefono personale per confermare la consegna end-to-end prima di passare al traffico di produzione.

​
Risoluzione dei Problemi — Codici di Errore

​
Errori Comuni

Anche gli operatori esperti ci cadono. Non sentirti male — la UI di Meta Business Suite rende tutti questi errori facili da commettere per sbaglio.
  • Inserire il numero di telefono visualizzato (+1 555 123 4567) invece del Phone Number ID (numerico di 15 cifre). Sembrano completamente diversi; l’ID non contiene la formattazione del prefisso internazionale.
  • Inserire il nome del WABA invece del WABA Account ID. Il nome è un’etichetta leggibile dall’uomo; l’ID è la stringa numerica.
  • Generare il token System User prima di assegnarlo al WABA. Assegna sempre prima, poi genera. Se lo hai fatto nell’ordine sbagliato, genera un token nuovo dopo l’assegnazione.
  • Usare un token Utente o un token Pagina invece di un token System User permanente. I token Utente scadono o si rompono quando l’account dell’utente cambia. I token System User sono persistenti.
  • Lasciare l’app Meta in modalità Development. In modalità Development, solo i numeri di test possono inviare/ricevere messaggi. Passa l’app alla modalità Live per l’uso in produzione.
  • Mismatch del verify token da copia-incolla. Uno spazio finale o un carattere di nuova riga nel verify token causerà il fallimento silenzioso della verifica del webhook. Usa il pulsante di copia in Switchbord invece di selezionare il testo manualmente.

​
Cosa Switchbord Non Ti Mostrerà

Per sicurezza, Switchbord non ripete i valori dei segreti memorizzati al browser. Vedrai solo:
  • Stato configurato o mancante
  • Se il valore proviene da Vault o dal fallback d’ambiente
  • Indizi mascherati dove disponibili
  • Ultimo stato di validazione e codice di errore

​
Manutenzione Continua

Dopo il go-live:
  • Ruota i token dalle Impostazioni invece di ridistribuire l’app
  • Ri-esegui la validazione dopo la rotazione
  • Mantieni i valori d’ambiente solo come fallback di bootstrap o di emergenza
  • I token System User impostati su Never expire non necessitano di rotazione programmata, ma ruotali se sospetti una compromissione

​
Leggi Anche