Envoyer à un groupe WhatsApp

Un envoi de groupe est un POST /v1/whatsapp/messages ordinaire dont to désigne un groupe plutôt qu'une personne : une requête, un message, et chaque participant de ce groupe le reçoit et peut répondre là où les autres le voient. Ce qui change, c'est le reporting. Le message porte des compteurs indiquant combien de participants il a atteints, et la livraison est confirmée un participant à la fois.

La création et l'administration d'un groupe sont distinctes de l'envoi de messages. Gérer les groupes WhatsApp couvre la création d'un groupe via l'API et le partage de son lien d'invitation, et les groupes WhatsApp couvre la fonction d'un groupe et les limites imposées par WhatsApp.

Prérequis

Vous avez besoin d'une clé API avec la permission d'écriture WhatsApp et de l'ID d'un groupe Active (wag_…). Copiez-le depuis l'onglet Details du groupe sur la page Groups, lisez-le depuis to.group_id sur un message reçu via le groupe, ou listez vos groupes.

Remplacez l'ID de groupe d'exemple par le vôtre. Initialisez le client pour votre langage en suivant le guide SDK TypeScript, Python, Go ou PHP. Pour les exemples CLI, installez et authentifiez le CLI avec un accès en écriture WhatsApp. Utilisez l'hôte API correspondant à la région de votre espace de travail dans les requêtes cURL.

1. Envoyer le message

Placez l'ID du groupe dans to et omettez from. Un groupe est lié au numéro professionnel avec lequel il a été créé, ce numéro est donc le seul sur lequel le message peut partir ; spécifier un expéditeur renvoie une 422 E15018.

const msg = await bird.whatsapp.send({
  to: "wag_01krdgeqcxet5s7t44vh8rt9mg",
  text: { body: "The route sheet for Tuesday is up." },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="wag_01krdgeqcxet5s7t44vh8rt9mg",
    text={"body": "The route sheet for Tuesday is up."},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:   "wag_01krdgeqcxet5s7t44vh8rt9mg",
	Text: &bird.WhatsAppTextSend{Body: "The route sheet for Tuesday is up."},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$text = (new WhatsAppMessageSendRequestText())
    ->setBody("The route sheet for Tuesday is up.");
$message = $bird->whatsapp->send(
    to: 'wag_01krdgeqcxet5s7t44vh8rt9mg',
    text: $text,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --text 'The route sheet for Tuesday is up.' \
  --to wag_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "wag_01krdgeqcxet5s7t44vh8rt9mg",
      "text": { "body": "The route sheet for Tuesday is up." }
    }'

L'API renvoie 202 avec le groupe repris sur to.group_id, status: accepted, et recipient_count : le nombre de personnes dans le groupe au moment où l'envoi a été accepté. Ce nombre est le dénominateur de tout ce qui suit à l'étape 3, et il est figé à cet instant. Une personne qui rejoint via le lien d'invitation pendant que le message est en cours d'acheminement ne le reçoit pas et ne modifie pas ce nombre.

2. Ce qu'un groupe accepte

Un groupe accepte du texte, des images, de la vidéo, de l'audio, des stickers, des documents, une position, des cartes de contact, et un template que votre espace de travail a créé dans n'importe quelle catégorie sauf l'authentification. Deux types de contenu sont refusés avec une 422 E15052, avant la création ou la facturation du message, car WhatsApp ne distribue ni l'un ni l'autre dans un groupe :

Tout contenu interactif : boutons de réponse, menus en liste, boutons de lien, carrousels, et les demandes de position et d'informations de contact.
Un template d'authentification. Envoyez plutôt le code de vérification à usage unique directement au participant.

Un template géré par Bird est envoyé depuis un numéro appartenant à Bird, qui n'est jamais le numéro auquel un groupe est lié, donc adresser un tel template à un groupe renvoie une 422 E15001.

Le contenu libre nécessite toujours une fenêtre de service client ouverte, et un groupe possède la sienne : tout participant qui envoie un message au groupe ouvre une fenêtre unique de 24 heures pour l'ensemble du groupe, et ce même participant qui vous écrit en dehors du groupe ne l'ouvre pas. Une fois la fenêtre expirée, seul un template peut atteindre le groupe.

3. Suivre la distribution

Récupérez le message pour voir jusqu'où il est parvenu. Trois compteurs rendent compte de la distribution :

Champ	Ce qu'il indique
`recipient_count`	Participants au moment de l'acceptation, le dénominateur des deux autres
`delivered_count`	Combien WhatsApp a confirmé que le message a atteints, y compris ceux qui n'ont signalé qu'une lecture
`read_count`	Combien l'ont ouvert

Sur un message de groupe, status indique le point le plus avancé atteint par tous les destinataires : il passe à delivered uniquement quand delivered_count est égal à recipient_count, et reste à sent tant que certains ont confirmé et d'autres non. Aucun message WhatsApp n'a de statut read, donc la lecture se suit via read_count et read_at. delivered_at et read_at sont ceux du premier destinataire, pas du dernier. failed et rejected ne sont jamais par participant, car il n'y a qu'une seule remise à WhatsApp et une seule façon pour celle-ci d'être refusée.

Un envoi à un groupe auquel personne n'avait encore adhéré ne porte aucun compteur, puisqu'il n'y a pas de dénominateur à rapporter ; utilisez donc to.group_id plutôt que les compteurs pour distinguer un message de groupe d'un message individuel.

Pour savoir quel participant une confirmation concerne, listez les événements du message. Un envoi de groupe produit au plus un whatsapp.delivered et au plus un whatsapp.read par participant, chacun portant recipient avec le numéro de téléphone de cette personne, son identifiant utilisateur limité à l'entreprise, ou les deux. Ni l'un ni l'autre n'est garanti pour quiconque : WhatsApp omet l'accusé de réception pour un participant qui regarde déjà la conversation, et une lecture n'arrive que s'il ouvre le message. Comptez ce qui arrive plutôt que d'attendre un événement de chaque type par participant, et consultez les compteurs pour les totaux. L'événement whatsapp.sent unique ne porte pas de recipient : il correspond à la seule transmission à WhatsApp, qui ne nomme personne. Les webhooks whatsapp.delivered et whatsapp.read portent le même champ, ce qui vous permet de distinguer des callbacks par ailleurs identiques.

4. Lire la conversation d'un groupe

Passez group_id à list messages pour le fil d'un groupe, dans les deux directions :

for await (const msg of bird.whatsapp.list({ group_id: "wag_01krdgeqcxet5s7t44vh8rt9mg" })) {
  console.log(msg.id, msg.direction, msg.status);
}

for msg in client.whatsapp.list(group_id="wag_01krdgeqcxet5s7t44vh8rt9mg"):
    print(msg.id, msg.direction, msg.status)

for msg, err := range client.Whatsapp.List(context.Background(), bird.WhatsappListParams{
	GroupID: "wag_01krdgeqcxet5s7t44vh8rt9mg",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Direction, *msg.Status)
}

foreach ($bird->whatsapp->list(['group_id' => 'wag_01krdgeqcxet5s7t44vh8rt9mg']) as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird whatsapp list --group-id wag_01krdgeqcxet5s7t44vh8rt9mg

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

Un message de groupe entrant est restitué avec le participant qui l'a écrit sur from, et un to qui porte à la fois votre numéro professionnel et group_id : le numéro qui l'a reçu, qualifié par le groupe par lequel il est arrivé. Ni to ni from ne correspond à un groupe, donc group_id est le seul filtre qui restreint la liste à un seul groupe. Les mêmes messages se trouvent dans le journal WhatsApp du dashboard.

Coût

Un envoi de groupe est facturé selon les deux composantes décrites dans Envoyer des messages WhatsApp, avec une différence dans la tarification de chacune. Les frais de Bird sont facturés une seule fois pour l'envoi et calculés sur le pays du numéro professionnel utilisé, car un groupe peut couvrir plusieurs pays et n'a pas de pays destinataire unique. La part de Meta s'accumule par participant atteint par le message, chacun étant facturé au tarif individuel habituel pour le pays de ce participant, de sorte que passthrough_amount augmente à mesure que leurs accusés de réception arrivent. À partir du 1er octobre 2026, cette part couvre aussi le contenu libre envoyé au groupe, que Meta facture par participant atteint et déduit des 1 000 messages de service gratuits par mois du numéro expéditeur : changements tarifaires d'octobre 2026.

Dépannage

404 (E15046) : L'ID de groupe ne désigne aucun groupe détenu par cet espace de travail. Un groupe appartient à l'espace de travail qui l'a créé, donc un ID provenant d'un autre espace de travail est introuvable ici.
409 (E15047) : Le groupe est en attente, suspendu, supprimé ou en échec. Seul un groupe Active peut recevoir des messages, et un groupe reste en attente tant que WhatsApp ne l'a pas confirmé.
422 (E15018) : Supprimez from. Le groupe envoie sur le numéro avec lequel il a été créé.
422 (E15052) : Contenu interactif, ou template d'authentification. Voir ce qu'un groupe accepte.
422 (E15044) : La fenêtre de service du groupe est fermée. Envoyez un template, ou attendez qu'un participant écrive au groupe.
status bloqué sur sent : Moins de recipient_count participants ont confirmé la livraison. Consultez les événements du message pour voir qui manque.

Étapes suivantes

Recevoir les messages de groupe WhatsApp : identifier l'expéditeur et répondre au groupe
Gérer les groupes WhatsApp : gérer les participants, les liens d'invitation et les demandes d'adhésion
Webhooks de statut des messages : recevoir les mises à jour de livraison de vos messages
Identifiants utilisateur limités à l'entreprise : identifier un participant dont vous n'avez pas le numéro de téléphone

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