Skip to main content

​
Configurazione delle Credenziali Meta WhatsApp

Questa guida è destinata a operatori e amministratori della piattaforma che configurano le credenziali della Meta WhatsApp Business API per un workspace Switchbord. Copre tutti i tipi di credenziale, spiega perché ciascuna è necessaria e illustra i percorsi di navigazione esatti in Meta Business Suite.
Questa guida copre il lato operatore della configurazione delle credenziali — cosa fai in Meta. Per il lato Switchbord (inserimento delle credenziali in Settings), vedi Connect WhatsApp.

​
Perché i Token System User

Switchbord richiede un token di accesso System User piuttosto che un token User personale o un token Page. Ecco perché questo è importante: Il vantaggio critico dei token System User: non sono legati all’account di nessuna singola persona. Se la persona che ha creato un token User lascia l’organizzazione, il token diventa non valido e la tua integrazione WhatsApp si interrompe — spesso silenziosamente, scoperta solo quando i messaggi smettono di essere inviati. I token System User supportano anche l’impostazione della scadenza su Never, il che elimina l’overhead operativo della rotazione periodica dei token.

​
Prerequisiti

Prima di iniziare, conferma di avere:
  • Accesso Admin a un Meta Business Portfolio su business.facebook.com
  • Un account WhatsApp Business (WABA) già creato o rivendicato
  • Un numero di telefono aziendale verificato in quella WABA
  • Una App Meta (tipo: Business) con il prodotto WhatsApp aggiunto
Se non disponi di questi elementi, completa prima la guida Connect WhatsApp — illustra l’intera configurazione da zero.

​
Configurazione Guidata delle Credenziali

1

Accedi alle Impostazioni Business di Meta

Vai su business.facebook.com/settings.Tutta la configurazione delle credenziali avviene da questo pannello centrale. Aggiungilo ai preferiti — ci tornerai spesso.
Se gestisci più Business Portfolio, conferma di essere in quello corretto controllando il nome del portfolio nel menu a discesa in alto a sinistra.
2

Individua il tuo WABA ID

Naviga su: Accounts → WhatsApp AccountsTrova la tua WABA nell’elenco e cliccaci sopra. Nella scheda Settings, copia l’Account ID.Si tratta di una stringa numerica di 15 cifre — il tuo WABA ID. Salvalo in un posto accessibile; ti servirà quando configurerai Switchbord Settings → Channel.
3

Individua il tuo Phone Number ID

Naviga su: Accounts → WhatsApp Accounts → [la tua WABA] → scheda Phone NumbersClicca sul tuo numero di telefono. Copia il Phone Number ID — anche questo, una stringa numerica di 15 cifre.
Il Phone Number ID non è il numero di telefono formattato come +1 555 123 4567. È un ID numerico interno che appare come 123456789012345. Usare il numero formattato causerà errori meta_graph_100 in Switchbord.
4

Crea un System User

Naviga su: Users → System Users → AddConfigura:
  • Name: Scegli qualcosa di descrittivo, es. switchbord-prod o switchbord-[nome-workspace]
  • Role: Admin
Clicca su Create System User.
Puoi creare più System User per ambienti diversi (staging, produzione) o workspace diversi. Ogni System User può avere il proprio token con il proprio set di scope.
5

Assegna il System User alla tua WABA

Non saltare questo passaggio. Questa è la causa più comune di errori meta_graph_190 (OAuthException). Il messaggio di errore dice “token invalid” ma il token va bene — il System User semplicemente non ha il permesso di operare sulla WABA.Anche un token System User valido, permanente e correttamente configurato con gli scope corretti restituirà meta_graph_190 finché il System User non viene assegnato alla WABA.
Naviga su: Accounts → WhatsApp Accounts → [la tua WABA] → scheda SettingsScorri fino a Assigned system users e clicca su Add people.
  1. Cerca e seleziona il tuo System User per nome
  2. Imposta il permesso su Full control
  3. Clicca su Save
Conferma che il System User ora appaia nell’elenco degli utenti assegnati.Perché full control? Switchbord deve inviare messaggi (write), leggere le ricevute di consegna (read), e gestire le iscrizioni ai webhook (admin). Permessi parziali causeranno fallimenti intermittenti.
6

Genera il token di accesso System User

Naviga su: Users → System Users → [il tuo System User] → Generate new tokenNella finestra di generazione del token:
  1. Select app: scegli la tua App Meta (App ID: 1485717133228319 per l’app di Switchbord)
  2. Select permissions — concedi come minimo:
    • whatsapp_business_messaging — richiesto per l’invio dei messaggi
    • whatsapp_business_management — richiesto per la gestione della WABA, le query sui numeri di telefono e le analitiche di billing della WABA
    • ads_read — richiesto per la ricerca di campagne/annunci Meta in Insights
    • read_insights — richiesto per le analitiche di pricing/billing della WABA Meta
    • paid_marketing_messages — richiesto per le analitiche sui messaggi di marketing a pagamento dove applicabile
  3. Token expiry: imposta su Never
  4. Clicca su Generate Token
Copia immediatamente la stringa completa del token e conservala in un gestore di credenziali sicuro.
Questa è l’unica volta in cui Meta ti mostra il token completo. Una volta chiusa questa finestra, non puoi recuperarlo — puoi solo generarne uno nuovo (che invalida il precedente). Copialo ora.
Genera il token dopo aver completato l’assegnazione della WABA nel passaggio precedente. La generazione del token non recepisce retroattivamente le nuove assegnazioni WABA in tutti i casi. Se hai già generato un token prima dell’assegnazione, generane subito uno nuovo.
7

Recupera l'App Secret

Vai su developers.facebook.com → My Apps → la tua app → Settings → Basic.Clicca su Show vicino al campo App Secret. Copia il segreto.Switchbord lo usa per validare la firma HMAC sui payload dei webhook in ingresso da Meta, garantendo che i messaggi non possano essere falsificati da terze parti.
L’App Secret è diverso dal token System User. Il token autentica le chiamate API in uscita; l’App Secret valida le firme dei webhook in ingresso. Entrambi sono richiesti.
8

Configura il webhook Meta

In developers.facebook.com → My Apps → la tua app → WhatsApp → Configuration → Webhook:
  • Callback URL: https://api.switchbord.ai/webhooks/meta
  • Verify Token: copia dal campo Switchbord Settings → Provider → Verify Token
Clicca su Verify and Save.Meta effettuerà immediatamente una richiesta GET al callback URL con un parametro challenge. Switchbord risponde con il challenge per confermare che l’endpoint sia attivo e che il verify token corrisponda.
La verifica del webhook fallirà se:
  • La WABA non è ancora connessa all’app Meta
  • Il verify token in Meta non corrisponde esattamente a quello salvato in Switchbord
  • C’è uno spazio finale o un a capo in uno dei due valori del token
Dopo che la verifica ha successo, clicca su Manage e iscriviti a questi campi del webhook:
  • messages — messaggi in ingresso e aggiornamenti di stato
  • message_deliveries — ricevute di consegna
  • messaging_optins — eventi di opt-in

​
Riferimento delle Credenziali

​
Pratiche di Sicurezza per i Token

  • Conserva i token in un password manager di team (1Password, Bitwarden, ecc.) non in vault personali
  • Limita gli scope dei token solo a whatsapp_business_messaging e whatsapp_business_management — non concedere permessi ampi
  • Ruota i token in caso di compromissione — genera un nuovo token System User e aggiorna immediatamente le Switchbord Settings
  • Non loggare né esporre mai i token nei log dell’applicazione, nei messaggi di errore o nel version control
  • Usa un System User per ambiente — token separati per staging e produzione semplificano la rotazione e riducono il raggio d’impatto

​
Configurare la Meta Marketing API in Switchbord

Dopo che il token esiste in Meta, inserisci la configurazione della Marketing API in Switchbord:
  1. Apri Settings → Integrations → Channels → WhatsApp.
  2. In Provider credentials, trova la card Meta Ads / Marketing API.
  3. Scegli una delle opzioni:
    • Reuse WhatsApp token se il token WhatsApp esistente del tuo workspace ha già ads_read, read_insights e whatsapp_business_management; oppure
    • Incolla un token System User separato in Meta Ads token.
  4. Inserisci l’id dell’account pubblicitario Meta nel formato act_1234567890.
  5. Clicca su Save & validate.
Per GB Viaggi, il token WhatsApp esistente del workspace ha già gli scope richiesti. Usa Reuse WhatsApp token e l’id dell’account pubblicitario act_474265269673453.
Questa configurazione sblocca:
  • Il confronto campagne/annunci di Insights → Meta ads.
  • L’ingestione di pricing_analytics e analytics della WABA in Insights → Billing.
  • L’enrichment di annunci, adset e campagne Click-to-WhatsApp quando i referral in ingresso includono un ad id.

​
Risoluzione dei Problemi

Vedi la tabella completa dei codici di errore nella guida Connect WhatsApp. Riferimento rapido per i problemi più comuni: meta_graph_190 dopo aver inserito un token valido Il System User non è assegnato alla WABA. Completa il Passaggio 5 sopra. La verifica del webhook fallisce immediatamente Oppure la WABA non è connessa all’app Meta, oppure i verify token non corrispondono esattamente. Copia il verify token usando il pulsante di copia in Switchbord per evitare problemi di spaziatura. I messaggi vengono inviati ma non arrivano ricevute di consegna Il campo webhook message_deliveries non è iscritto. Vai su WhatsApp → Configuration → Manage → abilita message_deliveries.

​
Guide Correlate