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

# Configurazione delle Credenziali Meta WhatsApp

> Guida operativa dettagliata per configurare le credenziali della Meta WhatsApp Business API — token System User, assegnazione WABA, configurazione dei webhook e best practice di sicurezza.

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

<Note>
  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](/it/platform/connect-whatsapp).
</Note>

***

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

| Tipo di Token            | Scadenza                    | Legato a                                | Consigliato per              |
| ------------------------ | --------------------------- | --------------------------------------- | ---------------------------- |
| Token User (short-lived) | 1–2 ore                     | Sessione di login della singola persona | Solo per i test              |
| Token User (long-lived)  | 60 giorni                   | Account della singola persona           | Mai in produzione            |
| Token Page               | Variabile                   | Pagina Facebook + singola persona       | Non applicabile per WhatsApp |
| Token System User        | Mai (se impostato su Never) | Business Portfolio, non una persona     | **Produzione — usa questo**  |

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](https://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](/it/platform/connect-whatsapp) —
illustra l'intera configurazione da zero.

***

## Configurazione Guidata delle Credenziali

<Steps>
  <Step title="Accedi alle Impostazioni Business di Meta">
    Vai su [business.facebook.com/settings](https://business.facebook.com/settings).

    Tutta la configurazione delle credenziali avviene da questo pannello centrale. Aggiungilo ai preferiti — ci tornerai spesso.

    <Tip>
      Se gestisci più Business Portfolio, conferma di essere in quello corretto controllando
      il nome del portfolio nel menu a discesa in alto a sinistra.
    </Tip>
  </Step>

  <Step title="Individua il tuo WABA ID">
    Naviga su: **Accounts → WhatsApp Accounts**

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

  <Step title="Individua il tuo Phone Number ID">
    Naviga su: **Accounts → WhatsApp Accounts → \[la tua WABA] → scheda Phone Numbers**

    Clicca sul tuo numero di telefono. Copia il **Phone Number ID** — anche questo, una stringa numerica di 15 cifre.

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

  <Step title="Crea un System User">
    Naviga su: **Users → System Users → Add**

    Configura:

    * **Name**: Scegli qualcosa di descrittivo, es. `switchbord-prod` o `switchbord-[nome-workspace]`
    * **Role**: Admin

    Clicca su **Create System User**.

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

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

    Naviga su: **Accounts → WhatsApp Accounts → \[la tua WABA] → scheda Settings**

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

  <Step title="Genera il token di accesso System User">
    Naviga su: **Users → System Users → \[il tuo System User] → Generate new token**

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

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

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

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

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

  <Step title="Configura il webhook Meta">
    In [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**: 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.

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

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

***

## Riferimento delle Credenziali

| Credenziale                  | Dove Trovarla                                                                   | Dove Inserirla in Switchbord                                                      |
| ---------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| WABA ID                      | Business Settings → Accounts → WhatsApp Accounts → scheda Settings → Account ID | Settings → Channel → WABA ID                                                      |
| Phone Number ID              | Business Settings → WhatsApp Accounts → \[WABA] → Phone Numbers → \[numero]     | Settings → Channel → Phone Number ID                                              |
| Token di accesso System User | Business Settings → Users → System Users → Generate new token                   | Settings → Provider → Meta access token                                           |
| App Secret                   | developers.facebook.com → App → Settings → Basic → App Secret                   | Settings → Provider → Meta App Secret                                             |
| Verify Token                 | Generato in Switchbord Settings → Provider                                      | developers.facebook.com → App → WhatsApp → Configuration → Webhook → Verify Token |

***

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

<Info>
  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`.
</Info>

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](/it/platform/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

* [Connect WhatsApp — Guida Completa alla Configurazione](/it/platform/connect-whatsapp)
* [Webhooks](/it/operations/webhooks)
* [Secrets and Encryption](/it/security/secrets-and-encryption)
* [Operator Onboarding](/it/platform/onboarding)