Envoyer votre premier message WhatsApp

Envoyez un message WhatsApp vers votre propre téléphone avec Bird WhatsApp, puis relisez le message pour confirmer sa distribution. Les envois à l’initiative de l’entreprise utilisent un modèle préapprouvé. Ce guide de démarrage envoie depuis le catalogue de modèles gérés de Bird (comme bird_delivery_update ou bird_otp), qui utilise un expéditeur WhatsApp partagé géré par Bird. Vous n’avez pas besoin de connecter un compte WhatsApp Business ni d’enregistrer un numéro au préalable.

Avant de commencer, vérifiez que le portefeuille de votre organisation est approvisionné. Les envois de modèles WhatsApp sont débités du portefeuille, et Bird refuse avec 402 WalletInsufficientBalance tout envoi que le solde ne peut pas couvrir. La page Moyens de paiement et portefeuille explique comment recharger le portefeuille.

1. Créer une clé API

Dans le tableau de bord, accédez à Platform tools > API keys et créez une clé avec la portée whatsapp:write, qui permet d’envoyer et de lire des messages. Chaque clé est liée à une région et ressemble à bk_us1_... ou bk_eu1_.... La région indiquée dans le préfixe détermine l’hôte API à appeler : https://us1.platform.bird.com ou https://eu1.platform.bird.com.

La page des clés API dans le tableau de bord Bird, qui liste les clés avec leur préfixe masqué, leurs portées et leur date de dernière utilisation

La clé complète ne s’affiche qu’une seule fois, lors de sa création. Copiez-la en lieu sûr, puis exportez-la pour les exemples cURL :

Exemple de code

export BIRD_API_KEY="bk_us1_..."

2. Envoyer un message basé sur un modèle

Envoyez le modèle bird_delivery_update préapprouvé du catalogue géré de Bird vers votre téléphone, ou utilisez bird_otp pour envoyer un code de vérification à usage unique. Les modèles gérés commencent par bird_ et sont envoyés depuis un numéro Bird partagé : vous omettez donc from. Installez le SDK Bird pour votre langage en suivant son guide de démarrage SDK. Si vous utilisez l’onglet Bird CLI, installez-le d’abord (curl -fsSL https://cli.bird.com/install.sh | sh), puis authentifiez-vous avec un accès en écriture (bird auth login --scope whatsapp:write).

Dans les onglets SDK, remplacez la clé API d’exemple, et remplacez +15551234567 par votre numéro de mobile au format E.164. Le CLI utilise votre connexion, et l’onglet cURL utilise BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.send(
            to="+15551234567",
            template="bird_delivery_update",
            components=[
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "name": "ref", "text": "A1B2C3D4"},
                        {"type": "text", "name": "date", "text": "10 Jul 2026"},
                    ],
                }
            ],
        )
        print(message.id, message.status)
    except APIError as err:
        print("send failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+15551234567",
		Template: "bird_delivery_update",
		Components: []bird.WhatsAppMessageTemplateComponent{{
			Type: "body",
			Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
				{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
				{Type: "text", Name: bird.String("date"), Text: bird.String("10 Jul 2026")},
			},
		}},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
            ]),
    ],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp send \
  --components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
  --template bird_delivery_update \
  --to +15551234567

curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "template": {
      "slug": "bird_delivery_update",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "name": "ref", "text": "A1B2C3D4" },
            { "type": "text", "name": "date", "text": "10 Jul 2026" }
          ]
        }
      ]
    }
  }'

Si votre clé commence par bk_eu1_, appelez plutôt https://eu1.platform.bird.com.

L’API répond avec 202 Accepted et le message créé. Son id commence par wam_, et son status vaut accepted : Bird a accepté le message et le distribue de manière asynchrone. Conservez le id pour l’étape suivante.

3. Vérifier le statut de distribution

Récupérez le message à partir de son ID wam_. Remplacez WHATSAPP_MESSAGE_ID par le id obtenu à l’étape 2, puis remplacez la clé API d’exemple dans les onglets SDK par la vôtre :

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.get("WHATSAPP_MESSAGE_ID")
        print(message.id, message.status)
    except APIError as err:
        print("read failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->get('WHATSAPP_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp get WHATSAPP_MESSAGE_ID

curl https://us1.platform.bird.com/v1/whatsapp/messages/WHATSAPP_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

Le champ status indique où en est le message :

accepted : Bird a admis le message et se prépare à le transmettre à WhatsApp.
sent : WhatsApp a accepté le message, et sent_at en enregistre l’heure.
delivered : WhatsApp a confirmé la distribution sur l’appareil du destinataire, et delivered_at en enregistre l’heure. Lorsque le destinataire lit le message, read_at est renseigné tandis que status reste à delivered.
failed ou rejected : le message n’a pas atteint le téléphone. last_error indique la raison, et Événements de statut des messages répertorie les codes d’erreur.

Interrogez l’API jusqu’à ce que le statut ne soit plus accepted ni sent, ou abonnez-vous aux webhooks WhatsApp pour recevoir chaque changement de statut de distribution et de lecture (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Les numéros partagés gérés par Bird servent uniquement à l’envoi et ne transmettent pas les réponses entrantes à votre espace de travail ; pour recevoir des réponses, connectez votre propre numéro. Chaque message apparaît également sur la page Messages avec la chronologie de ses événements.

Corriger un envoi en échec

402 WalletInsufficientBalance : le solde du portefeuille ne couvre pas le message. Rechargez le portefeuille, puis renvoyez le message.
403 InsufficientScope : la clé API n’a pas la portée whatsapp. Modifiez les portées de la clé ou créez une clé avec whatsapp:write.
422 WhatsAppInvalidRecipient : le numéro to n’est pas un numéro de téléphone E.164 valide. Vérifiez le + initial, l’indicatif du pays et les chiffres de l’abonné.

Étapes suivantes

Envoyer des messages WhatsApp : envoyez des modèles et des messages de service libres pendant la fenêtre de service client de 24 heures.
Modèles WhatsApp : parcourez le catalogue géré (bird_otp, bird_delivery_update et d’autres) ou créez vos propres modèles.
Connecter un numéro de téléphone : utilisez votre propre compte WhatsApp Business et votre propre numéro d’expéditeur pour que votre espace de travail puisse aussi recevoir les réponses entrantes.
Webhooks WhatsApp : recevez les accusés de réception et de lecture (ainsi que les messages entrants si vous utilisez votre propre numéro connecté).
Référence WhatsApp API : le schéma complet des requêtes et des réponses.

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

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