FAQ API WhatsApp

Installez le SDK, récupérez une clé API et appelez l'endpoint d'envoi avec un modèle pré-approuvé. Bird fournit des numéros d'expéditeur gérés, il n'y a donc aucune étape de provisionnement de numéro avant votre premier envoi.

Un seul endpoint d'envoi qui accepte un modèle ou du contenu libre, un catalogue de modèles pré-approuvés, des événements de livraison et d'accusé de lecture via l'API et les webhooks, une chronologie d'événements par message, des messages entrants et médias, des métriques de livraison agrégées, et des numéros d'expéditeur gérés par Bird pour votre premier envoi. Mêmes clés API et hôtes régionaux que Bird Email et SMS.

Cela signifie que Bird a accepté votre message et le livrera de manière asynchrone. Le 202 n'est pas une confirmation de livraison. La livraison, les accusés de lecture et les échecs arrivent ultérieurement sous forme d'événements que vous pouvez interroger ou recevoir via des webhooks.

Les deux. Un modèle peut atteindre n'importe qui à tout moment, c'est pourquoi c'est le seul moyen de démarrer une conversation. Le contenu libre atteint un contact dans la fenêtre de service client de 24 heures que son propre message ouvre, et uniquement depuis un numéro appartenant à votre workspace. Bird ne suit pas cette fenêtre pour vous : un envoi libre en dehors de celle-ci est accepté puis échoue avec service_window_expired.

Oui. Le message d'un contact arrive via le webhook whatsapp.received, apparaît dans le journal WhatsApp du tableau de bord et est comptabilisé dans l'onglet Entrant de la page Métriques. Les messages entrants vous parviennent uniquement sur vos propres numéros : les numéros gérés par Bird sont partagés entre les workspaces, donc un message envoyé à l'un d'eux n'est pas enregistré pour le vôtre.

Par message, en fonction de la catégorie du modèle (authentification, utilitaire ou marketing) et du pays du destinataire. La facturation intervient lorsque Bird accepte le message, et non lorsque le destinataire le lit.

Un tarif par message plus élevé facturé par Meta lorsque votre entreprise est située en dehors du pays du destinataire et que vous envoyez des modèles d'authentification. L'éligibilité commence après l'envoi de plus de 750 000 messages de type modèle d'authentification à des utilisateurs dans un même pays au cours d'une période glissante de 30 jours. L'emplacement principal de votre entreprise, défini dans Meta Business Manager, détermine quels envois sont concernés.

Les expéditeurs partagés paient toujours le tarif international pour les modèles d'authentification, quel que soit votre seuil de volume. Tous les numéros WhatsApp sont actuellement gérés par Bird, ce tarif s'applique donc aux envois d'authentification lorsque votre entreprise est située en dehors du pays du destinataire.

Les pages Utilisation et Dépenses du tableau de bord affichent vos coûts WhatsApp. Le journal des messages indique la catégorie et le coût de chaque message individuel une fois qu'il est tarifé.

Non. Chaque message WhatsApp est un appel API distinct à POST /v1/whatsapp/messages avec un seul destinataire. Pour envoyer à plusieurs destinataires, itérez sur l'endpoint d'envoi.

Le groupe de débit whatsapp_send s'applique à l'endpoint d'envoi. Chaque réponse contient un en-tête IETF RateLimit avec le quota restant et le délai de réinitialisation ; réglez votre cadence en fonction de celui-ci plutôt que d'un nombre codé en dur. Les forfaits payants augmentent le débit de base.

Oui, en tant que contenu libre. L'endpoint d'envoi prend en charge image, vidéo, audio, sticker, document et localisation en plus du texte. Comme tout envoi libre, chacun nécessite une fenêtre de service client de 24 heures ouverte et un numéro appartenant à votre workspace. Les paramètres de modèle restent quant à eux au format texte.

Une structure de message pré-approuvée enregistrée auprès de WhatsApp via Meta. Chaque modèle a un nom, une ou plusieurs langues, une catégorie (authentification, utilitaire ou marketing) et des variables de substitution que vous renseignez au moment de l'envoi. Bird fournit un catalogue géré que vous pouvez utiliser immédiatement, et vous pouvez créer vos propres modèles une fois que vous avez connecté un WhatsApp Business Account.

Meta examine et approuve chaque modèle, qu'il ait été soumis par Bird ou par vous. Un modèle peut être actif globalement tout en ayant des langues individuelles dans un état rejeté ou suspendu : vérifiez donc le statut par langue avant d'envoyer dans cette langue.

Authentification (codes à usage unique et flux de connexion), utilitaire (mises à jour de commande, notifications de compte) et marketing (promotions et offres). La catégorie détermine quel numéro d'expéditeur Bird sélectionne et comment le message est tarifé.

Transmettez un tableau components avec des paramètres body et button lors de l'envoi. Les paramètres peuvent être nommés (associés par une clé comme 'name') ou positionnels (associés par index). Les paramètres nommés sont plus sûrs lorsque l'ordre des variables d'un modèle peut changer.

Oui, sur la page Modèles du tableau de bord, une fois que votre workspace a connecté son propre WhatsApp Business Account. Le générateur couvre aujourd'hui le corps du texte dans une seule langue. La création via l'API publique n'est pas disponible, mais l'endpoint d'envoi accepte tout modèle que votre workspace peut envoyer, qu'il soit géré ou le vôtre.

Non. Bird fournit des numéros d'expéditeur gérés. Les modèles d'authentification sont envoyés depuis un numéro dédié, et les modèles utilitaires et marketing partagent un numéro de notification. La page Numéros du tableau de bord liste les numéros disponibles pour votre espace de travail.

Oui, et en connecter un est ce qui vous permet d'envoyer en tant que votre propre marque : vos propres modèles, du contenu libre dans une fenêtre de service client ouverte et des messages entrants. Les numéros gérés par Bird sont partagés entre les workspaces et ne prennent en charge que les modèles gérés : considérez-les comme le moyen sans configuration pour un premier envoi, et non comme la solution définitive.

Pour un modèle géré, selon sa catégorie : l'authentification utilise un numéro d'expéditeur dédié, tandis que les catégories utilitaire et marketing partagent un numéro de notification. Tout le reste spécifie son propre expéditeur dans le champ from, qui doit être un numéro appartenant à votre workspace, et un modèle que vous avez créé doit être rattaché au même WhatsApp Business Account que ce numéro.

Envoyez un POST vers /v1/whatsapp/messages avec le numéro de téléphone E.164 du destinataire, un slug de modèle et les valeurs des variables du modèle. Bird valide la requête, renvoie un 202 avec un identifiant de message et effectue la livraison de manière asynchrone.

Transmettez un en-tête Idempotency-Key et une requête retentée renverra le résultat original au lieu d'envoyer le message une seconde fois. Sans cet en-tête, une nouvelle tentative est traitée comme un nouveau message et le destinataire reçoit un doublon.

Oui. Les tags sont jusqu'à 20 libellés structurés que vous pouvez utiliser pour filtrer et regrouper dans le journal des messages et les métriques. Les métadonnées sont du JSON arbitraire (jusqu'à 2 Ko) renvoyé avec le message et ses événements, utile pour corréler les envois avec vos propres systèmes.

Chaque changement d'état déclenche un événement webhook : accepted, sent, delivered, read, failed ou rejected. Vous pouvez également interroger la chronologie des événements du message via l'API. Un statut delivered signifie que WhatsApp a confirmé que l'appareil du destinataire l'a reçu.

Six événements de cycle de vie : whatsapp.accepted (Bird l'a mis en file d'attente), whatsapp.sent (soumis à WhatsApp), whatsapp.delivered (l'appareil du destinataire l'a reçu), whatsapp.read (le destinataire l'a ouvert), whatsapp.failed (WhatsApp l'a refusé après soumission) et whatsapp.rejected (Bird l'a refusé avant soumission, non facturé).

Non. Un événement de lecture signifie que le destinataire a ouvert le message, mais le statut du message reste à « livré ». La lecture est signalée séparément sous forme d'horodatage et d'événement whatsapp.read, et non comme un changement de statut.

« Rejected » signifie que Bird a refusé le message avant de le soumettre à WhatsApp, donc vous n'êtes pas facturé. « Failed » signifie que Bird l'a soumis mais WhatsApp a refusé la livraison. Les deux contiennent un objet d'erreur avec un code, une description et un code d'erreur Meta le cas échéant.

Deux méthodes : récupérer la chronologie d'un message spécifique avec GET /v1/whatsapp/messages/{id}/events, ou abonner un endpoint webhook aux types d'événements whatsapp.* pour les recevoir en temps réel. La page Messages du tableau de bord affiche également la chronologie des événements par message.

Sur la page Métriques de l'application WhatsApp du tableau de bord. Elle affiche le taux de livraison, le taux d'échec, le volume accepté et la latence de livraison (traitement et de bout en bout) pour l'ensemble des envois de votre espace de travail.

Par numéro d'expéditeur, par modèle, par catégorie de modèle et par tag. Un taux d'échec qui semble correct dans l'ensemble s'avère souvent provenir d'un seul modèle ou d'un seul tag concentrant la majorité des erreurs.

Deux : la latence de traitement (côté Bird, de l'acceptation à la soumission) et la latence totale (de bout en bout, de l'acceptation à l'accusé de réception). Les deux sont reportées aux percentiles p50, p95 et p99.

Pas encore pour les statistiques agrégées. Vous pouvez construire vos propres agrégations à partir des événements webhook ou de l'API de liste de messages, qui contient le statut et la chronologie des événements pour chaque message.

WhatsApp fournit un chiffrement de bout en bout pour les messages entre l'expéditeur et l'appareil du destinataire. Votre appel API vers Bird se fait via HTTPS, et les événements webhook que Bird vous envoie sont signés par HMAC.

Chaque événement est signé par HMAC. Vérifiez la signature avec le secret de votre endpoint avant de traiter le contenu, et effectuez une rotation de ce secret depuis le tableau de bord si nécessaire.

Dans la région où votre organisation est hébergée, soit us1 soit eu1. Votre clé API porte cette information dans son préfixe (bk_us1_, bk_eu1_), ce qui permet aux SDK et au CLI de sélectionner automatiquement le bon endpoint sans configuration de votre part.

Uniquement ce que vous lui autorisez. Une clé contient une liste de scopes, chacun en lecture ou écriture, de sorte qu'une clé qui envoie des messages WhatsApp ne peut ni gérer vos numéros ni lire un autre canal. Les clés prennent également en charge les listes d'adresses IP autorisées et la rotation sécurisée avec une période de grâce configurable.

Les certifications et la documentation de sécurité sont disponibles sur trust.bird.com. L'accord de traitement des données, la déclaration de confidentialité et la politique d'utilisation acceptable se trouvent sur bird.com/legal. Pour un questionnaire fournisseur, votre équipe de compte Bird s'en charge.