Metriche WhatsApp
La pagina Metrics nella dashboard Bird mostra come sta andando il tuo canale WhatsApp: quanti messaggi hanno raggiunto il dispositivo del destinatario, se il tasso di fallimento sta salendo e quanto velocemente si è mosso tutto. Questa guida illustra la pagina, il significato di ogni numero e quando intervenire.
Le metriche sono la vista aggregata su tutto ciò che il tuo spazio di lavoro invia. Per il ciclo di vita di un singolo messaggio (questo numero lo ha ricevuto? quando?), consulta il log WhatsApp e gli eventi.
Leggere le metriche
La pagina Metrics si trova in WhatsApp → Metrics nella dashboard Bird; è visibile ai membri dello spazio di lavoro che dispongono sia del permesso di lettura WhatsApp sia del permesso Analytics read. Ogni numero rispetta il selettore di intervallo (ultime 24 ore, 7, 30 o 90 giorni). I nuovi eventi compaiono dopo aggregazione e replica, perciò il periodo più recente è provvisorio.
I tassi in uscita usano il momento di accettazione di ogni messaggio. Una conferma di consegna che arriva oggi per un messaggio accettato ieri viene conteggiata su ieri, insieme al relativo accepted. Ogni intervallo segue quindi i messaggi accettati al suo interno man mano che le osservazioni arrivano. Le ore più recenti possono sottostimare delivered mentre le conferme sono ancora in arrivo. accepted è il denominatore per le schede del tasso di consegna e del tasso di fallimento.
I conteggi rappresentano messaggi distinti per ogni evento osservato e possono essere approssimativi su larga scala. Non formano un funnel obbligatorio: una conferma di lettura può esistere senza una conferma di consegna, e osservazioni mancanti possono lasciare lacune tra le fasi. Le statistiche di gruppo contano anch'esse messaggi, non destinatari; la prima consegna osservata a un partecipante può incrementare il conteggio delivered prima che tutti i membri del gruppo abbiano ricevuto il messaggio.
Le schede riepilogative
La riga di schede in alto è il tuo controllo rapido sullo stato di salute:
- Tasso di consegna: messaggi consegnati come quota degli accettati. La scheda indica Healthy sopra il 95 %. A quella soglia o al di sotto, qualcosa non riesce a raggiungere i dispositivi: numeri non validi, una finestra di assistenza scaduta o un problema di template. L'istogramma delle cause di fallimento (vedi Tasso di fallimento e relative cause) indica quale.
- Tasso di fallimento: la quota di messaggi accettati terminata con stato failed. La scheda mostra il tuo tasso rispetto a un limite del 5 % con una barra di avanzamento; raggiungerlo porta la scheda a Risk. Un tasso di fallimento elevato e costante di solito indica problemi di qualità della lista, una finestra di assistenza clienti scaduta o un limite di frequenza Meta.
- Accettati: il conteggio grezzo dei messaggi accettati nell'intervallo, con il numero consegnato alla rete WhatsApp (sent).
Le soglie del 95 % e del 5 % sono i limiti che usiamo per colorare le schede. Sono volutamente conservativi: una scheda può indicare Healthy e avere comunque margine di miglioramento.
Consegna nel tempo
Il grafico di consegna traccia il volume accettato, consegnato e fallito nell'intervallo, così puoi individuare tendenze e picchi isolati: una campagna problematica, un'importazione di numeri andata male, un template che ha iniziato a essere rifiutato. La granularità segue l'intervallo (oraria per 24 ore, giornaliera per finestre più lunghe).
Tasso di fallimento e relative cause
Sotto il grafico di consegna nella pagina Metrics, una linea del tasso di fallimento traccia il tasso per bucket nell'intervallo, mentre la scheda riepilogativa Failure rate contiene il valore sull'intera finestra. Un istogramma suddivide i fallimenti per codice di errore normalizzato, classificato per conteggio con la quota di ciascun codice sui messaggi falliti. Le cause di fallimento di WhatsApp sono un insieme aperto, perciò l'istogramma elenca i codici effettivamente presenti nell'intervallo anziché una lista fissa; una barra in crescita su un codice ti indirizza direttamente alla soluzione.
Latenza di consegna
La tabella di latenza riporta due fasi ai percentili p50, p95 e p99:
- Processing: dall'accettazione del messaggio fino all'invio riuscito al provider WhatsApp. Un percentile lento qui richiede un'indagine sul percorso di invio, incluso l'invio al provider.
- Total: end-to-end, dall'accettazione del messaggio fino alla conferma di consegna al dispositivo del destinatario da parte di WhatsApp. La differenza tra Total e Processing è la rete WhatsApp e il dispositivo del destinatario, che non sono sotto il nostro controllo. Un telefono offline per un'ora allunga Total lasciando Processing invariato.
Usa p95/p99 per individuare i casi più lenti: una mediana sana con un p99 lento di solito indica un template o una destinazione in ritardo. La latenza è un valore sull'intera finestra; una fase o un percentile senza dati nell'intervallo mostra un segnaposto.
Suddivisioni
Il pannello Breakdowns suddivide gli stessi numeri di consegna in modo da isolare un problema alla sua origine:
- Per numero: il volume accettato, consegnato e fallito di ciascun numero business mittente con il relativo tasso di consegna, per confrontare i mittenti fianco a fianco.
- Per template: la stessa suddivisione per template, per individuare quello che sta abbassando un tasso.
- Per categoria di template: la stessa suddivisione per le categorie di template di Meta, il taglio che determina anche la tua spesa.
- Per tag: i tag che associ a un invio, il taglio più flessibile: tagga una campagna, un template o una variante di esperimento e confrontali direttamente.
- Per paese: la stessa suddivisione per paese di destinazione, per verificare se un problema di consegna segue un mercato anziché un mittente o un template. Un destinatario il cui paese non può essere determinato (un numero che sembra un numero di telefono ma non appartiene a nessun paese, o un intervallo internazionale come il numero verde) viene conteggiato sotto ZZ, lo stesso segnaposto che usa la suddivisione per paese di SMS. Gli invii di gruppo sono esclusi perché un gruppo può coprire più paesi e non ha una singola destinazione. La copertura storica per paese precedente al lancio di questa suddivisione può essere incompleta, con osservazioni di consegna o lettura senza conteggi accettati corrispondenti. Lo storico aggregato sopravvive alla finestra di dettaglio messaggi di 30 giorni; attendere 30 giorni non ripara quelle coorti più vecchie.
Ogni riga ha anche uno stato derivato (Healthy, Watching o Throttled) basato sui propri tassi di consegna e fallimento, così un numero o una categoria in difficoltà risalta senza che tu debba leggere ogni colonna. Ogni tab classifica le righe principali per l'intervallo; quando una dimensione ha più valori distinti di quanti ne entrino, il pannello riporta "Top N of M".
Accesso programmatico
Gli aggregati dietro questa pagina sono anche un'API pubblica. I metodi tipizzati sono disponibili negli SDK TypeScript, Python, PHP e Go sotto bird.whatsapp.stats, la CLI di bird li espone come bird whatsapp stats <verb> e un agente li raggiunge tramite gli strumenti MCP di whatsapp_stats_*. Schemi completi di richiesta e risposta sono nel riferimento API.
L'aggregato e la serie temporale
GET /v1/whatsapp/stats/summary restituisce una riga aggregata per la finestra: conteggi del ciclo di vita (accepted, sent, delivered, failed, rejected) con tassi di consegna e fallimento, engagement (read, read_rate) e percentili di latenza (p50, p95, p99) per tre fasi: processing, delivery e total. /daily e /hourly restituiscono gli stessi conteggi di ciclo di vita e lettura con una riga per giorno o ora di calendario, ciascuna con i propri percentili di latenza; solo i tassi (delivery_rate, failure_rate, read_rate) sono valori sull'intera finestra, leggili da /summary. Tutti e tre accettano un filtro per dimensione alla volta: template, category, tag o phone_number. Qui phone_number limita a un singolo mittente business, in formato E.164, non il contatto su cui filtra nel parametro deprecato phone_number di GET /v1/whatsapp/messages.
Il tasso di lettura è read / delivered, mentre i tassi di consegna e fallimento usano accepted. Un denominatore uguale a zero restituisce null, ovvero il tasso non può essere calcolato. Il tasso di lettura non è limitato al 100 %, quindi osservazioni di consegna mancanti possono produrre un valore più alto; si tratta di una lacuna nelle osservazioni da indagare, non della prova che abbia letto il messaggio un numero di persone superiore a quello dei destinatari.
I percentili di latenza usano campioni registrati. L'assenza di un campione di latenza di consegna non implica latenza zero, e la latenza totale può essere presente quando il timestamp intermedio di invio non era disponibile. Non fare la media di percentili finalizzati provenienti da bucket separati. Gli eventi riprodotti possono influenzare le distribuzioni di latenza anche quando i conteggi di messaggi distinti restano deduplicati.
Quando presente, data_as_of indica il grado di aggiornamento dell'aggregazione. Non garantisce che tutti i callback del provider siano arrivati o che la fatturazione sia stata regolata. Un valore di aggiornamento null significa che non era disponibile per quella risposta.
Scegliere la finestra
from e to accettano un giorno di calendario o un istante RFC 3339, ma le forme accettate variano per endpoint:
| Endpoint | Limiti | Finestra massima |
|---|---|---|
| /summary | Entrambi giorni di calendario, o entrambi istanti RFC 3339 | 365 giorni, o 720 ore con istanti |
| /daily | Solo giorni di calendario | 365 giorni |
| /hourly | Solo istanti RFC 3339 | 720 ore (30 giorni) |
Su /summary, mescolare un limite in giorni con uno in istanti restituisce 422. I limiti in istanti vengono arrotondati per difetto all'ora su /summary e /hourly, gli unici due che li accettano. Imposta timezone su un identificatore IANA per calcolare i confini di giorno e ora localmente anziché in UTC; una volta impostato, un offset UTC numerico come +05:45 in un limite istantaneo viene rifiutato. Aggiungi compare=previous_period a /summary per la finestra precedente di pari durata e la variazione rispetto ad essa.
Suddivisioni
Sei endpoint classificano gli stessi numeri di consegna per una dimensione, ciascuno già a dimensione singola quindi nessuno accetta un filtro: per numero, per template, per categoria di template, per tag e per codice di errore (solo messaggi falliti, raggruppati per causa di fallimento normalizzata). Le righe sono classificate per volume accettato (conteggio fallimenti per i codici di errore) e limitate a limit (default 50, massimo 200). Un invio senza valore per una dimensione è assente da quella suddivisione: un invio libero non risolve alcun template e un invio senza tag nessun tag. Un messaggio con più tag può comparire in più righe tag, quindi sommare quelle righe non restituisce il volume unico dello spazio di lavoro. Confronta una suddivisione con sé stessa nel tempo. Ogni riga tranne quella per codice di errore include anche i propri percentili latency. Un sesto endpoint, per paese, raggruppa gli stessi numeri per mercato di destinazione del destinatario; un destinatario il cui paese non può essere risolto viene conteggiato sotto ZZ e gli invii di gruppo sono assenti perché un invio può coprire più paesi.
Messaggi ricevuti
Quattro endpoint sotto /v1/whatsapp/stats/inbound/ coprono ciò che i tuoi numeri hanno ricevuto anziché inviato: riepilogo, giornaliero, orario e per numero di telefono. Ogni riga contiene solo un conteggio received e segue l'orario di occorrenza del messaggio in entrata. Un messaggio ricevuto non ha un ciclo di vita di consegna in uscita da suddividere ulteriormente. Sono annidati sotto bird.whatsapp.stats.inbound negli SDK e bird whatsapp stats inbound <verb> nella CLI.
Riconciliazione per messaggio
Gli endpoint di statistiche rispondono a domande aggregate; non sostituiscono le ricerche per messaggio. Per confermare cosa è successo a un singolo messaggio, consuma gli eventi webhook in tempo reale oppure scorri GET /v1/whatsapp/messages e l'endpoint eventi di ciascun messaggio, i cui filtri (stato, destinatario, tag, finestra temporale) coprono la maggior parte dei lavori di riconciliazione.
Passi successivi
- Analytics WhatsApp: collega le osservazioni sui messaggi ai risultati cliente confermati
- Log WhatsApp: la vista per messaggio dietro i numeri aggregati
- Eventi: il flusso del ciclo di vita per messaggio da cui derivano le metriche
- Invio di messaggi WhatsApp: categorie, tag e modello di costo per messaggio
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione