Envoyer votre premier message WhatsApp

Envoyez un message WhatsApp à votre propre téléphone avec Bird WhatsApp, puis relisez le message pour confirmer sa remise. 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é et 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 un envoi que le solde ne peut pas couvrir avec 402 WalletInsufficientBalance. 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 associé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 à votre téléphone le modèle bird_delivery_update préapprouvé du catalogue géré de Bird, ou utilisez bird_otp pour envoyer un code de vérification à usage unique. Les noms des modèles gérés commencent par bird_ et ces modèles sont envoyés depuis un numéro Bird partagé : vous omettez donc from. Installez le Bird SDK 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",
    parameters: { ref: "A1B2C3D4", date: "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",
            parameters={"ref": "A1B2C3D4", "date": "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",
		Parameters: map[string]any{"ref": "A1B2C3D4", "date": "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;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    parameters: ['ref' => 'A1B2C3D4', 'date' => '10 Jul 2026'],
);

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

bird whatsapp send \
  --parameters '{"date":"10 Jul 2026","ref":"A1B2C3D4"}' \
  --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",
      "parameters": {
        "ref": "A1B2C3D4",
        "date": "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 à l’aide de son ID wam_. Remplacez WHATSAPP_MESSAGE_ID par le id obtenu à l’étape 2, et 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 enregistre à quel moment.
delivered : WhatsApp a confirmé la distribution sur l’appareil du destinataire, et delivered_at enregistre à quel moment. Lorsque le destinataire lit le message, read_at est renseigné tandis que status reste delivered.
failed ou rejected : le message n’est pas parvenu au téléphone. last_error en donne la raison, et Événements de statut des messages liste 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 aussi 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 ne dispose pas du scope whatsapp. Modifiez les scopes 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 du numéro d'abonné.

Étapes suivantes

Envoyer des messages WhatsApp : envoyez des templates et des messages de service libres pendant la fenêtre de service client de 24 heures.
Templates WhatsApp : parcourez le catalogue géré (bird_otp, bird_delivery_update et d'autres) ou créez vos propres templates.
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 les confirmations de lecture (ainsi que les messages entrants si vous utilisez votre propre numéro connecté).
Référence de l'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