Skip to main content

​
Credenziali Meta

Switchbord comunica con la WhatsApp Business Platform tramite la Graph API di Meta. Prima che qualsiasi messaggio possa fluire, servono cinque elementi:
  1. Meta access token (token System User)
  2. App Secret (firma dei webhook)
  3. Verify token (handshake del webhook)
  4. Phone Number ID (da quale numero inviare)
  5. WhatsApp Business Account ID (WABA ID — l’account che possiede il numero)
Puoi incollare tutti e cinque dalla pagina Impostazioni del canale o dal wizard di benvenuto integrato su /welcome. Ogni campo ha un toggle “Dove lo trovo?” con il percorso esatto nel Meta Business Suite e un deep-link che ti porta direttamente lì.

​
1 · Meta access token

  1. Apri Meta Business Settings → Users → System Users.
  2. Seleziona il System User assegnato al tuo WABA (creane uno se non lo hai — deve avere controllo completo sul WABA).
  3. Clicca Generate new token, scegli la tua app WhatsApp e concedi:
    • whatsapp_business_management
    • whatsapp_business_messaging
  4. Copia la lunga stringa EAAG… e incollala in Impostazioni canale → Credenziali provider → Meta Access Token.
Switchbord cifra il token a riposo in Supabase Vault. Non compare mai nei log dell’applicazione.

​
2 · App Secret

  1. Apri Meta App Dashboard e scegli la tua app WhatsApp.
  2. Vai su App settings → Basic.
  3. Clicca Show accanto ad App secret, autenticati e copia il valore.
  4. Incollalo in Impostazioni canale → Webhook Signing Secret.
L’App Secret è ciò con cui Switchbord verifica che i payload dei webhook in entrata provengano davvero da Meta (HMAC-SHA256 sul corpo grezzo).

​
3 · Verify token

Questo è a tua discrezione — Switchbord può generarlo per te.
  1. Nel passo 3 del wizard di benvenuto (oppure Impostazioni canale → Meta verify token), clicca Generate.
  2. Copia il token generato swb_….
  3. In Meta App Dashboard → WhatsApp → Configuration → Webhooks, clicca Edit, incolla lo stesso token e imposta la Callback URL su quella mostrata nel wizard.
Meta chiama GET {callbackUrl}?hub.verify_token=… una sola volta — Switchbord risponde con la challenge corrispondente se i token coincidono.

​
4 · Phone Number ID

  1. Apri WhatsApp Manager — Phone Numbers.
  2. Seleziona il business che possiede il tuo WABA.
  3. Trova la riga del numero WhatsApp da cui vuoi inviare.
  4. Copia il lungo valore numerico nella colonna ID (in genere 15 cifre).
  5. Incollalo in Impostazioni canale → WhatsApp phone ID.
Dopo il salvataggio, Switchbord chiama GET https://graph.facebook.com/v25.0/{phone_number_id} per confermare che l’ID sia reale e appartenga all’ambito del tuo access token. In caso di successo vedrai una riga verde “Verified with Meta”, oppure in caso di errore una riga rossa “Meta rejected this ID” con il codice di errore esatto (in genere meta_graph_100 se l’ID è errato o meta_graph_190 se il token non ha accesso).

​
5 · WhatsApp Business Account ID (WABA ID)

  1. Apri Business Settings → Accounts → WhatsApp Accounts.
  2. Seleziona il tuo WABA.
  3. L’ID numerico è mostrato sotto il nome dell’account (e nell’URL — business.facebook.com/settings/whatsapp-business-accounts/<WABA_ID>).
  4. Incollalo in Impostazioni canale → WhatsApp Business Account ID.
Il WABA ID viene usato per inviare modelli e leggere i metadati a livello di account. Switchbord lo valida rispetto a GET https://graph.facebook.com/v25.0/{waba_id} immediatamente dopo il salvataggio.

​
Risoluzione dei problemi

​
Alternativa: Meta Embedded Signup

I cinque passi precedenti sono il percorso bring-your-own-token — sempre disponibile e l’unico percorso per i deployment self-hosted. Se il tuo deployment ha Embedded Signup abilitato (NEXT_PUBLIC_EMBEDDED_SIGNUP_ENABLED=1 più le credenziali dell’app Meta), /welcome offre anche un flusso di accesso ospitato da Meta che salta completamente i passi 1, 4 e 5 sopra indicati — Meta restituisce direttamente il WABA ID e il Phone Number ID, e Switchbord scambia lato server un codice one-time per l’access token. Supporta inoltre in modo trasparente l’onboarding di un secondo WABA nella stessa area di lavoro, senza toccare il token archiviato del primo WABA. Consulta Meta Embedded Signup e Multi-WABA per il flusso completo.

​
Riferimento

  • packages/whatsapp/validate-meta-ids.ts — valida in tempo reale il Phone Number ID e il WABA ID rispetto alla Graph API di Meta.
  • apps/app/app/api/settings/meta/validate-ids/route.ts — l’endpoint chiamato dall’interfaccia.
  • Le impostazioni del canale risiedono su channels.phone_number_id e channels.waba_id (vedi packages/database/src/adapters/messages.ts).
  • apps/app/app/api/onboarding/meta/exchange/route.ts — l’endpoint di scambio codice dell’Embedded Signup (vedi Meta Embedded Signup e Multi-WABA).