API Cloud

Piattaforma WhatsApp Business > API Cloud

Panoramica

L'API Cloud, ospitata da Meta, consente alle imprese di medie e grandi dimensioni di comunicare con i clienti su larga scala. Utilizzando l'API, le aziende possono creare sistemi che connettono migliaia di clienti con agenti o bot, consentendo la comunicazione sia programmatica che manuale. L'API può anche essere integrata con numerosi sistemi di back-end, come CRM e piattaforme di marketing.

Protocollo HTTP

L'API Cloud è stata creata a partire dall'API Graph, questo significa che le richieste vengono espresse utilizzando il protocollo HTTP e combinazioni di parametri URL, intestazioni e corpi della richiesta. Ad esempio, una chiamata comune all'API Cloud da una riga di comando basata su UNIX ha il seguente aspetto:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Se non hai familiarità con l'API Graph, fai riferimento alla nostra documentazione sull'API Graph per apprendere le nozioni di base. Le principali differenze tra API Graph e API Cloud sono i tipi di token d'accesso che si utilizzano comunemente, le autorizzazioni delle risorse, la sintassi delle richieste e quella dei webhook. Queste differenze sono descritte in modo più dettagliato nelle sezioni dedicate della documentazione sull'API Cloud.

Risorse

Queste sono le risorse principali con cui interagirai durante l'utilizzo dell'API.

Portfolio business

Per utilizzare l'API, devi avere un portfolio business. Se non hai un portfolio, ti verrà richiesto di crearne uno nell'ambito della nostra procedura Primi passi. I portfolio business fungono da contenitore per i tuoi account WhatsApp Business (WABA) e i numeri di telefono aziendali.

Per saperne di più sui portfolio business, consulta l'articolo del nostro Centro assistenza Informazioni sui portfolio business in Meta Business Suite.

Account WhatsApp Business

Un account WhatsApp Business rappresenta un'azienda sulla piattaforma WhatsApp Business ed è composto principalmente da metadati su una specifica azienda. La maggior parte delle altre risorse WhatsApp, come i numeri di telefono WhatsApp Business e i modelli di messaggi WhatsApp, è associata a un account WhatsApp Business.

Puoi creare un account WhatsApp Business, seguendo i passaggi del nostro documento Primi passi. Per ulteriori informazioni sugli account WhatsApp Business e le loro limitazioni, consulta Account WhatsApp Business.

Numeri di telefono WhatsApp Business

Un numero di telefono WhatsApp Business (numero di telefono aziendale) rappresenta un numero di telefono reale, che, una volta registrato per l'utilizzo con l'API Cloud, può essere utilizzato per scambiare messaggi con gli utenti di WhatsApp tramite l'API.

I numeri di telefono aziendali sono composti principalmente da metadati sul numero stesso e sulla tua azienda, i quali possono essere visibili nel client WhatsApp quando gli utenti interagiscono con il tuo numero di telefono aziendale.

Puoi creare un numero di telefono aziendale seguendo i passaggi descritti nel nostro documento Primi passi. Tieni presente che ci sono restrizioni e limitazioni ai numeri di telefono aziendali e ai loro utilizzi, descritte in dettaglio nel nostro documento Numeri di telefono aziendali.

Modelli di messaggi WhatsApp

I modelli di messaggi WhatsApp (modelli) sono personalizzabili tramite l'API grazie ai diversi componenti disponibili. Una volta creati, vengono automaticamente controllati e, se approvati, possono essere utilizzati nei modelli di messaggi.

Esistono due tipi di messaggi di base che puoi inviare tramite l'API: i messaggi in forma libera e i modelli di messaggi. Dei due, i modelli di messaggi sono quelli con più restrizioni in quanto richiedono l'uso di un modello di messaggio WhatsApp approvato. Tuttavia, poiché i modelli devono essere controllati e approvati prima di poter essere utilizzati, i modelli di messaggi hanno minori probabilità di ricevere feedback negativi dai destinatari, che potrebbero mettere a repentaglio la tua capacità di inviare messaggi ai clienti.

Per ulteriori informazioni sui modelli, consulta il nostro documento Modelli.

Webhook

I webhook sono semplicemente payload JSON che utilizzano lo stesso protocollo HTTP per un endpoint pubblico sul tuo server. L'API Cloud fa uso intensivo di webhook, in quanto il contenuto di qualsiasi messaggio inviato da un utente di WhatsApp al tuo numero di telefono aziendale verrà inviato come webhook e tutti gli aggiornamenti dello stato di consegna dei messaggi in uscita vengono segnalati tramite webhook.

Se può tornarti utile, offriamo un'app webhook di esempio che puoi clonare su Glitch e utilizzare per i test. L'app scarica i payload dei webhook direttamente su una console in modo che tu possa vederne il contenuto. Ricorda che a un certo punto dovrai creare un endpoint sul tuo server che elabori i webhook secondo la tua logica aziendale.

Consulta Webhook di Meta per saperne di più sui webhook e su come elaborarli e il nostro documento Webhook per gli account WhatsApp Business.

Risorse di prova

La prima volta che completi i passaggi del nostro documento Primi passi, vengono creati automaticamente un account WhatsApp Business di prova e un numero di telefono aziendale di prova per te.

Gli account WhatsApp Business di prova e i numeri di telefono aziendali di prova sono utili per lo svolgimento di test, in quanto bypassano la maggior parte dei limiti di messaggistica e non richiedono un metodo di pagamento registrato per l'invio di modelli di messaggi.

Puoi eliminare il tuo portfolio business e le relative risorse di prova se:

  • sei un amministratore del portfolio business associato all'app;
  • al portfolio business non sono associate altre app;
  • il portfolio business non è associato ad altri account WhatsApp Business;
  • l'account WhatsApp Business non è associato ad altri numeri di telefono aziendali.

Per eliminare il tuo portfolio business e le relative risorse di prova:

  1. Accedi alla Dashboard gestione app > WhatsApp > scheda Configurazione.
  2. Individua la sezione Account di prova.
  3. Clicca sul pulsante Elimina.

Autenticazione e autorizzazione

Token d'accesso

L'API supporta tre tipi di token:

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

Consulta la nostra documentazione Token d'accesso per sapere quale tipo di token usare. Tieni presente che i token devono essere passati tramite intestazioni di richiesta, non come parametro della stringa della query.

Autorizzazioni

L'API si basa sulle seguenti autorizzazioni dell'API Graph. La combinazione esatta di autorizzazioni di cui la tua app ha bisogno dipende dagli endpoint a cui la tua app avrà accesso.

  • business_management: necessaria in caso di interazione con un portfolio business.
  • whatsapp_business_management: necessaria in caso di interazione con un account WhatsApp Business e i relativi dati statistici oppure con i suoi modelli o numeri di telefono aziendali.
  • whatsapp_business_messaging: necessaria per poter scambiare messaggi con gli utenti di WhatsApp.

Queste autorizzazioni sono tipicamente concesse quando si generano token d'accesso in Meta Business Suite. Consulta le sezioni sulla generazione dei token nel nostro documento Token d'accesso.

Gestione delle versioni

La gestione delle versioni utilizza il protocollo di gestione delle versioni dell'API Graph. Ciò significa che tutte le richieste di endpoint possono includere un numero di versione e ogni versione sarà disponibile per circa 2 anni prima di essere ritirata e non potrà più essere chiamata.

Throughput

Per ogni numero di telefono aziendale registrato, l'API Cloud supporta fino a 80 messaggi al secondo (mps) per impostazione predefinita e fino a 1000 mps per aggiornamento automatico.

Il throughput comprende messaggi in entrata e in uscita e tutti i tipi di messaggi. I numeri di telefono aziendali, indipendentemente dal throughput, sono soggetti al rate limiting per casi d'uso aziendali e ai limiti di messaggi dei modelli dell'account WhatsApp Business.

Se provi a inviare più messaggi di quanto consentito dal tuo attuale livello di throughput, l'API restituisce il codice di errore 130429 finché non sarai di nuovo entro il livello consentito. Inoltre, i livelli di throughput sono pensati per campagne di messaggistica che coinvolgono numeri di telefono di diversi utenti di WhatsApp. Se tenti di inviare troppi messaggi allo stesso numero di un utente di WhatsApp, potresti ricevere un errore di associazione rate limiting.

Throughput più elevato

Se soddisfi i nostri requisiti di idoneità, aggiorneremo automaticamente il tuo numero di telefono aziendale a 1000 mps senza alcun costo per te. Un throughput più elevato non comporta costi aggiuntivi né incide sui prezzi.

La procedura di aggiornamento può richiedere fino a 1 minuto. Durante questo periodo, il numero non sarà utilizzabile nella nostra piattaforma. Se usata in una richiesta API, l'API restituirà il codice di errore 131057. Dopo che un numero di telefono aziendale è stato aggiornato, verrà automaticamente aggiornato per gli eventuali aumenti di throughput futuri, senza tempi di inattività.

Requisiti di idoneità

Webhook

I server dei webhook dovrebbero essere in grado di fronteggiare una capacità del traffico di messaggi in uscita 3 volte superiore e una capacità del traffico previsto di messaggi in arrivo 1 volta superiore. Ad esempio, se si inviano 1000 mps con una percentuale di risposte prevista del 30%, i server dovrebbero poter elaborare fino a 3000 webhook per lo stato dei messaggi, più altri 300 webhook per i messaggi in arrivo.

Proviamo a consegnare i webhook contemporaneamente, quindi ti consigliamo di configurare e caricare il test del server del webhook per gestire richieste simultanee con il seguente standard di latenza:

  • Latenza media che non supera 250 ms.
  • Meno dell'1% di latenza che supera 1 s.

Proveremo a consegnare nuovamente i webhook non andati a buon fine per un massimo di 7 giorni, con backoff esponenziale.

Messaggi con contenuto multimediale

Per sfruttare al massimo il throughput più elevato, ti consigliamo di caricare le risorse multimediali sui nostri server e utilizzare gli ID dei contenuti multimediali restituiti nei messaggi con contenuto multimediale invece di ospitare le risorse sui nostri server e utilizzare gli URL. Se preferisci (o devi) ospitare le risorse sui tuoi server, ti consigliamo di utilizzare la memorizzazione nella cache dei contenuti multimediali.

Acquisizione del livello di throughput

Usa l'endpoint WhatsApp Business Phone Number per ottenere l'attuale livello di throughput di un numero di telefono:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migrazione

Se effettui la migrazione di un numero di telefono aziendale su cui multiconnect esegue 2 o più partizioni dall'API On-Premises all'API Cloud, sarà automaticamente passato al livello di throughput superiore.

Rate limiting

Consulta Rate limiting, API WhatsApp Business Management.

In aggiunta a questi rate limiting, abbiamo limiti più granulari sulle singole risorse, come i modelli di messaggi e i numeri di telefono aziendali di prova:

Metriche disponibili

In qualità di utente dell'API Cloud, puoi vedere il numero di messaggi inviati e consegnati nonché altre metriche. Per informazioni, consulta Ottenere le metriche dell'account.

Scalabilità

All'interno dell'infrastruttura di Meta, l'API Cloud aumenta i volumi e si adatta automaticamente per gestire il carico di lavoro entro il tuo rate limiting (volume di messaggi e numero di account WhatsApp Business).

Privacy e sicurezza dei dati

Per informazioni, consulta la nostra Panoramica su privacy e sicurezza.

Crittografia

Con l'API Cloud, ogni messaggio WhatsApp continua a essere protetto dalla crittografia del protocollo Signal, che protegge i messaggi prima che lascino il dispositivo. Ciò significa che i messaggi con un account WhatsApp Business vengono consegnati in modo sicuro alla destinazione scelta da ciascuna azienda.

L'API Cloud utilizza tecniche di crittografia standard del settore per proteggere i dati in transito e a riposo. L'API utilizza l'API Graph per l'invio di messaggi e webhook per la ricezione di eventi, ed entrambi operano su HTTPS standard del settore, protetti da TLS. Per ulteriori dettagli, consulta il nostro white paper Encryption Overview (Panoramica sulla crittografia).

Per ulteriori dettagli, consulta il nostro white paper Encryption Oveview (Panoramica sulla crittografia).

Associazione di rate limiting

I numeri di telefono aziendali sono limitati all'invio di 1 messaggio ogni 6 secondi allo stesso numero di telefono di un utente di WhatsApp (0,17 messaggi/secondo). Questo equivale all'incirca a 10 messaggi al minuto, o a 600 messaggi all'ora. Se superi questo limite, l'API restituirà il codice di errore 131056 finché non sarai di nuovo entro il tuo limite.

Se necessario, puoi inviare fino a 45 messaggi in 6 secondi come sequenza. Se invii una sequenza, stai essenzialmente prendendo in prestito quanto consentito dal tuo rate limiting di associazione, questo significa che non potrai inviare ulteriori messaggi allo stesso utente finché non sarà trascorso il tempo normalmente necessario per inviare quella quantità di messaggi in modalità "non in sequenza". Ad esempio, ci vogliono circa 2 minuti per inviare 20 messaggi "non in sequenza" a un utente, quindi se invii una sequenza di 20 messaggi, dovrai aspettare circa 2 minuti prima di poter inviare un altro messaggio a quell'utente.

Per evitare di dover calcolare i tempi di attesa post-sequenza, consigliamo, se una richiesta di invio di messaggi ha esito negativo dopo aver inviato una sequenza, di riprovare 4^X secondi dopo, dove X = 0 e aumenta di 1 dopo ogni tentativo fallito, fino a quando la richiesta non va a buon fine.

Strumenti

WhatsApp Manager

WhatsApp Manager è la nostra app web che ti consente di gestire manualmente le risorse WhatsApp, come account WhatsApp Business, numeri di telefono aziendali e modelli, semplificando la visualizzazione di insight e limiti o valutazioni di qualità su queste risorse. La maggior parte delle funzionalità offerte da WhatsApp Manager è disponibile anche tramite l'API, con alcune piccole eccezioni.

Esistono diversi modi per accedere a WhatsApp Manager. Ogni percorso implica che tu abbia già completato tutti i passaggi del nostro documento Primi passi.

Tramite Meta Business Suite

  1. Accedi a Meta Business Suite.
  2. Se hai più portfolio business, usa il menu a discesa a sinistra per selezionare l'account che possiede o che ha accesso all'account WhatsApp Business che desideri caricare su WhatsApp Manager.
  3. Nel menu a sinistra, vai ad Account > Account WhatsApp.
  4. Seleziona l'account WhatsApp Business.
  5. Nella tab Riepilogo, clicca sul pulsante WhatsApp Manager.

Tramite la Dashboard gestione app

  1. Vai a Le mie app.
  2. Seleziona l'app associata all'account WhatsApp Business che vuoi caricare su WhatsApp Manager.
  3. Nel menu a sinistra, vai a WhatsApp > Avvio rapido.
  4. Clicca sul riquadro Informazioni account nella sezione WhatsApp Business.

Tramite URL

Puoi accedere direttamente alla Panoramica di WhatsApp Manager, che mostra tutti gli account WhatsApp Business di proprietà di o condivisi con un determinato portfolio business, da questo indirizzo:

https://business.facebook.com/wa/manage/home/

Per impostazione predefinita, la panoramica carica l'account WhatsApp Business più recente che hai creato o a cui ti è stato concesso l'accesso, ma puoi usare il menu a discesa a sinistra per selezionare il portfolio business contenente l'account WhatsApp Business a cui vuoi accedere. In questo modo però uscirai dalla panoramica e dovrai usare il menu a sinistra per andare ad Account > Account WhatsApp > (selezione account WhatsApp Business desiderato) > Impostazioni > WhatsApp Manager (pulsante).

In alternativa, se hai più portfolio business, puoi aggiungere l'ID di un account alla fine dell'URL e aggiungerlo ai segnalibri per facilitare l'accesso:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

Abbiamo una raccolta Postman dell'API Cloud contenente query comuni nell'area di lavoro della nostra piattaforma WhatsApp Business.