Questo articolo illustra gli errori che potresti riscontrare utilizzando l'API pubblica di WhatsApp, il modo in cui le valutazioni della qualità e i livelli di messaggistica influiscono sulla capacità di invio e quali problemi puoi risolvere autonomamente rispetto a quelli che richiedono l'intervento di Meta o del Supporto Aircall.
Riferimento degli errori
| Errore | Significato | Cosa fare |
|---|---|---|
| 403 | L'account utilizza Essentials, non dispone di un componente aggiuntivo WhatsApp attivo oppure la funzionalità non è abilitata | Conferma lo stato del piano e del componente aggiuntivo nella dashboard di Aircall. Contatta il Supporto Aircall per verificare che la funzionalità sia disponibile nel tuo piano. |
| 400 — linea non configurata | La linea non è stata registrata per l'utilizzo dell'API pubblica | Chiama prima POST /v1/numbers/{id}/messages/configuration. |
| 400 — modello non approvato | Il modello inviato non presenta lo stato APPROVED in Meta | Controlla lo stato del modello in Meta Business Manager. Aircall non può risolvere questo problema. |
| 63016 — finestra di 24 ore scaduta | L'invio restituisce una risposta 200, ma il tuo webhook riceve un callback con un errore quando viene inviato testo in formato libero al di fuori della finestra di conversazione | Utilizza un modello approvato per riavviare una conversazione con il cliente. Consulta la sezione sulla finestra di 24 ore nell'articolo Introduzione all'API pubblica di Whatsapp. |
| 400 — WABA non configurato | La linea WhatsApp non dispone di un WABA (account WhatsApp Business) configurato | Contatta il Supporto Aircall. Si tratta di un problema di configurazione della linea. |
| 400 — linea OFFLINE o BLOCKED | La linea non si trova in uno stato di invio attivo | Controlla l'endpoint relativo allo stato della linea. Se è BLOCKED, contatta il Supporto Aircall. |
| 429 | Limite del livello di messaggistica superato: è stato raggiunto il limite giornaliero di conversazioni | Limite imposto da Meta. Si azzera ogni 24 ore. Aircall non può ignorarlo. |
| 131048 | Limite di frequenza antispam di Meta: gli invii da questo numero sono soggetti a restrizioni da parte di Meta | Esamina la qualità della messaggistica e contatta il Supporto Meta Business. Aircall non può ignorare questa restrizione. |
| 131045 | Errore di registrazione del numero di telefono presso un fornitore esterno | Contatta il Supporto Aircall |
| 131000 | Errore Meta sconosciuto | Se l'errore persiste, contatta il Supporto Aircall fornendo l'ID dell'azienda, l'ID della linea, il payload completo dell'errore e un timestamp. |
La finestra di conversazione di 24 ore
La finestra di conversazione di WhatsApp è una regola di Meta, non un'impostazione di Aircall. Determina quando è possibile inviare messaggi di testo in formato libero.
- Una finestra di 24 ore si apre quando un cliente invia un messaggio al tuo numero o risponde a uno dei tuoi messaggi.
- All'interno di questa finestra puoi inviare testo in formato libero.
- Una volta chiusa la finestra, puoi inviare soltanto un modello approvato per riavviare la conversazione.
IMPORTANTE: Il tentativo di inviare testo in formato libero al di fuori di una finestra aperta restituirà un errore al tuo webhook. La soluzione consiste sempre nell'inviare prima un modello approvato. Aircall non può ignorare o estendere la finestra.
Valutazione della qualità
Meta assegna a ogni linea WhatsApp una valutazione della qualità in base al modo in cui i destinatari reagiscono ai messaggi provenienti da quel numero. Se i destinatari bloccano o segnalano frequentemente il tuo numero, la valutazione peggiora.
- GREEN: linea in regola, nessuna restrizione di invio.
- YELLOW: la qualità sta peggiorando, spesso perché i clienti segnalano i tuoi messaggi come spam o bloccano il tuo numero. Esamina la qualità dei modelli e valuta la possibilità di ridurre il volume di invio.
- RED: Meta ha applicato restrizioni a questa linea. Gli invii potrebbero non riuscire. Contatta il Supporto Meta Business.
IMPORTANTE: Le valutazioni della qualità sono stabilite e controllate da Meta. Aircall non può modificarle. Per migliorare la valutazione sono necessari modelli migliori, elenchi di contatti più puliti e consensi espliciti confermati dai destinatari.
Livelli di messaggistica
Meta limita il numero di conversazioni avviate dall'azienda che una linea può iniziare nell'arco di 24 ore. Questo è il livello di messaggistica. I livelli aumentano automaticamente man mano che Meta acquisisce fiducia nella qualità e nei modelli di invio di un numero. Non esiste una procedura manuale per richiedere un aumento di livello.
| Livello | Conversazioni ogni 24 ore | Tipo di account tipico |
|---|---|---|
| TIER_250 | 250 | Linee nuove o non verificate |
| TIER_1K | 1,000 | Aziende standard verificate |
| TIER_10K | 10,000 | Mittenti consolidati e di alta qualità |
| TIER_100K | 100,000 | Aziende verificate con elevati volumi |
NOTA: Se la tua integrazione restituisce un errore 429, è stato raggiunto il limite giornaliero del livello. Il limite si azzera ogni 24 ore. In questo caso, integra nella tua integrazione una logica per ripetere il tentativo.
Cosa puoi e non puoi controllare
Alcune limitazioni sono stabilite da Meta e non possono essere modificate né da Aircall né da te.
Nessuno in Aircall può ignorare le seguenti limitazioni:
- Valutazioni della qualità
- Limiti dei livelli di messaggistica
- Sblocco di un numero soggetto a restrizioni da parte di Meta
- Approvazione o rifiuto dei modelli di messaggi WhatsApp
- Finestra di conversazione di 24 ore
Contatta il Supporto Aircall per:
- Verificare lo stato della funzionalità o attivarla
- Errori relativi a WABA non configurato (400)
- Linee OFFLINE o BLOCKED
- Errori di registrazione del numero di telefono (131045)
- Errori sconosciuti persistenti (131000): fornisci l'ID dell'azienda, l'ID della linea, il payload completo dell'errore e un timestamp
Contatta direttamente il Supporto Meta Business per:
- Restrizioni della frequenza antispam (131048)
- Peggioramento della valutazione della qualità
- Linee completamente bloccate da Meta
Domande frequenti
Le mie chiamate API restituiscono un errore 403 anche se disponiamo di un componente aggiuntivo WhatsApp. Qual è il problema?
Un errore 403 può anche indicare che la funzionalità non è ancora abilitata per il tuo account o che il tuo piano è Essentials. Contatta il Supporto Aircall per verificare che siano soddisfatti tutti i requisiti di idoneità: piano Pro o superiore, componente aggiuntivo WhatsApp attivo e linea registrata.
Posso inviare un messaggio a un cliente che non ci ha mai scritto per primo?
Sì, utilizzando un modello approvato. I modelli approvati possono essere inviati al di fuori della finestra di 24 ore per avviare un contatto. I messaggi di testo in formato libero richiedono una finestra di conversazione aperta, ovvero il cliente deve averti inviato un messaggio o risposto nelle ultime 24 ore.
Perché la mia linea mostra una valutazione della qualità GIALLA o ROSSA?
Meta riduce le valutazioni della qualità quando i destinatari bloccano o segnalano i messaggi provenienti dal tuo numero. In genere, ciò accade quando si inviano messaggi non richiesti, si utilizzano modelli di bassa qualità o si contattano persone che non hanno fornito il proprio consenso. Aircall non può modificare questa valutazione. Migliora le tue pratiche di messaggistica e attendi che la valutazione si ripristini naturalmente.
Quanto rapidamente si azzerano i limiti dei livelli di messaggistica?
Ogni 24 ore dal momento in cui viene raggiunto il limite. Se ricevi un errore 429, attendi 24 ore prima di riprovare. I livelli aumentano automaticamente nel tempo man mano che Meta acquisisce fiducia nella qualità dei tuoi invii.
Vogliamo che HubSpot o Salesforce inviino automaticamente messaggi WhatsApp. Da dove iniziamo?
Inizia dall'articolo introduttivo indicato di seguito. Una volta registrata la linea, il tuo team CRM o RevOps può creare flussi di lavoro che richiamano POST /v1/messages/whatsapp/send quando cambiano le fasi delle trattative, i contratti sono pronti o si verificano altri eventi di attivazione.