WhatsApp-Audio empfangen

Audio, das ein Kontakt sendet, kommt als eingehende Nachricht mit audio an. Der Arm umfasst sowohl eine im Chat aufgenommene Sprachnachricht als auch eine angehängte Audiodatei, und voice unterscheidet die beiden.

Was eine eingehende Audionachricht enthält

Codebeispiel

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

Feld	Was es enthält
id	Die gespeicherte Datei, als media_id beim Abrufen der Bytes zu übergeben
url	Eine Bird-URL, abzurufen mit Ihrem API-Schlüssel
mime_type	Der von WhatsApp gemeldete Medientyp, zum Beispiel audio/ogg; codecs=opus für eine Sprachnachricht
voice	true bei einer im Chat aufgenommenen Sprachnachricht, nicht bei einer angehängten Audiodatei

caption existiert auf diesem Arm in keiner Richtung, daher enthält eine Audionachricht niemals begleitenden Text. Ein Kontakt, der Worte hinzufügen möchte, sendet eine separate Textnachricht.

Eine Sprachnachricht wird im WhatsApp-Client automatisch heruntergeladen und kann dort für den Empfänger transkribiert werden. Bird leitet das Audio durch und transkribiert es nicht, daher ist das Transkript, das Ihr Kontakt in seiner eigenen App sieht, nicht Teil der Nachricht, die Sie lesen.

Die Bytes abrufen

Übergeben Sie die Nachrichten-ID und die Media-id an die Media-Methode des Channels. Die Hub-Seite Eingehende Medien abrufen enthält diesen Aufruf in jeder Sprache samt den Redirect- und Header-Regeln, denen er folgt.

mime_type benennt den Container und den Codec, und eine Sprachnachricht ist Opus in einem Ogg-Container statt der MP3- oder AAC-Datei, die ein Anhang wahrscheinlich hat. Lesen Sie den Typ aus dem Feld statt aus der Dateierweiterung in url, die keine enthält, und prüfen Sie ihn, bevor Sie die Bytes an einen Transkriptionsdienst übergeben, der nur bestimmte Formate akzeptiert. Die Nachricht und ihre Medien verfallen gemeinsam, 30 Tage nach Eingang der Nachricht; die Hub-Seite Eingehende Medien abrufen beschreibt dieses Zeitfenster und was die Abfragen zurückgeben, wenn es abgelaufen ist.

Der Webhook-Payload

whatsapp.received enthält den audio-Arm im Event-Envelope, einschließlich des voice-Flags:

Codebeispiel

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

Ein automatisierter Flow, der Sprachnachrichten beantwortet, liest voice hier, bevor er etwas abruft: Eine Support-Warteschlange, die Aufnahmen transkribiert, aber angehängte Musikdateien weiterleitet, kann allein anhand des Flags verzweigen.

Worauf Sie achten sollten

Lesen Sie voice als Flag, das eine Sprachnachricht markiert. Alles andere, einschließlich eines fehlenden Feldes, ist ein gewöhnlicher Audio-Anhang.
Es wird keine Dauer gemeldet. Der Arm enthält keine Länge; lesen Sie sie nach dem Abrufen aus der Datei, falls eine Warteschlange sie benötigt.

Nächste Schritte

So funktioniert der Empfang: der Eingangs-Envelope, das Abrufen von Medien und der whatsapp.received-Webhook
WhatsApp-Audionachrichten: die Sendeseite desselben Arms
Video empfangen: Clips, mit einer Beschriftung, für die der Audio-Arm keinen Platz hat
WhatsApp-Events: die vollständige Event-Liste, über API oder Webhooks