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.

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.

Un message de service, c'est-à-dire l'un des neuf types ci-dessus, n'est livré qu'à l'intérieur d'une fenêtre de service client de 24 heures ouverte. 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.

Un message de service envoyé dans une fenêtre 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é ; il atteint le contact indépendamment de la fenêtre, et sa réponse la rouvre. Une fenêtre qui se ferme entre l'acceptation et l'envoi échoue quand même, mais de façon asynchrone : le message atteint failed avec service_window_expired sur last_error.

La vérification à l'acceptation fonctionne au mieux, sans garantie : la porte s'ouvre par défaut, donc un cache manquant ou une erreur de lecture laisse passer l'envoi au lieu de le bloquer. Un 202 ne prouve donc pas que la fenêtre était ouverte au moment de l'envoi ; le signal définitif est le statut du message lui-même, pas la réponse d'acceptation.

Chaque message de service requiert aussi from, un numéro appartenant à votre espace de travail. Les numéros gérés par Bird ne le supportent pas, donc 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.

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 :

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.

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é.

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.