Modèles utilitaires WhatsApp

Un modèle utilitaire fait suite à une action que le destinataire a déjà effectuée : une commande, un paiement, une réservation, une connexion. Le catalogue de Bird en propose huit, dont bird_signin_alert et bird_delivery_update. Déterminez la catégorie d'un slug d'après la liste des modèles, et non d'après son nom : bird_signin_alert ressemble à un modèle d'authentification, mais c'est un modèle utilitaire.

Avant l'envoi

Choisissez un modèle géré du catalogue ou créez un modèle utilitaire sur votre compte professionnel connecté.

L'envoi des modèles du catalogue de Bird ne nécessite aucune vérification de votre part, comme pour l'authentification. La création de votre propre modèle utilitaire n'en nécessite pas non plus : contrairement à l'authentification, l'exigence de vérification d'entreprise de Meta ne s'applique jamais aux modèles utilitaires. Vous pouvez donc créer et modifier des modèles utilitaires dans un espace de travail non vérifié. Consultez Vérification d'entreprise WhatsApp pour savoir ce que la vérification débloque ailleurs.

to peut être un numéro de téléphone au format E.164 ou un identifiant utilisateur propre à l'entreprise. Un modèle utilitaire ne comporte pas de bouton OTP : il n'exige donc pas un destinataire identifié uniquement par son numéro de téléphone, contrairement à l'authentification.

Chaque modèle utilitaire géré du catalogue est enregistré uniquement en en, avec on_missing_language: fail. Si vous demandez une langue absente du catalogue, l'envoi échoue au lieu de basculer vers l'anglais ou une autre langue.

Envoyer un modèle utilitaire

POST /v1/whatsapp/messages avec un objet template qui indique un slug du catalogue :

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  template: {
    slug: "bird_order_confirmation",
    language: "en",
    parameters: { ref: "A1B2C3D4", amount: "USD 49.99" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    template="bird_order_confirmation",
    language="en",
    parameters={"ref": "A1B2C3D4", "amount": "USD 49.99"},
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:         "+16505551234",
		Template:   "bird_order_confirmation",
		Language:   "en",
		Parameters: map[string]any{"ref": "A1B2C3D4", "amount": "USD 49.99"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->whatsapp->send(
    to: '+16505551234',
    template: 'bird_order_confirmation',
    language: 'en',
    parameters: ['ref' => 'A1B2C3D4', 'amount' => 'USD 49.99'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"amount":"USD 49.99","ref":"A1B2C3D4"}' \
  --template bird_order_confirmation \
  --to +16505551234

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+16505551234",
      "template": {
        "slug": "bird_order_confirmation",
        "language": "en",
        "parameters": {
          "ref": "A1B2C3D4",
          "amount": "USD 49.99"
        }
      }
    }'

Comme pour tout modèle géré, omettez from : Bird choisit le numéro d'envoi selon la catégorie et la région, et si vous le renseignez, l'appel renvoie 422 E15018 WhatsAppSenderNotAllowed. Créer et envoyer votre propre modèle utilitaire fonctionne comme tout envoi de modèle créé par vous ; consultez Envoyer avec un modèle pour le contrat général.

Renseigner les variables

Les variables d'un modèle utilitaire sont nommées : chacune correspond donc à sa propre clé dans parameters, par exemple ref et amount. Un bouton URL dont le suffixe {{1}} est numéroté utilise plutôt la clé button_url. Un suffixe nommé utilise son propre nom. L'envoi transmet la valeur seule, et non une adresse complète :

{ "parameters": { "ref": "A1B2C3D4", "button_url": "A-4192" } }

Un envoi components nomme plutôt chaque paramètre du corps, et l'ordre d'un paramètre nommé dans le tableau n'a aucune signification. Pour les règles communes sur les composants, sur sub_type et sur la correspondance entre les components d'un envoi et les espaces réservés déclarés par un modèle, consultez Envoyer avec un modèle et Composants et paramètres.

Coût

Un modèle utilitaire distribué pendant qu'une fenêtre de service client est ouverte bénéficie du tarif gratuit de Meta jusqu'au 30 septembre 2026. À partir du 1er octobre 2026, Meta le facture comme tout autre modèle utilitaire (changements tarifaires d'octobre 2026). Les frais sortants de Bird sont facturés pendant le traitement du message, avant sa soumission. C'est un rappel ultérieur de distribution ou de lecture qui détermine si des frais Meta s'appliquent. Tenez compte de ces deux composantes pour estimer le total.

Consultez Coût et facturation pour savoir quand un envoi est facturé, et Tarifs WhatsApp pour les tarifs.

Points de vigilance

• Meta peut reclasser de sa propre initiative un modèle utilitaire en marketing, et le message continue d'être envoyé au nouveau tarif, plus élevé. Depuis avril 2025, une entreprise que Meta a déjà avertie pour une mauvaise catégorisation ne reçoit aucun préavis : le changement s'applique immédiatement. N'incluez dans le texte d'un modèle utilitaire aucun langage promotionnel, aucune offre ni aucune vente additionnelle, car c'est ce qui déclenche le reclassement. Consultez Consignes relatives aux modèles pour savoir ce qui est considéré comme promotionnel.
• Un en-tête gif ou un bouton copy_code est refusé en dehors du marketing. Ces deux composants sont réservés au marketing : en déclarer un sur un modèle utilitaire provoque un échec.
• Le nombre de paramètres d'un envoi components avec votre propre modèle n'est pas vérifié avant la facturation. Si vous envoyez un nombre incorrect de paramètres dans components avec votre propre modèle, le message est accepté et facturé, puis rejeté par Meta. Un envoi parameters auquel il manque une clé obligatoire est refusé avant toute facturation, et les envois de modèles gérés du catalogue ne présentent pas cette faille.
• Un expéditeur rattaché au mauvais compte WhatsApp Business est refusé avant toute facturation. from doit se trouver sur le même compte que le modèle ; sinon, l'envoi échoue avec 422 E15023 WhatsAppSenderWABAMismatch.

Étapes suivantes

• Modèles WhatsApp : parcourir le catalogue et le contrat commun d'envoi par modèle
• Modèles d'authentification : les codes de vérification à usage unique et l'exigence de vérification pour en créer un
• Modèles marketing : les envois promotionnels et le compte nécessaire pour en créer un