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

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

caption bestaat in geen van beide richtingen op deze arm, dus een audiobericht bevat nooit tekst. 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 pagina inkomende media ophalen van de hub bevat die aanroep in elke taal, samen met de redirect- en headerregels die de aanroep volgt.

mime_type benoemt de container en de codec. Een voicenote is Opus in een Ogg-container, terwijl een bijlage waarschijnlijk MP3 of AAC is. Lees het type uit het veld en niet uit de bestandsextensie in url, want die heeft er geen. Controleer het type voordat je de bytes doorgeeft aan een transcriptieservice die maar enkele formaten accepteert. Het bericht en de media verlopen samen, 30 dagen nadat het bericht binnenkomt; de pagina inkomende media ophalen van de hub beschrijft die termijn en wat het uitlezen teruggeeft zodra die verstreken is.

De webhook-payload

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

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

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 webhooks: alle events waarop je je kunt abonneren