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

Modèles WhatsApp

Les envois WhatsApp à l’initiative de l’entreprise utilisent un modèle préapprouvé. Un modèle contient du texte fixe et des variables : un envoi fournit donc uniquement des valeurs, comme un code OTP ou un numéro de commande.

Bird fournit un catalogue géré, en enregistre le contenu auprès de WhatsApp et l’envoie depuis les numéros propres à Bird ; ses slugs commencent par bird_. Un espace de travail qui a connecté un numéro qui lui appartient peut aussi créer des modèles sur son propre compte WhatsApp Business. La page Approved templates affiche tous les modèles que l’espace de travail peut envoyer et leur rendu.

La page Templates WhatsApp du tableau de bord Bird, avec la liste des modèles. Un champ de recherche et des filtres de statut et de catégorie se trouvent au-dessus du tableau. Chaque ligne indique le statut d’un modèle, Draft ou Active, puis son nom et son slug, sa catégorie, ses langues disponibles, le WABA qui le détient et la date de sa dernière modification.

Parcourir les modèles dans le tableau de bord

Ouvrez Approved templates dans WhatsApp > Approved templates. Your templates contient les modèles créés par cet espace de travail ; All templates y ajoute le catalogue géré par Bird. Recherchez par nom ou filtrez par statut et par catégorie, et basculez entre la grille de cartes et la vue en liste avec le sélecteur situé à côté des filtres.

En vue liste, chaque ligne affiche les champs nécessaires pour choisir et envoyer un modèle :

  • Status : indique si le modèle peut être envoyé dans l’ensemble. Les modèles du catalogue géré indiquent active ; un modèle qui vous appartient indique l’état de sa propre approbation. Consultez la liste des langues pour vérifier que la langue requise est disponible.
  • Name : le libellé affiché, avec le slug du modèle en dessous. Utilisez le slug pour l’envoi.
  • Languages : les langues dans lesquelles le modèle est enregistré, comme l’anglais et le néerlandais.
  • Category : authentication, utility ou marketing. La catégorie détermine la façon dont WhatsApp traite le message, le numéro Bird depuis lequel un modèle géré est envoyé et, avec le pays de destination, le prix.
  • WABA : Bird-managed pour les modèles du catalogue. Un modèle qui vous appartient affiche le compte WhatsApp Business qui le détient, et n'est envoyé que depuis un numéro de ce même compte.
  • Updated : date de la dernière modification du modèle.

Cliquez sur une ligne pour ouvrir le détail du modèle.

Contenu d'un modèle

La vue détaillée affiche le corps du message, les variables et les boutons dans un aperçu de style WhatsApp.

Le détail fournit aussi un exemple cURL pour POST /v1/whatsapp/messages, qui utilise l'hôte régional et les valeurs d'exemple du modèle. Remplacez la clé API, le destinataire et les valeurs des variables avant l'envoi.

L'exemple est le moyen le plus rapide de voir la structure à laquelle un envoi doit correspondre. Via l'API, le même contenu provient de la version du modèle (Lire le contenu d'un modèle).

Lister les modèles depuis l'API

GET /v1/whatsapp/templates renvoie un catalogue paginé par curseur. La requête nécessite un accès en lecture whatsapp_management. Utilisez HTTP ou une méthode de requête brute d'un SDK.

type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});

Chaque entrée identifie le modèle, sa catégorie et ses langues disponibles. Pour obtenir le contenu du message, lisez séparément la version active.

Exemple de code
{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}

L'exemple de réponse abrège les listes de langues bird_otp.

Les champs dont dépend un envoi :

  • slug : l'identifiant utilisé dans un envoi. Les slugs des modèles gérés commencent par bird_, un préfixe qui leur est réservé.
  • waba : le compte WhatsApp Business qui détient les langues du modèle chez Meta, et auquel doit appartenir le numéro d'envoi. Ce champ est absent sur un modèle géré, car Bird gère son compte.
  • available_languages : les langues qui peuvent être envoyées. Une langue en pause, désactivée, archivée ou limitée est retirée de cette liste.
  • on_missing_language : ce qui se passe lorsque la langue demandée n'est pas disponible. Les modèles WhatsApp gérés par Bird utilisent fail, qui rejette l'envoi au lieu de le remplacer par une autre langue.

Statut et statut de langue

Les modèles gérés par Bird indiquent status: active. languages.<tag>.status indique l'état attribué par WhatsApp à une langue, par exemple approved, paused ou disabled.

Un modèle actif peut tout de même avoir une langue indisponible. Utilisez available_languages pour déterminer si une langue peut être envoyée.

Lire le contenu d'un modèle

Le contenu du message est rattaché à une langue de la version active. Lisez live_version_id dans le modèle, puis demandez la langue souhaitée :

const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});

La référence du modèle accepte un ID slug ou wat_. GET …/versions/{version_id}/languages liste les langues de la version sans leur contenu.

Exemple de code
{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "name": "ref", "text": "A1B2C3D4", "type": "text" },
        { "name": "amount", "text": "USD 49.99", "type": "text" }
      ],
      "text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "status": "approved"
}

Un envoi remplit ces espaces réservés par leur nom. example_parameters identifie chacun d'eux. Dans cet exemple, le champ parameters de l'envoi prend les clés ref et amount. Les clés d'un modèle positionnel sont ses numéros, par exemple 1, à deux exceptions près : le code d'un modèle d'authentification prend la clé code, et le suffixe numéroté d'un bouton url prend la clé button_url. Les boutons paramétrés ont leur propre example_parameters.

Le champ category de la langue indique la catégorie Meta utilisée pour la tarification. Elle peut différer de la catégorie enregistrée du modèle si Meta reclasse la langue.

La liste variables de la version récapitule chaque espace réservé avec sa clé, son type, son indicateur d'obligation et sa contrainte. Les espaces réservés nommés utilisent leur nom comme clé. Les espaces réservés positionnels utilisent leur numéro, sauf un code d'authentification (code) et le suffixe d'un bouton url (button_url). Le champ parameters d'un envoi accepte ces clés.

Envoyer avec un modèle

Indiquez le modèle dans l'objet template de l'envoi et renseignez ses variables via parameters. Consultez Envoyer des messages WhatsApp pour la charge utile complète :

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    parameters: { code: "123456" },
  },
});
console.log(msg.id, msg.status);

Envoyer selon la catégorie

Chaque modèle appartient à l'une des trois catégories de Meta. La catégorie détermine ce que vous devez faire pour qu'un envoi réussisse, ainsi que son coût. Pour créer ou copier votre propre modèle d'authentification, votre entreprise doit être vérifiée, mais pas pour en envoyer un : le bird_otp géré par Bird se trouve sur le compte WhatsApp Business de Bird et s'envoie sans vérification de votre part. Les modèles marketing s'envoient toujours depuis votre propre compte WhatsApp Business, via un second API Meta vers lequel Bird achemine automatiquement les envois. Les modèles utilitaires sont ceux qui exigent le moins de prérequis.

  • Modèles d'authentification : codes à usage unique, bouton de copie du code et vérification requise pour en créer un
  • Modèles utilitaires : mises à jour de commande, rappels de rendez-vous et notifications de compte
  • Modèles marketing : envois promotionnels, compte professionnel nécessaire et attentes en matière de désinscription

Étapes suivantes

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Essayez la pratique et obtenez un guide d'implémentation