Primi passi per i partner di soluzioni

Questa guida illustra i passaggi che i partner di soluzioni devono compiere per offrire l'API Cloud ai propri clienti. Ci sono 4 fasi principali:

1. Preparazione e pianificazione
2. Configurazione delle risorse
3. Sottoscrizione di contratti
4. Creazione dell'integrazione

Completata la procedura, non perderti gli aggiornamenti mensili.

Preparazione e pianificazione

Lettura della documentazione

Prima di iniziare, ti consigliamo di leggere la documentazione per gli sviluppatori e la raccolta Postman. In questo modo puoi scoprire come funziona l'API Cloud, come muovere i primi passi ed effettuare la migrazione dei numeri.

Registrazione del piano e migrazione

Devi utilizzare l'iscrizione integrata per registrare nuovi clienti nell'API Cloud. Se non l'hai già fatto, integra e avvia l'iscrizione integrata. L'iscrizione integrata rappresenta il modo più semplice e rapido per registrare i clienti, consentendo loro di iniziare a inviare messaggi in meno di cinque minuti.

In seguito, pensa ai primi clienti per i quali desideri effettuare la migrazione all'API Cloud. In generale, ti consigliamo di effettuare la migrazione di tutti i clienti dall'API On-Premises all'API Cloud, ma le esigenze di ogni cliente possono variare. Pensando ai clienti per cui effettuare la migrazione, prendi in considerazione i seguenti elementi:

Dopo aver deciso per chi effettuerai la migrazione, puoi creare un piano di migrazione e definirne le tempistiche.

Durante la creazione del piano, ricorda di progettare il sistema per due scenari: registrazione dei nuovi clienti e migrazione di quelli attuali dall'API On-Premises all'API Cloud. Per lo scenario di migrazione, includi piani per eseguire il backup dell'istanza corrente sull'API On-Premises ed effettuare la migrazione di tali numeri all'API Cloud.

Pianificazione della comunicazione ai clienti

Innanzitutto, devi decidere se informare i clienti esistenti della migrazione. Quindi, devi stabilire se è necessario creare o aggiornare la documentazione per supportare la configurazione dell'API Cloud.

Adozione di decisioni sui prezzi

Poiché i costi di hosting per l'API Cloud sono coperti da Meta, devi decidere se desideri aggiornare i prezzi di conseguenza.

Configurazione delle risorse

Per utilizzare l'API Cloud, i partner di soluzioni devono disporre delle seguenti risorse:

Sottoscrizione di contratti

Accettazione delle condizioni d'uso

Per accedere all'API WhatsApp Business Messaging Cloud, devi prima accettare le condizioni d'uso della piattaforma WhatsApp Business per conto dell'azienda.

Per eseguire tale operazione, accedi a WhatsApp Manager e accetta le condizioni d'uso nel banner informativo.

Se sei un partner beta esistente per l'API Cloud, hai un periodo di tolleranza di 90 giorni. Ciò implica che devi accettare le condizioni prima del 5 luglio 2022, altrimenti perderai l'accesso.

Tutte le nuove aziende dell'API Cloud, comprese quelle che eseguono la migrazione dall'API On-Premises, dovranno accettare le condizioni d'uso prima di poter iniziare a utilizzare l'API Cloud. Le chiamate di registrazione avranno esito negativo fino a quando non accetti le condizioni d'uso.

Creazione dell'integrazione

Passaggio 1: acquisizione di un token d'accesso dell'utente di sistema

Le chiamate API Graph utilizzano token d'accesso per l'autenticazione. Per maggiori informazioni, consulta Token d'accesso. Ti consigliamo di utilizzare il tuo utente di sistema per generare il token.

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

1. Accedi a Business Manager > Impostazioni business > Utenti > Utenti di sistema per visualizzare l'utente di sistema creato.
2. Clicca su tale utente e seleziona Aggiungi risorse. Questa azione apre una nuova finestra.
3. In Seleziona il tipo di risorsa nel riquadro a sinistra, seleziona App. In Seleziona risorse, scegli l'app di Meta che desideri utilizzare (l'app deve disporre delle autorizzazioni corrette). Abilita Sviluppa l'app per tale app.
4. Seleziona Salva modifiche per salvare le impostazioni e tornare alla schermata principale dell'utente di sistema.
5. Adesso puoi generare il token. Nella schermata principale dell'utente di sistema, clicca su Genera token e seleziona l'app di Meta. Dopo la selezione dell'app, viene visualizzata una lista di autorizzazioni disponibili. Seleziona whatsapp_business_management e whatsapp_business_messaging. Clicca su Genera token.
6. Si apre una nuova finestra con l'utente di sistema, l'app assegnata e il token d'accesso. Salva il token.
7. Se lo desideri, puoi cliccare sul token per vedere il debugger, dove dovrebbero essere riportate le due autorizzazioni selezionate. Puoi anche incollare direttamente il token nel debugger dei token d'accesso.

Passaggio 2: configurazione dei webhook

Configurando i webhook, puoi ricevere notifiche HTTP in tempo reale dalla piattaforma WhatsApp Business, ad esempio quando ricevi un messaggio da un cliente o quando vengono apportate modifiche all'account WhatsApp Business (WABA).

Per configurare il webhook, devi creare un server web con connessione Internet (Internet-facing) con un URL che soddisfi i requisiti di Meta e WhatsApp. Consulta Creazione di un endpoint per le istruzioni su come eseguire tale operazione. Se hai bisogno di un endpoint per scopi di test, puoi generare un endpoint dei webhook di prova.

Configurazione dell'app

Quando l'endpoint è pronto, configuralo affinché sia utilizzato dall'app di Meta:

Devi configurare i webhook solo una volta per ogni app a disposizione. Puoi utilizzare lo stesso webhook per ricevere più tipi di eventi da più account WhatsApp Business. Per maggiori informazioni, consulta la sezione sui webhook.

Passaggio 3: attivazione dell'iscrizione per l'account WhatsApp Business

Per avere la certezza di ricevere notifiche per l'account corretto, attiva l'iscrizione per l'app:

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Se ricevi la risposta seguente, tutti gli eventi del webhook per i numeri di telefono di questo account verranno inviati all'endpoint del webhook configurato.

{
  "success": true
}

Passaggio 4: acquisizione dell'ID del numero di telefono

Per inviare messaggi, devi registrare il numero di telefono che desideri utilizzare (ovvero il numero di telefono aziendale menzionato in Prima di iniziare).

Prima di poter procedere con la registrazione, devi trovare l'ID di questo numero. Per ottenerlo, effettua la seguente chiamata API:

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Se la richiesta è stata eseguita correttamente, la risposta include tutti i numeri di telefono connessi all'account WhatsApp Business:

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Salva l'ID del numero di telefono che desideri registrare. Consulta Lettura dei numeri di telefono per maggiori informazioni su questo endpoint.

Eccezione migrazione

Passaggio 5: registrazione del numero di telefono

Dopo aver ottenuto l'ID del numero di telefono, puoi procedere alla registrazione. Nella chiamata API Registration, esegui due azioni contemporaneamente:

1. Registra il numero di telefono.
2. Abilita la verifica in due passaggi impostando un codice di registrazione a 6 cifre (sei tu a dover impostare questo codice). Salva e memorizza questo codice poiché potrà essere richiesto in un secondo momento.

La configurazione dell'autenticazione a due fattori è un requisito per l'utilizzo dell'API Cloud. Se non la configuri, riceverai un messaggio di errore di registrazione:

Esempio di richiesta:

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

Esempio di risposta:

{
  "success": true
}

Utenti dell'iscrizione integrata

Passaggio 6: ricezione di un messaggio dall'app del consumatore

Se i clienti partecipanti inviano un messaggio alla tua azienda, per 24 ore puoi scambiare messaggi gratuiti con loro: tale intervallo di tempo è la "finestra dell'assistenza clienti". A scopo di test, abilita questa finestra temporale in modo da poter inviare tutti i messaggi che desideri.

Da un'app WhatsApp per iOS/Android personale, invia un messaggio al numero di telefono appena registrato. Dopo l'invio del messaggio, dovresti ricevere un messaggio in arrivo sul webhook con una notifica nel formato seguente.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

Passaggio 7: invio di un messaggio di prova

Dopo l'abilitazione della finestra dell'assistenza clienti, puoi inviare un messaggio di prova al numero del consumatore utilizzato nel passaggio precedente. Per farlo, effettua la seguente chiamata API:

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

Se la chiamata è stata eseguita correttamente, la risposta includerà un ID del messaggio. Utilizza tale ID per monitorare il progresso dei tuoi messaggi tramite webhook. La lunghezza massima dell'ID è di 128 caratteri.

Esempio di risposta:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

Non perderti gli aggiornamenti mensili

Il primo martedì di ogni mese pubblicheremo gli aggiornamenti dell'API Cloud, che includeranno nuove funzioni e miglioramenti. Poiché l'API Cloud si aggiorna automaticamente, non devi fare nulla per utilizzare le nuove funzioni.

FAQ

FAQ generali

FAQ sull'implementazione tecnica

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

Permalink

FAQ su privacy e sicurezza dei dati

FAQ sulla conformità normativa