Messages de service WhatsApp

Un message de service est tout ce que vous envoyez en dehors d'un template pré-approuvé : le contenu libre qu'une entreprise envoie dans une conversation ouverte. POST /v1/whatsapp/messages transporte exactement l'un des neuf types de contenu de message de service, ou un template. Cette page couvre ce que les neuf types ont en commun ; la page de chaque type détaille sa structure réseau et ses propres limites.

Les types de contenu

Une requête transporte exactement l'un des champs template ou l'un de ces neuf champs. Une requête qui n'en contient aucun, ou qui en contient plus d'un, est refusée avec une 422.

La fenêtre de service client

Un message de service, c'est-à-dire l'un des neuf types ci-dessus, n'est livré qu'à l'intérieur de la fenêtre de service client de 24 heures ouverte de Meta. Le contact ouvre cette fenêtre en envoyant un message ou en appelant votre numéro professionnel, et chaque nouveau message de sa part la réinitialise à 24 heures.

Pour sa vérification à l'acceptation, l'API Bird suit la fenêtre uniquement à partir des messages entrants. Un appel peut ouvrir la fenêtre de Meta alors que celle suivie par Bird reste fermée. Avant d'envoyer du contenu libre via Bird, demandez au contact d'envoyer un message au numéro professionnel connecté que vous utiliserez comme from. Pour répondre, utilisez le champ from du message entrant comme destinataire et son champ to comme expéditeur. Si le message entrant ne contient qu'un bsuid, adressez la réponse à cet identifiant ; un numéro de téléphone obtenu ailleurs ne partage pas sa fenêtre.

Un message de service envoyé alors que la fenêtre suivie par Bird est fermée est refusé immédiatement : la requête renvoie une 422 E15044 WhatsAppServiceWindowClosed, et rien n'est créé ni facturé. Envoyez plutôt un template approuvé et éligible ; les templates ne nécessitent pas de fenêtre ouverte, et la réponse du contact la rouvre. Si la fenêtre se ferme entre l'acceptation et l'envoi, le message échoue aussi, mais de façon asynchrone : il atteint failed avec service_window_expired sur last_error.

Si l'API ne peut pas terminer sa vérification de la fenêtre de service, la requête peut tout de même être acceptée pour que WhatsApp l'évalue lors de l'envoi. Une vérification terminée qui ne trouve aucune fenêtre ouverte refuse la requête. Un 202 confirme l'acceptation ; consultez le statut du message pour connaître le résultat de la livraison.

Chaque message de service exige aussi from, un numéro que votre espace de travail possède. Les numéros gérés par Bird ne peuvent pas le porter : un message de service nécessite d'abord un numéro à vous connecté ; voir Configuration du numéro de téléphone.

Voir la fenêtre de service client pour le cycle de vie complet : comment la fenêtre s'ouvre, ce qui la réinitialise et comment elle est suivie.

Envoi de médias par URL

image, video, audio, sticker et document prennent tous un url pointant vers un fichier que WhatsApp récupère au moment de l'envoi, et non un fichier que vous téléchargez vers Bird. Bird vérifie la forme de l'URL à l'acceptation, avant toute mise en file d'attente :

• Non vide et analysable, avec un hôte et sans espace brut
• Le schéma est https

Une URL http est rejetée avec une 422 à l'acceptation, même si WhatsApp la récupérerait sans problème. C'est la politique de Bird, pas une limite imposée par WhatsApp.

Bird ne vérifie ni la taille du fichier, ni son type MIME, ni l'accessibilité de l'URL. WhatsApp récupère l'URL au moment de l'envoi du message, donc une URL signée doit rester valide au-delà de cet instant, pas seulement au moment où vous envoyez la requête ; une URL privée ou expirée échoue lorsque WhatsApp tente de la récupérer. WhatsApp met aussi en cache une URL récupérée pendant environ 10 minutes, donc renvoyer la même URL dans cet intervalle réutilise le premier téléchargement au lieu de récupérer à nouveau.

Quand le média échoue

Un envoi de média suit le même chemin asynchrone que tout message WhatsApp : Bird renvoie 202 et accepte le message, puis WhatsApp récupère l'URL au moment de l'envoi. Si cette récupération échoue, le message atteint failed avec media_rejected sur last_error, qui correspond à 131053 de Meta en dessous.

media_rejected est un code générique couvrant aussi bien un fichier trop volumineux, un 404, une erreur DNS qu'un type MIME incorrect ; Bird ne le détaille pas davantage, donc n'attendez pas un code distinct par cause.

Un envoi de média échoué de façon asynchrone est quand même facturé. La facturation intervient quand Bird traite l'envoi accepté, avant même que WhatsApp ne récupère l'URL, et il n'existe aucun mécanisme de remboursement une fois le montant débité. Prévoyez en conséquence : un message qui échoue plus tard dans media_rejected a déjà coûté autant qu'un message livré.

Lire ce qu'un contact a envoyé

Un message entrant transporte l'un des mêmes neuf types, donc le champ que vous lisez correspond au type utilisé par le contact. Les fiches contact se lisent sur le même champ contact_cards, que le contact en ait partagé une ou que vous en ayez envoyé une. Recevoir des messages WhatsApp couvre la lecture des messages entrants via le API, la récupération des médias envoyés par un contact et le webhook whatsapp.received.

Étapes suivantes

• Envoyer des messages WhatsApp : l'enveloppe de requête, le modèle 202 et les réessais sûrs
• Messages interactifs : les six types sur lesquels un destinataire peut appuyer
• Recevoir des messages WhatsApp : messages entrants, médias et webhook whatsapp.received
• Templates WhatsApp : les messages que vous pouvez encore envoyer une fois la fenêtre fermée