Recevoir un audio WhatsApp

L'audio envoyé par un contact arrive sous forme de message entrant portant audio. Cette branche couvre aussi bien une note vocale enregistrée dans la conversation qu'un fichier audio joint, et c'est voice qui permet de les distinguer.

Ce que contient un audio entrant

Exemple de code

{
  "id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "audio": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "audio/ogg; codecs=opus",
    "voice": true
  },
  "created_at": "2026-08-25T09:07:32Z"
}

Champ	Ce qu'il contient
id	Le fichier stocké, à transmettre comme media_id lors de la récupération des octets
url	Une URL Bird, récupérée avec votre clé API
mime_type	Le type de média rapporté par WhatsApp, par exemple audio/ogg; codecs=opus pour une note vocale
voice	true pour une note vocale enregistrée dans la conversation, plutôt qu'un fichier audio joint

caption n'existe pas sur cette branche dans aucune des deux directions : un message audio ne contient donc jamais de texte en parallèle. Un contact qui souhaite ajouter des mots envoie un message texte séparé.

Une note vocale se télécharge automatiquement dans le client WhatsApp et peut y être transcrite pour le destinataire. Bird transmet l'audio sans le transcrire, donc la transcription que votre contact voit dans sa propre application ne fait pas partie du message que vous lisez.

Récupérer les octets

Transmettez l'identifiant du message et le id du média à la méthode media du canal. La section récupérer un média entrant du hub contient cet appel dans chaque langage, ainsi que les règles de redirection et d'en-têtes appliquées.

mime_type nomme le conteneur et le codec : une note vocale est de l'Opus dans un conteneur Ogg, et non du MP3 ou de l'AAC comme un fichier joint le sera probablement. Lisez le type depuis le champ plutôt que depuis l'extension de fichier dans url, qui n'en contient pas, et vérifiez-le avant de transmettre les octets à un service de transcription qui n'accepte que certains formats. Le message et son média expirent ensemble, 30 jours après l'arrivée du message ; la section récupérer un média entrant du hub décrit cette fenêtre et ce que les lectures renvoient une fois qu'elle est passée.

Le payload du webhook

whatsapp.received porte la branche audio sur l'enveloppe d'événement, indicateur voice inclus :

Exemple de code

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:07:32.451Z",
  "data": {
    "whatsapp_id": "wam_01kyb3q8ndvt6r2h5k9wxc4pfa",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "audio": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyb3q8ndvt6r2h5k9wxc4pfa/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "audio/ogg; codecs=opus",
      "voice": true
    },
    "tags": null,
    "metadata": null
  }
}

Un flux automatisé qui répond aux notes vocales lit voice ici, avant de récupérer quoi que ce soit : une file de support qui transcrit les enregistrements mais transfère les fichiers musicaux joints peut se brancher sur l'indicateur seul.

Points à surveiller

Lisez voice comme un indicateur signalant une note vocale. Toute autre valeur, y compris un champ absent, correspond à un fichier audio joint ordinaire.
Aucune durée n'est rapportée. La branche ne contient pas de longueur : lisez-la depuis le fichier après récupération si une file en a besoin.

Étapes suivantes

Fonctionnement de la réception : l'enveloppe entrante, la récupération de média et le webhook whatsapp.received
Messages audio WhatsApp : le côté envoi de la même branche
Recevoir une vidéo : des clips, avec une légende que la branche audio ne peut pas porter
Événements WhatsApp : la liste complète des événements, via le API ou les webhooks

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

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