L'API pubblica di WhatsApp di Aircall consente agli sviluppatori e agli Strumenti esterni (HubSpot, Salesforce e script personalizzati) di inviare messaggi WhatsApp a livello di codice per conto della tua azienda, senza che un Agente debba inviarli manualmente da Aircall Workspace. Questo articolo spiega chi può utilizzare l'API, come registrare una linea e cosa fa ogni endpoint.

Chi può utilizzare l'API pubblica di WhatsApp

Perché l'API funzioni per la tua azienda, devono essere soddisfatte tutte e quattro le seguenti condizioni:

  • Piano Aircall Professional: gli account Essentials non sono idonei e restituiranno un errore 403.
  • Add-on WhatsApp: almeno una licenza Add-on WhatsApp attiva sull'account.
  • Disponibilità della funzionalità: viene abilitata automaticamente per i clienti idonei e non richiede alcuna azione, a meno che non sia stata disabilitata. Se sospetti che sia stata disabilitata, contatta il Supporto Aircall.
  • Registrazione della linea: la linea WhatsApp deve essere registrata per l'utilizzo dell'API pubblica tramite l'endpoint di configurazione prima di poter effettuare qualsiasi invio.
Importante: Tutte le condizioni devono essere soddisfatte. Se ne manca anche solo una, l'API non funzionerà per quell'azienda.

Le due modalità di invio

Quando invii un messaggio WhatsApp tramite l'API, puoi scegliere tra due modalità.

  • Invio proxy: il messaggio viene inviato per conto dello sviluppatore e non appare nella Posta in arrivo dell'Agente. Gli aggiornamenti sulla consegna e le risposte in entrata vengono inviati al callbackUrl registrato.
  • Invio nativo: il messaggio viene inviato e appare nella conversazione dell'Agente in Workspace. L'Agente può visualizzare e continuare la conversazione da Aircall.
Nota: Le due modalità di invio si escludono a vicenda. L'invio proxy richiede che la linea sia registrata per l'utilizzo dell'API pubblica tramite l'endpoint di configurazione. L'invio nativo richiede che non sia registrata.

I quattro endpoint dell'API

Registrare una linea per l'utilizzo dell'API pubblica

POST /v1/numbers/{id}/messages/configuration

Registra una linea WhatsApp e fornisci un callbackUrl: l'URL al quale Aircall invierà gli aggiornamenti sulla consegna e le risposte in entrata. Questo passaggio deve essere completato prima di poter inviare qualsiasi messaggio.

Importante: Se l'API non funziona, la prima cosa da verificare è se la linea è stata registrata tramite questo endpoint. Senza registrazione, tutti i tentativi di invio restituiranno un errore.

Verificare lo stato della linea

GET /v1/numbers/{id}/whatsapp_status

Restituisce lo stato corrente di una linea WhatsApp. Richiama questo endpoint prima dell'invio per confermare che la linea sia in buono stato. La risposta include:

  • Stato: indica se la linea è ONLINE, OFFLINE o NOT_REGISTERED
  • canSendMessage: indica se la linea può attualmente inviare messaggi (AVAILABLE, LIMITED o BLOCKED)
  • qualityRating: l'indicatore di Meta relativo al coinvolgimento dei destinatari (GREEN, YELLOW o RED)
  • messagingLimitTier: il numero massimo di conversazioni avviate dall'azienda che la linea può iniziare ogni 24 ore (TIER_250, TIER_1K, TIER_10K o TIER_100K)

Inviare un messaggio

POST /v1/messages/whatsapp/send

POST /v1/messages/send/whatsapp/native

Invia un messaggio WhatsApp a livello di codice. Sono supportati due tipi di messaggio:

  • Modelli approvati: possono essere inviati in qualsiasi momento, all'interno o all'esterno della finestra di conversazione di 24 ore
  • Testo libero: può essere inviato solo all'interno di una finestra di conversazione di 24 ore Aperta

Consulta la sezione "La finestra di conversazione di 24 ore" qui sotto per maggiori dettagli su quando si applica ciascun tipo.

Elencare i modelli disponibili

GET /v1/numbers/{id}/templates

Restituisce tutti i Modelli di messaggi WhatsApp per una linea, incluso il relativo stato di approvazione (APPROVED, PENDING, REJECTED, PAUSED o DISABLED) e la struttura delle variabili per ciascun modello. Utilizza questo endpoint per confermare quali modelli sono disponibili prima dell'invio.

Configurazione dell'API pubblica di WhatsApp

Passaggi:

  1. Verifica che il tuo account utilizzi il Piano Pro e disponga di almeno una licenza Add-on WhatsApp attiva.
  2. Richiama POST /v1/numbers/{id}/messages/configuration con l'ID della tua linea WhatsApp e il tuo callbackUrl per registrare la linea.
  3. Richiama GET /v1/numbers/{id}/whatsapp_status per confermare che la linea sia ONLINE e che canSendMessage mostri AVAILABLE.
  4. Richiama GET /v1/numbers/{id}/templates per recuperare i modelli approvati.
  5. Invia il tuo primo messaggio utilizzando POST /v1/messages/whatsapp/send.
Suggerimento: Controlla sempre lo stato della linea prima dell'invio, soprattutto nei Flussi di lavoro automatizzati. Lo stato di una linea può cambiare in base alla valutazione della qualità e alle regole di Meta. Integrare un controllo dello stato prima dell'invio nella tua Integrazione evita invii non riusciti.

La finestra di conversazione di 24 ore

La regola di Meta relativa alla finestra di conversazione determina quando è possibile inviare messaggi di testo libero:

  • Quando un cliente invia un messaggio al tuo Numero o risponde a uno dei tuoi messaggi, si apre una finestra di 24 ore.
  • All'interno di tale finestra, puoi inviare messaggi di testo libero.
  • Una volta chiusa la finestra (se il cliente non risponde entro 24 ore), per ristabilire il contatto è possibile inviare solo modelli approvati.
Nota: L'invio di testo libero al di fuori di una finestra Aperta restituisce una risposta 200, ma il Webhook registrato riceverà un callback contenente un errore 63016. Utilizza un modello approvato per riaprire la conversazione. Aircall non può ignorare o estendere la finestra.

Riferimento API

Per gli schemi completi di richiesta e risposta, i dettagli sull'autenticazione e gli esempi di codice, consulta la documentazione per sviluppatori di Aircall.