WhatsApp-audio ontvangen

Audio die een contact stuurt komt binnen als een inkomend bericht met audio. De arm dekt zowel een voicenote die ze in de chat hebben ingesproken als een audiobestand dat ze hebben bijgevoegd, en voice maakt het verschil tussen de twee.

Wat een inkomend audiobericht bevat

Codevoorbeeld

{
  "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"
}

Veld	Wat het bevat
id	Het opgeslagen bestand, om als media_id mee te geven bij het ophalen van de bytes
url	Een Bird-URL, op te halen met je API-key
mime_type	Het mediatype dat WhatsApp heeft gerapporteerd, zoals audio/ogg; codecs=opus voor een voicenote
voice	true voor een voicenote die in de chat is ingesproken, in plaats van een bijgevoegd audiobestand

caption bestaat niet op deze arm in beide richtingen, dus een audiobericht bevat nooit tekst ernaast. Een contact dat woorden wil toevoegen stuurt een apart tekstbericht.

Een voicenote wordt automatisch gedownload in de WhatsApp-client en kan daar voor de ontvanger worden getranscribeerd. Bird geeft de audio door en transcribeert niet, dus het transcript dat je contact in de eigen app ziet maakt geen deel uit van het bericht dat je leest.

De bytes ophalen

Geef het bericht-ID en de media-id door aan de mediamethode van het kanaal. De hub's inkomende media ophalen bevat die aanroep in elke taal, samen met de redirect- en headerregels die worden gevolgd.

mime_type benoemt de container en de codec, en een voicenote is Opus in een Ogg-container in plaats van de MP3 of AAC die een bijlage waarschijnlijk heeft. Lees het type uit het veld in plaats van uit de bestandsextensie in url, die er geen heeft, en controleer het voordat je de bytes doorgeeft aan een transcriptieservice die maar enkele formaten accepteert. Het bericht en de media verlopen samen, 30 dagen na aankomst van het bericht; de hub's inkomende media ophalen bepaalt dat venster en wat de reads teruggeven zodra het verstreken is.

De webhook-payload

whatsapp.received bevat de audio-arm op de event-envelope, inclusief de voice-vlag:

Codevoorbeeld

{
  "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
  }
}

Een geautomatiseerde flow die voicenotes beantwoordt leest hier voice, voordat er iets wordt opgehaald: een supportwachtrij die opnames transcribeert maar bijgevoegde muziekbestanden doorstuurt kan puur op de vlag branchen.

Waar je op moet letten

Lees voice als een vlag die een voicenote markeert. Al het andere, inclusief een afwezig veld, is een gewone audiobijlage.
Er wordt geen duur gerapporteerd. De arm bevat geen lengte, dus lees die uit het bestand na het ophalen als een wachtrij dat nodig heeft.

Vervolgstappen

Hoe ontvangen werkt: de inkomende envelope, media ophalen en de whatsapp.received-webhook
WhatsApp-audioberichten: de verzendzijde van dezelfde arm
Video ontvangen: clips, met een bijschrift waar de audio-arm geen ruimte voor heeft
WhatsApp-events: de volledige eventlijst, via de API of webhooks

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channel Begrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builder Ontdek de mogelijkheidWhatsApp

Probeer de oefening en ontvang een implementatieoverzicht