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 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_) envoie depuis le numéro que Bird conserve pour cette catégorie, donc omettez 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éé par vous doit aussi être rattaché au même WhatsApp Business Account que le numéro, sinon 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), donc une URL signée doit rester valide au-delà de l'envoi. Une URL http est rejetée directement. WhatsApp récupère le fichier lui-même, donc une URL qu'il ne peut pas atteindre, une URL servant un type non pris en charge ou un fichier dépassant la limite de taille pour son type est accepté puis échoue, avec media_rejected sur le last_error du message et la raison propre de 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": ... } (tous deux obligatoires, en degrés décimaux) plus name et address optionnels.
• contact_cards : un tableau de jusqu'à cinq contacts 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 donne à cette fiche un bouton qui ouvre une conversation avec ce contact.
• interactive : du texte de corps plus un élément interactif, dans l'un des six types : boutons de réponse, menu de 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 le format d'échange de chaque type, les réponses produites 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 libellés { "name": ..., "value": ... } structurés pour des dimensions à faible cardinalité sur lesquelles vous filtrez et produisez des rapports (une campagne, une variante d'expérience). Les noms et valeurs acceptent les lettres ASCII, les chiffres, l'underscore et le tiret ; les noms sont limités à 32 caractères et uniques au sein d'un envoi, les valeurs à 64. Filtrez la liste de messages par tag (?tag=campaign ou ?tag=campaign:launch-week), et la page Metrics ventile la livraison par tag.
• metadata : un objet JSON arbitraire, jusqu'à 2 Ko sérialisé, pour un contexte par envoi dont vous n'avez pas besoin comme dimension de filtrage (un ID 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

• 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é de réception delivered ou read applicable, des frais Meta enregistrés avec succès alimentent 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édia et webhook whatsapp.received
• Identifiants utilisateur limités au périmètre 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
• Idempotence : réessais sûrs avec l'en-tête Idempotency-Key