Bird
Sign inGet started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

Créer des templates WhatsApp

Le catalogue géré de Bird couvre les cas courants, mais un template rédigé dans vos propres mots doit être créé sur un WhatsApp Business Account que vous avez connecté. Cette page traite de la création ; Templates WhatsApp couvre la consultation et l'envoi de ce qui existe déjà.
Trois éléments structurent l'ensemble du flux :
  • Un template contient des versions, et une version contient une entrée par langue. Ce qui est réellement envoyé est une langue d'une version, pas le template.
  • Le contenu est écrit dans un brouillon. Un template a au plus un brouillon ouvert, et rien de ce qu'il contient n'atteint WhatsApp tant que vous ne le soumettez pas.
  • L'approbation revient par langue. Une langue peut être approuvée tandis qu'une autre sur la même version est rejetée.

Avant de commencer

Vous avez besoin d'un numéro qui vous appartient connecté : c'est ce qui donne à votre espace de travail un WhatsApp Business Account sur lequel créer. Un compte que vous n'avez pas connecté est refusé, tout comme la modification d'un template bird_ intégré de Bird : ceux-ci résident sur le propre compte de Bird, dupliquez-en donc un sur le vôtre.
La création d'un template authentication nécessite en plus une entreprise vérifiée ; utility et marketing non. Consultez Authentication templates pour cette condition.
Créez un template dans le tableau de bord sous WhatsApp > Templates, avec le bird CLI, ou via le serveur MCP. Le tableau de bord suit les mêmes étapes décrites sur cette page ; les exemples plus bas utilisent le CLI.

Dans le tableau de bord

New template propose deux points d'entrée. Start with a template ouvre la galerie, le chemin le plus rapide : choisissez-en un qui dit déjà presque ce dont vous avez besoin, y compris un de Bird, et la copie arrive sur votre compte sous forme de brouillon ouvert.
La galerie de templates dans le tableau de bord Bird : une grille de cartes de templates, chacune affichant un aperçu de son message et étiquetée avec son nom, slug, statut, catégorie et langues, accompagnée de filtres par source de template, catégorie et langue
Start from scratch demande la catégorie, un nom et une langue par défaut avant d'ouvrir l'éditeur. Un template marketing demande aussi un type de message. Le nom devient le slug, et le slug et la catégorie sont les deux choix que vous ne pouvez plus modifier ensuite.
L'étape Create a new template dans le tableau de bord Bird : des tuiles de catégorie Marketing, Utility et Authentication au-dessus d'un champ Name et d'un sélecteur Default language, avec un bouton Create template
L'éditeur rédige une langue à la fois : la barre latérale liste les langues du template avec l'état d'examen de chacune, la colonne centrale contient le contenu, et l'aperçu téléphone affiche le message avec les valeurs d'exemple substituées.
L'éditeur de templates dans le tableau de bord Bird pour le template utility Order update : English marqué Approved à côté de Dutch dans la barre latérale des langues, et un aperçu téléphone du message rendu avec ses boutons Track order et Contact support
L'éditeur change de forme selon le template. Un carousel ajoute un onglet par carte à côté du message, et chaque carte doit reproduire la structure de la carte 1 : le même format d'en-tête et les mêmes boutons dans le même ordre.
L'éditeur de templates dans le tableau de bord Bird pour un template marketing carousel : des onglets Message, Card 1, Card 2 et Card 3 au-dessus du corps du message, avec une section Variable samples en dessous, à côté d'un aperçu téléphone montrant le message suivi de cartes images défilantes chacune dotée d'un bouton Show me
Un template authentication n'a pas d'éditeur de message. WhatsApp rédige le texte, donc l'éditeur propose uniquement les deux paramètres à partir desquels il l'écrit : Add security recommendation et Code expiration (minutes).
L'éditeur de templates dans le tableau de bord Bird pour un template authentication : un panneau Authentication settings avec un interrupteur Add security recommendation et un champ Code expiration (minutes), à côté d'un aperçu téléphone du message de code de vérification écrit par WhatsApp, avec son bouton Copy code
Save as draft conserve votre travail sans contacter WhatsApp. Submit for review fige la version et l'envoie à WhatsApp. La soumission du CLI, ci-dessous, effectue le même gel.

Deux façons de commencer

Dupliquer un template existant

Un duplicata reprend le contenu de la source sous forme de brouillon ouvert et n'appelle WhatsApp aucune fois : rien n'est soumis tant que vous ne le décidez pas. Deux points méritent d'être connus avant de faire une copie :
  • La catégorie est héritée et ne peut pas être changée. Si vous avez besoin d'une catégorie différente, partez de zéro.
  • Vous pouvez réduire les langues, jamais en ajouter. Un template du catalogue proposant 70 langues n'a pas à devenir 70 langues chez vous : choisissez le sous-ensemble que vous maintiendrez réellement. Demander une langue que la source ne contient pas est refusé avec E15060, et la réponse indique lesquelles ne correspondaient pas. Ajoutez d'autres langues à la copie ensuite.
Le sous-ensemble de langues est un tableau, il passe donc dans un corps de requête plutôt que dans une option de ligne de commande :
Exemple de code
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
Exemple de code
{
  "waba": "102290129340398",
  "slug": "acme_order_update",
  "include_languages": ["en", "es-ES"],
  "default_language": "en"
}
Omettez include_languages et la copie reprend toutes les langues de la source. Omettez default_language et la copie conserve la langue par défaut de la source lorsque votre sous-ensemble la contient encore ; sinon elle prend la première des langues de la copie par tag canonique, qui n'est pas nécessairement la première que vous avez listée, donc définissez-la explicitement si c'est important.

Partir de zéro

La création d'un template nécessite un slug, un compte, une catégorie et une langue par défaut :
Exemple de code
bird whatsapp templates create order_update \
  --waba 102290129340398 \
  --category utility \
  --default-language en
Le slug et la catégorie sont tous deux permanents. WhatsApp dérive son propre nom de template à partir du slug, et ni celui-ci ni la catégorie ne peuvent être modifiés ensuite ; en changer signifie un nouveau template. Le préfixe bird_ est réservé au catalogue de Bird. La catégorie que vous choisissez n'est pas nécessairement celle qui détermine le prix d'un envoi : Meta applique sa propre catégorie par langue et peut la modifier, et le prix suit celle de Meta.

Rédiger chaque langue

Ouvrez le brouillon, puis rédigez une langue à la fois :
Exemple de code
bird whatsapp templates versions create order_update
bird whatsapp templates versions languages set order_update <version-id> en --body-file en.json
Ouvrir un brouillon peut être répété sans risque : un template n'en a qu'un seul, donc cette opération renvoie le brouillon ouvert plutôt que d'en créer un second. Le template le signale également comme draft_version_id.
L'écriture d'une langue remplace la langue, elle ne fusionne pas avec. Le fichier contient l'intégralité du components de cette langue à chaque fois, donc lisez la langue d'abord et réécrivez-la en entier ; envoyer uniquement le bloc que vous avez modifié supprime le reste.
Chaque variable a besoin d'une valeur d'exemple. WhatsApp examine le message rempli plutôt que le template, donc un bloc avec des espaces réservés et sans paramètres d'exemple est refusé à la soumission, pas à l'écriture.

Vérifier, puis soumettre

Validez avant de figer quoi que ce soit. Une soumission en mode validation uniquement exécute tous les contrôles sur toutes les langues et signale chaque problème en une seule passe, sans rien envoyer à WhatsApp :
Exemple de code
bird whatsapp templates versions submit order_update <version-id> --validate-only
Lisez valid et errors ; chaque erreur nomme la langue, le champ et le code avec lequel une vraie soumission échouerait. Puis soumettez réellement en retirant le flag. Cela fige le brouillon en une version immuable et répond 202. Utilisez une clé d'idempotence différente pour la vérification et la soumission, car réutiliser une clé avec un corps modifié est rejeté.
Seules les langues dont le contenu diffère de leur copie approuvée sont envoyées à WhatsApp. Une langue qui correspond déjà conserve son approbation, donc une soumission sans changement se conclut immédiatement sans rien à interroger. Aucun brouillon de remplacement ne s'ouvre ensuite : le prochain cycle de modifications commence par la création d'un nouveau brouillon.
Une validation réussie en mode validation uniquement ne prédit pas la décision de WhatsApp. WhatsApp n'offre aucun moyen de demander à l'avance, donc du contenu ayant passé tous les contrôles locaux peut quand même être refusé.

Suivre l'examen

L'approbation arrive plus tard et par langue. Le pending_version_id du template reste défini tant qu'une langue est non résolue, et la liste par langue porte chaque verdict :
  • approved envoie. available_languages sur le template correspond exactement à ce qu'un envoi peut résoudre en ce moment.
  • rejected, submit_failed, paused nécessitent une modification sur un nouveau brouillon. WhatsApp accepte une modification d'une langue mise en pause, et c'est la resoumission qui la réactive.
  • disabled, limit_exceeded, in_appeal refusent toute modification ; ils nécessitent seulement une relecture jusqu'à ce que WhatsApp les déplace.
Le status propre du template est un agrégat : active signifie qu'au moins une langue est envoyable, pas toutes.

Envoyer ce que vous avez créé

Un template créé par vous s'envoie via le même endpoint que tout autre, avec une différence par rapport au catalogue de Bird : vous devez nommer from, et il doit s'agir d'un numéro sur le même WhatsApp Business Account que le template. Un expéditeur sur un compte différent est refusé 422 E15023 avant toute facturation.
Un template peut exiger une langue du destinataire via language_source_required. Sinon, on_missing_language détermine si la résolution échoue ou peut utiliser une langue de base approuvée ou default_language. Testez la politique configurée par rapport aux available_languages approuvées du template ; une langue par défaut non approuvée n'est pas envoyable. Les valeurs que vous fournissez doivent remplir les espaces réservés de la langue effectivement résolue, donc lisez le contenu de cette langue avant l'envoi. Consultez Envoi de messages WhatsApp pour le payload complet.

Points d'attention

  • La version la plus récente n'est pas celle qui envoie. Une liste de versions est triée de la plus récente à la plus ancienne et inclut tout brouillon ouvert, donc la première ligne est souvent un brouillon ou une version encore en cours d'examen. Le template nomme la version en service comme live_version_id ; un template sans version active ne peut pas du tout être envoyé.
  • Une langue en cours d'examen refuse l'écriture. WhatsApp la bloque jusqu'à la fin de l'examen, donc une modification pendant pending échoue au lieu d'être mise en file d'attente.
  • Une ligne de liste ne contient pas de contenu. Lister les templates les trouve et affiche l'état du cycle de vie ; lire ce qu'un template dit réellement nécessite une lecture de version.
  • La suppression est irréversible. Supprimer une langue, supprimer un brouillon et supprimer un template nécessitent tous une confirmation explicite, et supprimer un template arrête tous les envois par ce slug.

Étapes suivantes

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptWhat is a WhatsApp message template?Explorer la fonctionnalitéWhatsApp templatesSuivre le parcours d'apprentissageBuild your first integration
Essayez la pratique et obtenez un guide d'implémentation