Modèles d’authentification WhatsApp

Un modèle d’authentification transmet un code de vérification à usage unique. Meta fournit son texte lorsque vous créez le modèle. Lors de l’envoi, indiquez le code comme paramètre du corps.

Avant l’envoi

Choisissez entre un modèle géré par Bird et un modèle que vous créez sur votre propre compte professionnel.

L’envoi des modèles du catalogue fournis par Bird, bird_otp et bird_otp_authifly, ne nécessite aucune vérification de votre part. Ces modèles se trouvent sur les comptes WhatsApp Business de Bird, et le circuit d’envoi géré ne contrôle jamais le statut de vérification de votre entreprise.

Lorsque le compte professionnel connecté indique not_verified, Bird refuse la création ou la duplication de modèles d’authentification avec 412 E15043 WhatsAppTemplateBusinessNotVerified. Vérifiez le compte connecté et son dernier statut synchronisé. Consultez Vérification de l’entreprise WhatsApp pour le processus de vérification et la gestion des statuts.

Cette condition ne concerne pas la création de modèles utilitaires et marketing : vous pouvez continuer à les créer et à les modifier quel que soit votre statut de vérification.

Créez vos modèles dans le tableau de bord, avec la bird CLI ou via le serveur MCP. Consultez Créer des modèles d’authentification pour la procédure complète.

Envoyer un code de vérification

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

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

msg = client.whatsapp.send(
    to="+14155550100",
    template="bird_otp",
    language="en",
    parameters={"code": "481920"},
)
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:         "+14155550100",
		Template:   "bird_otp",
		Language:   "en",
		Parameters: map[string]any{"code": "481920"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->whatsapp->send(
    to: '+14155550100',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '481920'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"481920"}' \
  --template bird_otp \
  --to +14155550100

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+14155550100",
      "template": {
        "slug": "bird_otp",
        "language": "en",
        "parameters": {
          "code": "481920"
        }
      }
    }'

Quatre règles sont propres à cette catégorie :

Omettez from. Un modèle géré par Bird choisit lui-même son expéditeur en fonction de la catégorie et de la région. Si vous définissez from, vous obtenez donc 422 E15018 WhatsAppSenderNotAllowed. C'est l'inverse d'un envoi en format libre, qui exige from : gardez-le en tête si vous venez des pages sur les messages interactifs.
to doit être un numéro de téléphone au format E.164. Un modèle d'authentification ne peut pas être envoyé à un identifiant utilisateur propre à une entreprise. Une telle tentative renvoie 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
Le code se place dans parameters.code. Il remplit l'espace réservé du corps et le bouton de copie du code. Un envoi components prend en revanche exactement un paramètre de corps positionnel : le code. Si vous ne fournissez aucun paramètre ou si vous nommez le paramètre, vous obtenez 422 E15003 WhatsAppTemplateParameterMismatch.
Aucune fenêtre de service client n'est nécessaire. Les envois de modèles ne dépendent pas de cette fenêtre. C'est la raison d'être d'un modèle de code de vérification : il doit atteindre une personne qui ne vous a jamais écrit.

Consultez les langues disponibles pour bird_otp ou bird_otp_authifly dans le catalogue de modèles. Si la langue demandée n'est pas disponible, l'envoi échoue au lieu de passer à une autre langue.

Le bouton de copie du code

Meta rédige lui-même le corps d'un modèle d'authentification, sous forme de texte prédéfini contenant un seul espace réservé pour le code. Vous fournissez donc des indicateurs plutôt que du texte. Un envoi parameters remplit le bouton à partir de code. Dans un envoi components, le composant bouton est facultatif : si vous n'en incluez pas, Bird l'ajoute pour vous, avec le même code que le corps. Vous pouvez aussi le fournir vous-même :

Exemple de code

{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }

Dans les deux cas, un seul bouton parvient à WhatsApp : le bouton de copie du code. Un appui sur ce bouton copie le code dans le presse-papiers. Bird prend en charge uniquement copy_code. Les deux autres comportements de bouton que Meta documente pour les modèles d'authentification, le remplissage automatique en un appui et sans appui, ne sont pas disponibles sur Bird.

La création du bouton d'un modèle suit la même structure : un seul bouton otp, et le modèle n'accepte aucun autre type de bouton. Au lieu de rédiger du texte, vous fournissez add_security_recommendation (un booléen affiché dans le corps) et code_expiration_minutes (de 1 à 90, affiché dans le pied de page).

Ce que Meta autorise dans un modèle d'authentification

Meta impose la structure d'un modèle d'authentification et en examine le contenu : aucune URL, aucun média ni aucun emoji nulle part dans le modèle, et 15 caractères au maximum pour le paramètre du code. La catégorie modifie aussi la façon dont WhatsApp distribue le message : il est envoyé uniquement à l'appareil principal du destinataire. Consultez Consignes relatives aux modèles pour le détail de la structure imposée, des limites de caractères et du processus d'examen.

Coût

Le prix dépend de la catégorie et de la destination. Consultez Tarifs authentication-international WhatsApp pour savoir comment un envoi vers un pays autre que votre pays principal peut le modifier, et Coût et facturation pour savoir quand un envoi est facturé. Les tarifs figurent sur Tarifs WhatsApp.

Points d'attention

Les modèles proposés par Bird ne sont pas distribués dans neuf pays. bird_otp et bird_otp_authifly sont envoyés depuis les comptes WhatsApp Business de Bird, et ces comptes n'acheminent pas les messages d'authentification vers l'Égypte, l'Inde, l'Indonésie, la Malaisie, le Nigeria, le Pakistan, l'Arabie saoudite, l'Afrique du Sud et les Émirats arabes unis. Un tel envoi est refusé avec 422 E15063 WhatsAppDestinationRestricted avant toute facturation. Un modèle que vous avez créé sur votre propre compte et envoyé depuis votre propre numéro atteint normalement ces pays. Verify les atteint aussi, en basculant de lui-même le code de vérification vers un autre canal.
Un envoi de modèle créé par vos soins exige from, qui doit appartenir au même compte WhatsApp Business que le modèle. Un expéditeur rattaché à un autre compte est refusé avec 422 E15023 WhatsAppSenderWABAMismatch avant toute facturation.
Seule une langue dont la version est approuvée et active peut être envoyée. Une langue à l'état de brouillon, en attente, rejetée ou suspendue ne peut pas l'être.
Meta peut changer la catégorie d'un modèle de sa propre initiative. Vous ne pouvez pas le refuser, et ce changement modifie les règles de tarification et de distribution liées à la catégorie.
La catégorie du modèle et celle de sa langue peuvent différer. Consultez Modèles WhatsApp pour savoir comment le processus d'envoi résout cet écart.
Un modèle d'authentification importé ne peut pas être dupliqué. Bird ne peut pas convertir le texte généré par WhatsApp en paramètres servant à créer un nouveau modèle ; l'opération renvoie 422 E15024 WhatsAppTemplateContentNotDuplicable. Créez plutôt un nouveau modèle avec sa propre recommandation de sécurité et sa propre durée d'expiration du code.

Étapes suivantes

Modèles WhatsApp : parcourir le catalogue et le contrat commun d'envoi par modèle
Modèles utilitaires : suivi de commandes, rappels de rendez-vous et notifications de compte
Vérification d'entreprise WhatsApp : fonctionnement de la vérification et ce qu'elle débloque d'autre

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

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

Ressources associées