Envoyer des messages WhatsApp

Un envoi minimal

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

msg = client.whatsapp.send(
    to="+31612345678",
    template="bird_otp",
    language="en",
    components=[{"type": "body", "parameters": [{"type": "text", "text": "123456"}]}],
)
print(msg.id, msg.status)

code := "123456"
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:       "+15551234567",
	Template: "bird_otp",
	Language: "en",
	Components: []bird.WhatsAppMessageTemplateComponent{{
		Type:       "body",
		Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
	}},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('123456'),
            ]),
    ],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --components '[{"parameters":[{"text":"1234","type":"text"}],"type":"body"},{"parameters":[{"text":"1234","type":"text"}],"type":"button"}]' \
  --language en \
  --template bird_otp \
  --to +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        },
        {
          "type": "button",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        }
      ]
    }
  }'

La fenêtre de service client

Construire le payload

Destinataire

Template

• slug (obligatoire) : le slug du template, par exemple bird_order_confirmation. Il doit correspondre à un template de votre catalogue (lettres minuscules, chiffres et underscores).
• language : le tag de langue du template, par exemple en ou pt-BR. Omettez-le pour envoyer la langue par défaut du template ; nommer une langue que le template ne possède pas renvoie un 422 qui liste celles disponibles. Le message accepté renvoie en écho la langue résolue.
• components : les valeurs qui remplissent les variables du template (voir Composants et paramètres). Omettez-le pour un template sans variables.

Composants et paramètres

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

Catégorie et expéditeur

• Un template géré par Bird (son slug commence par bird_) est envoyé depuis le numéro que Bird conserve pour cette catégorie ; omettez donc from. Le définir renvoie un 422 WhatsAppSenderNotAllowed.
• Tout le reste nomme son propre expéditeur dans from : un message de service de tout type et tout template créé par votre espace de travail. Le numéro doit appartenir à votre espace de travail. L'omettre renvoie un 422 WhatsAppSenderRequired, et un numéro depuis lequel l'espace de travail ne peut pas envoyer renvoie un 422 WhatsAppSenderNotFound. Un template créé doit aussi se trouver sur le même WhatsApp Business Account que le numéro, sans quoi l'envoi renvoie un 422 WhatsAppSenderWABAMismatch.

Messages de service

• text : { "body": "..." }, jusqu'à 4 096 caractères. Ajoutez "preview_url": true pour afficher un aperçu de lien pour la première URL dans body.
• image, video, audio, sticker, document : chacun prend une URL https publique que WhatsApp récupère au moment de l'envoi (url) ; une URL signée doit donc rester valide au-delà de l'envoi. Une URL http est rejetée immédiatement. WhatsApp récupère le fichier lui-même ; une URL inaccessible, servant un type non pris en charge ou un fichier dépassant la limite de taille pour son type est acceptée puis échoue, avec media_rejected sur le last_error du message et la raison propre à WhatsApp dans description. image, video et document acceptent aussi un caption optionnel ; document accepte aussi un filename optionnel ; audio accepte un flag voice optionnel pour un rendu en note vocale.
• location : { "latitude": ..., "longitude": ... } (les deux obligatoires, en degrés décimaux) plus name et address optionnels.
• contact_cards : un tableau de cinq contacts maximum partagés dans un seul message. Le name de chaque fiche nécessite formatted_name plus au moins une autre partie (first_name, last_name, middle_name, prefix ou suffix) ; phone_numbers, emails, urls et addresses acceptent chacun jusqu'à dix entrées, et org et birthday (sous forme de YYYY-MM-DD) sont optionnels. Un phone_number au format E.164 ajoute à cette fiche un bouton ouvrant une conversation avec ce contact.
• interactive : du texte dans le corps plus un élément interactif, selon l'un des six types : boutons de réponse, menu à liste, bouton de lien, carrousel média, ou un bouton unique demandant au destinataire sa localisation ou son numéro de téléphone. Messages interactifs couvre la structure de chaque type, les réponses générées par un appui et les limites.

{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}

Citer un message

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that slot is still free." }
}

Tags et métadonnées

• tags : jusqu'à 20 labels { "name": ..., "value": ... } structurés pour des dimensions à faible cardinalité sur lesquelles vous filtrez et créez des rapports (une campagne, une variante d'expérience). Les noms et valeurs acceptent les lettres ASCII, chiffres, underscores et tirets ; les noms sont limités à 32 caractères et uniques par envoi, les valeurs à 64. Filtrez la liste des messages par tag (?tag=campaign ou ?tag=campaign:launch-week), et la page Métriques ventile la distribution par tag.
• metadata : un objet JSON arbitraire, jusqu'à 2 Ko sérialisé, pour du contexte par envoi dont vous n'avez pas besoin comme dimension de filtre (un identifiant de commande interne, une référence de session).

{
  "tags": [{ "name": "campaign", "value": "order-confirmations" }],
  "metadata": { "order_id": "ord_8271" }
}

Référence des champs

Le modèle asynchrone : ce que signifie 202

Réessayer en toute sécurité

Recevoir la réponse

Coût et facturation

Note: a service message carries no Meta share until September 30th 2026, and neither does a utility template delivered inside an open customer service window. From October 1st 2026 Meta charges for both, except inside a 72-hour free entry point window, and with 1,000 free service messages per business phone number per month: October 2026 pricing changes.

• Au moment du 202, cost est null. Rien n'a été tarifé.
• Après le traitement, transaction_amount est défini et amount lui est égal. passthrough_amount reste null.
• Après un accusé delivered ou read applicable, un frais Meta enregistré avec succès remplit passthrough_amount, et amount reflète les composants enregistrés.

Étapes suivantes

• Messages de service : les neuf types de contenu libre et ce que chacun accepte
• Recevoir des messages WhatsApp : messages entrants, médias et webhook whatsapp.received
• Identifiants utilisateur à portée business : adresser un contact qui vous a joint sans numéro de téléphone
• Templates : parcourir le catalogue et lire les variables d'un template
• Envoyer à un groupe WhatsApp : adresser un groupe et lire ses accusés par participant
• Idempotence : nouvelles tentatives sûres avec l'en-tête Idempotency-Key