> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Collega WhatsApp

> Guida completa passo-passo per collegare un numero WhatsApp Business a Switchbord — inclusi la configurazione Meta, l'impostazione delle credenziali e la risoluzione dei problemi.

# 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.

<Note>
  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.
</Note>

***

## Configurazione Completa — Passo per Passo

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

<Steps>
  <Step title="Crea un'App Meta">
    Vai su [developers.facebook.com](https://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**

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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](https://business.facebook.com/settings)
    sotto **Accounts → WhatsApp Accounts**.
  </Step>

  <Step title="Ottieni il tuo WABA ID">
    In [Meta Business Settings](https://business.facebook.com/settings):

    **Accounts → WhatsApp Accounts → \[il tuo WABA] → tab Settings**

    Copia l'**Account ID** — è una stringa numerica di 15 cifre. Questo è il tuo **WABA ID**.

    <Warning>
      Non inserire il *nome* del WABA (ad es. "My Business"). Ti serve l'Account ID numerico.
      Ha l'aspetto di `123456789012345`.
    </Warning>
  </Step>

  <Step title="Ottieni il tuo Phone Number ID">
    In [Meta Business Settings](https://business.facebook.com/settings):

    **Accounts → WhatsApp Accounts → \[il tuo WABA] → tab Phone Numbers**

    Clicca sul tuo numero di telefono e copia il **Phone Number ID** — una stringa numerica di 15 cifre.

    <Warning>
      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`.
    </Warning>
  </Step>

  <Step title="Crea un System User">
    In [Meta Business Settings](https://business.facebook.com/settings):

    **Users → System Users → Add**

    * Ruolo: **Admin**
    * Nome: qualcosa di riconoscibile, ad es. `switchbord`

    Clicca **Create System User**.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Assegna il System User al tuo WABA">
    <Warning>
      **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.
    </Warning>

    In [Meta Business Settings](https://business.facebook.com/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.
  </Step>

  <Step title="Genera un token di accesso System User">
    In [Meta Business Settings](https://business.facebook.com/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

    <Warning>
      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.
    </Warning>

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Ottieni il tuo App Secret">
    Vai su [developers.facebook.com](https://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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configura il webhook Meta">
    Vai su [developers.facebook.com](https://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.

    <Warning>
      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
    </Warning>
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>
  </Step>
</Steps>

***

## Risoluzione dei Problemi — Codici di Errore

| Errore                                                            | Significato                                                              | Correzione                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `meta_graph_190`                                                  | OAuthException — System User non assegnato al WABA, oppure token scaduto | **Più probabile:** assegna il System User al WABA (Passaggio 6 sopra). Se già assegnato, verifica che il token non sia scaduto. Se stai usando un token Utente invece di un token System User, genera un token System User corretto.                                                         |
| `meta_graph_100`                                                  | Phone Number ID non valido                                               | Il tuo Phone Number ID in Settings → Channel è errato o è ancora un placeholder. Ottieni il vero ID numerico di 15 cifre da Meta Business Settings → tab Phone Numbers. Non usare il numero visualizzato (+1 555...).                                                                        |
| Fallimento del callback webhook `#N/A:WBxP...`                    | Meta non riesce a completare l'handshake di verifica                     | Controlla: (1) l'URL del webhook è esattamente `https://api.switchbord.ai/webhooks/meta` senza slash finale; (2) il verify token in Meta corrisponde esattamente a quello salvato in Switchbord — nessuno spazio extra; (3) il WABA deve essere collegato prima di sottoscrivere il webhook. |
| `workspace_secret_store_unavailable`                              | `SUPABASE_DB_URL` manca dall'ambiente Vercel                             | Contatta il tuo amministratore Switchbord — questo è un problema di configurazione dell'infrastruttura, non un problema di credenziali Meta.                                                                                                                                                 |
| Il token funziona nel Meta API Explorer ma fallisce in Switchbord | Mismatch del tipo di token                                               | L'API Explorer usa un token Utente temporaneo. Switchbord richiede un token System User permanente. Genera un token System User con i passaggi sopra.                                                                                                                                        |

***

## 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

* [Impostazione delle Credenziali Meta — Guida per l'Operatore](/it/operations/meta-credential-setup)
* [Onboarding dell'Operatore](/it/platform/onboarding)
* [Architettura della Piattaforma](/it/platform/architecture)
* [API Interna](/it/api-reference/introduction)