Métriques WhatsApp
La page Metrics du tableau de bord Bird montre comment se comporte votre canal WhatsApp : quelle part atteint l'appareil du destinataire, si votre taux d'échec dérive, et à quelle vitesse tout transite. Ce guide parcourt la page, explique chaque chiffre et indique quand agir.
Les métriques sont la vue agrégée de tout ce que votre espace de travail envoie. Pour le cycle de vie d'un message individuel (est-ce que ce numéro l'a reçu, et quand), consultez le journal WhatsApp et les événements.
Lire vos métriques
La page Metrics se trouve sous WhatsApp → Metrics dans le tableau de bord Bird ; elle est visible par les membres de l'espace de travail disposant des permissions WhatsApp read et Analytics read. Chaque chiffre respecte le sélecteur de plage (dernières 24 heures, 7, 30 ou 90 jours). Les nouveaux événements apparaissent après agrégation et réplication : la période la plus récente est donc provisoire.
Les taux sortants utilisent l'heure d'acceptation de chaque message. Un accusé de réception arrivé aujourd'hui pour un message accepté hier est comptabilisé sur la journée d'hier, aux côtés du accepted propre à ce message. Chaque plage suit donc les messages acceptés dans celle-ci au fur et à mesure que les observations arrivent. Les heures récentes peuvent sous-estimer delivered tant que des accusés sont encore en transit. accepted est le dénominateur des cartes de taux de livraison et d'échec.
Les compteurs représentent des messages distincts pour chaque événement observé et peuvent être approximatifs à grande échelle. Ils ne forment pas un entonnoir obligatoire : un accusé de lecture peut exister sans accusé de livraison, et des observations manquantes peuvent laisser des écarts entre les étapes. Les statistiques de groupe comptent aussi les messages, pas les destinataires ; la première livraison observée à un participant peut incrémenter le compteur de livraisons avant que tous les membres du groupe aient reçu le message.
Les tuiles récapitulatives
La rangée de tuiles en haut de page est votre bilan de santé en un coup d'œil :
- Delivery rate : messages livrés rapportés aux messages acceptés. La tuile affiche Healthy au-dessus de 95 %. À 95 % ou en dessous, quelque chose empêche les messages d'atteindre les appareils : numéros invalides, fenêtre de service expirée ou problème de template. L'histogramme des causes d'échec (voir Taux d'échec et ses causes) vous indique laquelle.
- Failure rate : la part des messages acceptés qui se sont terminés failed. La tuile affiche votre taux par rapport à une limite de 5 % avec une barre de progression ; l'atteindre fait basculer la tuile en Risk. Un taux d'échec élevé et soutenu pointe généralement vers la qualité de la liste, une fenêtre de service client expirée ou une limitation de débit Meta.
- Accepted : le nombre brut de messages acceptés dans la plage, avec le nombre transmis au réseau WhatsApp (sent).
Les seuils de 95 % et 5 % sont les garde-fous utilisés pour colorer les tuiles. Ils sont volontairement conservateurs ; une tuile peut afficher Healthy tout en ayant une marge d'amélioration.
Livraison dans le temps
Le graphique de livraison trace les volumes accepted, delivered et failed sur la plage pour repérer les tendances et les pics ponctuels : une mauvaise campagne, un import de liste de numéros mal passé, un template qui commence à être rejeté. La granularité suit la plage (horaire sur 24 heures, quotidienne sur les fenêtres plus longues).
Taux d'échec et ses causes
Sous le graphique de livraison sur la page Metrics, une courbe trace le taux d'échec par intervalle sur la plage, tandis que la tuile récapitulative Failure rate affiche le chiffre sur la fenêtre entière. Un histogramme ventile les échecs par code d'erreur normalisé, classé par nombre avec la part de chaque code dans les messages échoués. Les raisons d'échec de WhatsApp forment un ensemble ouvert : l'histogramme liste les codes effectivement survenus dans la plage plutôt qu'une liste fixe ; une barre en hausse sur un code vous oriente directement vers la correction.
Latence de livraison
Le tableau de latence rapporte deux étapes aux percentiles p50, p95 et p99 :
- Processing : de l'acceptation du message jusqu'à la soumission réussie au fournisseur WhatsApp. Un percentile lent ici appelle une investigation du chemin d'envoi, y compris la soumission au fournisseur.
- Total : de bout en bout, de l'acceptation du message jusqu'à la confirmation de livraison à l'appareil du destinataire par WhatsApp. L'écart entre Total et Processing correspond au réseau WhatsApp et à l'appareil du destinataire, que nous ne contrôlons pas. Un téléphone hors ligne pendant une heure allonge Total sans modifier Processing.
Utilisez p95/p99 pour repérer les cas les plus lents : une médiane saine avec un p99 lent pointe généralement vers un template ou une destination en retard. La latence est un chiffre sur la fenêtre entière ; une étape ou un percentile sans données pour la plage affiche un indicateur de remplacement.
Ventilations
Le panneau Breakdowns découpe les mêmes chiffres de livraison pour isoler un problème à sa source :
- By number : volume accepté, livré et échoué de chaque numéro professionnel émetteur avec son taux de livraison, pour comparer les émetteurs côte à côte.
- By template : la même ventilation par template, pour trouver celui qui fait baisser un taux.
- By template category : la même ventilation selon les catégories de templates Meta, le découpage qui détermine aussi vos coûts.
- By tag : les tags que vous associez à un envoi, le découpage le plus flexible : taguez une campagne, un template ou une variante d'expérience et comparez-les directement.
- By country : la même ventilation par pays de destination, pour voir si un problème de livraison suit un marché plutôt qu'un émetteur ou un template. Un destinataire dont le pays ne peut pas être déterminé (un numéro qui ressemble à un numéro de téléphone mais n'appartient à aucun pays, ou une plage internationale comme les numéros verts) est comptabilisé sous ZZ, le même indicateur de remplacement qu'utilise la ventilation par pays de SMS. Les envois de groupe sont exclus parce qu'un groupe peut couvrir plusieurs pays et n'a pas de destination unique. La couverture historique par pays antérieure à la mise en place de cette ventilation peut être incomplète, avec des observations de livraison ou de lecture sans compteurs d'acceptation correspondants. L'historique agrégé survit à la fenêtre de détail des messages de 30 jours ; attendre 30 jours ne répare pas ces cohortes plus anciennes.
Chaque ligne reçoit aussi un statut dérivé (Healthy, Watching ou Throttled) basé sur ses propres taux de livraison et d'échec, de sorte qu'un numéro ou une catégorie en difficulté ressort sans que vous lisiez chaque colonne. Chaque onglet classe les premières lignes pour la plage ; quand une dimension a plus de valeurs distinctes que l'affichage ne le permet, le panneau indique "Top N of M".
Accès programmatique
Les agrégats derrière cette page sont aussi une API publique. Des méthodes typées sont disponibles dans les SDK TypeScript, Python, PHP et Go sous bird.whatsapp.stats, l'interface CLI bird les expose en tant que bird whatsapp stats <verb>, et un agent y accède via les outils MCP whatsapp_stats_*. Les schémas complets de requête et de réponse se trouvent dans la référence API.
L'agrégat et la série temporelle
GET /v1/whatsapp/stats/summary renvoie une ligne agrégée pour la fenêtre : compteurs de cycle de vie (accepted, sent, delivered, failed, rejected) avec taux de livraison et d'échec, engagement (read, read_rate), et percentiles de latence (p50, p95, p99) pour trois étapes : processing, delivery et total. /daily et /hourly renvoient les mêmes compteurs de cycle de vie et de lecture à raison d'une ligne par jour ou heure calendaire, chacune avec ses propres percentiles de latence ; seuls les taux (delivery_rate, failure_rate, read_rate) sont des chiffres sur la fenêtre entière, lisez-les depuis /summary. Les trois acceptent un filtre de dimension à la fois : template, category, tag ou phone_number. Ici, phone_number restreint à un seul émetteur professionnel, au format E.164, et non le contact filtré par le paramètre déprécié phone_number de GET /v1/whatsapp/messages.
Le taux de lecture est read / delivered, tandis que les taux de livraison et d'échec utilisent accepted. Un dénominateur à zéro renvoie null, ce qui signifie que le taux ne peut pas être calculé. Le taux de lecture n'est pas plafonné à 100 %, donc des observations de livraison manquantes peuvent produire une valeur supérieure ; il s'agit d'un écart d'observation à investiguer, pas d'une preuve que plus de 100 % des destinataires ont lu le message.
Les percentiles de latence utilisent des échantillons enregistrés. L'absence d'un échantillon de latence de livraison n'implique pas une latence nulle, et la latence totale peut être présente lorsque l'horodatage intermédiaire d'envoi n'était pas disponible. Ne faites pas la moyenne de percentiles finalisés provenant d'intervalles distincts. Des événements rejoués peuvent affecter les distributions de latence même lorsque les compteurs de messages distincts restent dédupliqués.
Lorsqu'il est présent, data_as_of indique la fraîcheur de l'agrégation. Il ne prouve pas que tous les callbacks du fournisseur sont arrivés ni que la facturation est finalisée. Une valeur de fraîcheur null signifie qu'elle n'était pas disponible pour cette réponse.
Choisir la fenêtre
from et to acceptent un jour calendaire ou un instant RFC 3339, mais les formes acceptées diffèrent selon le point de terminaison :
| Point de terminaison | Bornes | Fenêtre maximale |
|---|---|---|
| /summary | Les deux en jours calendaires, ou les deux en instants RFC 3339 | 365 jours, ou 720 heures en instants |
| /daily | Jours calendaires uniquement | 365 jours |
| /hourly | Instants RFC 3339 uniquement | 720 heures (30 jours) |
Sur /summary, mélanger une borne en jour avec une borne en instant renvoie 422. Les bornes en instant sont arrondies à l'heure inférieure sur /summary et /hourly, les deux seuls qui les acceptent. Définissez timezone avec un identifiant IANA pour calculer les limites de jour et d'heure localement au lieu d'UTC ; une fois défini, un décalage UTC numérique tel que +05:45 dans une borne en instant est rejeté. Ajoutez compare=previous_period à /summary pour obtenir la fenêtre précédente de même durée et la variation par rapport à celle-ci.
Ventilations
Six points de terminaison classent les mêmes chiffres de livraison par une dimension, chacun étant déjà mono-dimension et n'acceptant donc aucun filtre : par numéro, par template, par catégorie de template, par tag et par code d'erreur (messages échoués uniquement, groupés par raison d'échec normalisée). Les lignes sont classées par volume accepté (nombre d'échecs pour les codes d'erreur) et plafonnées à limit (par défaut 50, maximum 200). Un envoi sans valeur pour une dimension est absent de cette ventilation : un envoi libre ne résout aucun template, et un envoi sans tag aucun tag. Un message avec plusieurs tags peut apparaître dans plusieurs lignes de tag : additionner ces lignes ne donne pas le volume unique de l'espace de travail. Comparez une ventilation avec elle-même dans le temps. Chaque ligne sauf celle d'un code d'erreur porte aussi ses propres percentiles latency. Un sixième, par pays, groupe les mêmes chiffres par marché de destination du destinataire ; un destinataire dont le pays ne peut pas être résolu est comptabilisé sous ZZ, et les envois de groupe sont absents parce qu'un envoi peut couvrir plusieurs pays.
Messages reçus
Quatre points de terminaison sous /v1/whatsapp/stats/inbound/ couvrent ce que vos numéros ont reçu plutôt qu'envoyé : résumé, quotidien, horaire et par numéro de téléphone. Chaque ligne ne porte qu'un compteur received et suit l'heure d'occurrence du message entrant. Un message reçu n'a pas de cycle de vie de livraison sortante à ventiler davantage. Ils sont imbriqués sous bird.whatsapp.stats.inbound dans les SDK et bird whatsapp stats inbound <verb> dans l'interface CLI.
Rapprochement par message
Les points de terminaison de statistiques répondent à des questions agrégées ; ils ne remplacent pas les consultations par message. Pour confirmer ce qui est arrivé à un message, consommez les événements webhook en temps réel, ou parcourez GET /v1/whatsapp/messages et le point de terminaison événements de chaque message, dont les filtres (statut, destinataire, tag, fenêtre temporelle) couvrent la plupart des tâches de rapprochement.
Étapes suivantes
- Analytique WhatsApp : relier les observations de messages aux résultats clients confirmés
- Journal WhatsApp : la vue par message derrière les chiffres agrégés
- Événements : le flux de cycle de vie par message dont les métriques sont dérivées
- Envoyer des messages WhatsApp : catégories, tags et modèle de coût par message
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channelComprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builderExplorer la fonctionnalitéWhatsApp
Essayez la pratique et obtenez un guide d'implémentation