Panoramica

L'API Business Management consente di creare e gestire risorse business relative a WhatsApp, come gli account WhatsApp Business e i modelli di messaggi. Poiché l'API è creata sul modello dell'API Marketing di cui sfrutta alcuni endpoint, questa documentazione potrebbe contenere dei link alla documentazione dell'API Marketing, dove necessario.

Requisiti

• Un account business di Meta.
• Un account WhatsApp Business associato al tuo account business di Meta.
• Un'app business associata al tuo account business di Meta.
• Un token d'accesso dell'utente di sistema con integrazione business, un token d'accesso dell'utente di sistema o un token d'accesso dell'utente.
• L'autorizzazione whatsapp_business_management.
• Se la tua app accede agli endpoint che targetizzano il tuo account business di Meta, avrai bisogno anche dell'autorizzazione business_management.
• Se la tua app accede agli endpoint dell'API Cloud, ti servirà l'autorizzazione whatsapp_business_messaging.

Token d'accesso

La piattaforma supporta i seguenti tipi di token d'accesso. Il tipo che usi dipende da chi userà la tua applicazione e dal fatto che tu sia o meno un fornitore di soluzioni.

• Se sei uno sviluppatore diretto, che significa che l'accesso ai tuoi dati è riservato soltanto a te o alla tua azienda, utilizza un token d'accesso dell'utente di sistema.
• Se sei un fornitore di soluzioni tecnologiche, utilizza un token d'accesso dell'utente di sistema con integrazione business.
• Se sei un partner di soluzioni, utilizza i token d'accesso dell'utente di sistema per condividere la tua linea di credito con i clienti appena registrati e i token d'accesso dell'utente di sistema con integrazione business per tutte le altre finalità.

Token d'accesso dell'utente di sistema

I token d'accesso dell'utente di sistema rappresentano te, la tua azienda o la tua organizzazione oppure le persone all'interno della tua azienda o della tua organizzazione. Il vantaggio principale di questi token è che non scadono e possono rappresentare servizi automatizzati all'interno della tua azienda che non richiedono alcun input da parte dell'utente.

I token d'accesso dell'utente di sistema sono l'unico tipo di token che può essere usato dai partner di soluzioni per condividere linee di credito con i clienti registrati.

Prima di generare un token d'accesso dell'utente di sistema, devi creare un utente di sistema. La maggior parte degli endpoint controlla se l'utente identificato dal token ha accesso alla risorsa interrogata. Se l'utente non ha accesso alla risorsa, la richiesta sarà rifiutata con il codice di errore 200.

Gli utenti di sistema possono essere dipendenti o amministratori.

Utenti di sistema con funzioni di dipendente

Gli utenti di sistema con funzioni di dipendente devono disporre dell'accesso per ciascun account WhatsApp Business di proprietà di o condiviso con Meta. Se la tua app avrà bisogno di accedere solo ad alcuni account WhatsApp Business di tua proprietà, un utenti di sistema con funzioni di dipendente dovrebbe essere sufficiente.

Una volta creato, devi concedere l'accesso alle risorse businessparziale o completo per ogni account WhatsApp Business a cui l'utente di sistema deve accedere.

Utenti di sistema con funzioni di amministratore

Per impostazione predefinita, gli utenti di sistema con funzioni di amministratore hanno pieno accesso a tutti gli account WhatsApp Business e alle risorse di proprietà di o condivise con la tua azienda.

Gli utenti di sistema con funzioni di amministratore sono utili se la tua app ha bisogno di accedere agli account WhatsApp Business condivisi di recente con la tua azienda; se usi un utente di sistema con funzioni di dipendente, devi concedere manualmente l'accesso alle risorse business a ogni account WhatsApp Business condiviso con te.

Tieni presente che puoi sovrascrivere l'accesso predefinito di un utente di sistema con funzioni di amministratore concedendo l'accesso parziale alle risorse business per singolo account WhatsApp Business. Consulta Accesso alle risorse business per scoprire come impostare ed escludere l'accesso.

Creazione degli utenti di sistema

Per creare un utente di sistema:

1. Accedi a Meta Business Suite.
2. Individua il tuo account business nel menu a discesa in alto a sinistra e clicca sulla relativa icona a forma di ingranaggio Impostazioni.
3. Clicca su Impostazioni business.
4. Accedi a Utenti > Utenti di sistema.
5. Clicca sul pulsante Aggiungi e crea un utente di sistema amministratore o dipendente.

Generazione dei token d'accesso dell'utente di sistema

Per generare un token d'accesso dell'utente di sistema dopo aver creato un utente di sistema:

1. Accedi a Meta Business Suite.
2. Individua il tuo account business nel menu a discesa in alto a sinistra e clicca sulla relativa icona a forma di ingranaggio Impostazioni.
3. Clicca su Impostazioni business.
4. Accedi a Utente > Utenti di sistema.
5. Seleziona l'utente di sistema appropriato dalla lista degli utenti di sistema.
6. Clicca sul pulsante Genera un nuovo token.
7. Seleziona l'app che userà il token.
8. Seleziona tutte le autorizzazioni di cui l'API Graph ha bisogno per funzionare correttamente e generare il token.

Token d'accesso dell'utente di sistema con integrazione business

I token d'accesso dell'utente di sistema con integrazione business sono rivolti ai singoli clienti registrati e vengono usati dai fornitori di soluzioni tecnologiche e dai partner di soluzioni per accedere ai dati dei clienti registrati.

Questi token sono utili per le app che eseguono azioni programmatiche e automatizzate sugli account WhatsApp Business dei clienti senza doversi affidare agli input di un utente dell'app o senza dover richiedere la riautenticazione.

Per generare un token d'accesso dell'utente di sistema con integrazione business, devi implementare l'iscrizione integrata, configurata con Facebook Login for Business, e sostituire il codice che ti viene restituito quando un cliente completa il flusso.

Consulta il documento Iscrizione integrata e il documento token d'accesso dell'utente di sistema con integrazione business per maggiori informazioni sui token e su come vengono generati.

Token d'accesso dell'utente

Anche se i token d'accesso dell'utente sono supportati e possono essere usati da tutti gli sviluppatori di app, probabilmente li userai soltanto al tuo primo utilizzo della Dashboard gestione app per inviare il tuo primo messaggio di prova. Mentre sviluppi la tua app, molto probabilmente passerai a un token d'accesso dell'utente di sistema (ed eventualmente a un token d'accesso dell'utente di sistema dell'azienda, se sei un fornitore di soluzioni tecnologiche o un fornitore di soluzioni). Questo perché i token d'accesso dell'utente scadono rapidamente, quindi dovrai continuare a generarne di nuovi a distanza di poche ore.

Esistono diversi modi per generare un token d'accesso dell'utente:

• Accedi alla scheda Dashboard gestione app > WhatsApp > Configurazione API. Questa scheda genera sempre un nuovo token d'accesso dell'utente ogni volta che la visiti. Il token viene fornito automaticamente al tuo utente, dato che, al momento dell'apertura della scheda, avevi effettuato l'accesso al tuo account sviluppatore.
• Utilizza il Tool di esplorazione per la API Graph.
• Implementa Facebook Login.

Utilizzo dei token nelle richieste

Quando effettui delle richieste all'API, includi il token nell'intestazione di una richiesta di autorizzazione, preceduto da Bearer. Ad esempio:

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

Accesso alle risorse business

Dopo aver creato un utente di sistema, devi impostare i livelli di accesso alle risorse business. Molti endpoint richiedono che l'utente di sistema il cui token è incluso nelle richieste API abbia accesso parziale o completo alle risorse business all'account WhatsApp Business in questione (o alle sue risorse). Se l'utente di sistema non dispone di questo accesso, questi endpoint restituiranno il codice di errore 200.

Tieni presente che se imposti l'accesso alle risorse business di un utente di sistema su un account WhatsApp Business come accesso parziale, puoi limitare ulteriormente l'accesso a determinate risorse o azioni sull'account WhatsApp Business. Ad esempio, se hai un'azienda di grandi dimensioni e vuoi che un determinato reparto abbia accesso solo in lettura al modello di un account WhatsApp Business e ai dati del numero di telefono aziendale, puoi creare un utente di sistema per quel reparto e impostare l'accesso granulare di sola visualizzazione per quei dati.

Per impostare l'accesso alle risorse business su un account WhatsApp Business:

1. Accedi a Meta Business Suite.
2. Individua il tuo account business nel menu a discesa in alto a sinistra e clicca sulla relativa icona a forma di ingranaggio Impostazioni.
3. Accedi ad Account > Account WhatsApp.
4. Seleziona l'account WhatsApp Business desiderato.
5. Seleziona la tab Accesso all'account WhatsApp.
6. Clicca sul pulsante +Aggiungi persone.
7. Seleziona l'utente di sistema desiderato e assegna i livelli di accesso appropriati per l'account WhatsApp Business.

Test degli endpoint

Consigliamo di usare la nostra raccolta Postman o il nostro cURL per il test degli endpoint. Anche se puoi usare il Tool di esplorazione per la API Graph, questo passa i token come parametri della stringa della query, cosa che sconsigliamo di fare (piuttosto passa i token nelle intestazioni delle richieste).

Acquisizione di informazioni su un'azienda

Per ottenere le informazioni su un'azienda, invia una richiesta GET all'endpoint WhatsAppBusinessAccount in cui <WHATSAPP_BUSINESS_ACCOUNT_ID> corrisponda all'ID del tuo account WhatsApp Business.

Esempio di richiesta

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Esempio di risposta

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

Per ottenere informazioni specifiche su un'azienda, come nome, modelli di messaggi e numeri di telefono, invia una richiesta GET all'endpoint WhatsAppBusinessAccount in cui <WHATSAPP_BUSINESS_ACCOUNT_ID> corrisponde all'ID del tuo account WhatsApp Business e imposta il parametro fields su una lista di elementi che vorresti vengano restituiti.

Esempio di richiesta

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Esempio di risposta

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...
    

Rate limiting

Per saperne di più

• SDK di Facebook: per chiedere agli utenti le autorizzazioni utilizzando Facebook Login, puoi implementare uno dei nostri SDK.
• Business Manager API Marketing: scopri di più sul Business Manager dell'API Marketing.
• Analisi dell'app: scopri di più sulla procedura per accedere ai tuoi dati o ai dati di proprietà di altri.
• Guarda il video Set up the WhatsApp Business Platform (Configurazione della piattaforma WhatsApp Business).

Passaggi successivi

• Guide: scopri quali altre attività puoi svolgere con l'API Business Management di WhatsApp.
• Esplora la nostra raccolta Postman .