Sign inGet started

WhatsApp-Audionachrichten

Eine Audionachricht enthält eine öffentliche URL, die WhatsApp zum Sendezeitpunkt abruft. Sie hat keine Bildunterschrift und kann optional als Sprachnotiz dargestellt werden.

Eine Audionachricht senden

Setzen Sie audio.url:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  audio: { url: "https://cdn.example.com/vm/9f2.ogg" },
});
console.log(msg.id, msg.status);
Die vollständige Struktur ergänzt das optionale voice-Flag, das einzige weitere Feld, das audio hat:
Codebeispiel
{
  "to": "+16505551234",
  "from": "+13124495648",
  "audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}
audio hat kein caption-Feld. from ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete.

Limits

FeldGrenzeGeprüft von
Dateigröße16 MBnur WhatsApp, beim Abruf (async)
FormatAAC, AMR, MP3, M4A oder OGG mit dem OPUS-Codec, mononur WhatsApp, beim Abruf (async)
voice: trueerfordert .ogg/OPUS, mono; andere Formate lassen die Transkription fehlschlagennur WhatsApp, beim Abruf (async)
captionkein gültiges FeldBird, bei Annahme (422, Schema-Ablehnung)
urlabsolut, https, hat einen Host, kein rohes LeerzeichenBird, bei Annahme (422)
Bird prüft die Form der URL, bevor etwas in die Warteschlange gestellt wird; es prüft weder die tatsächliche Dateigröße, das Format oder den Codec noch ob ein voice: true-Versand tatsächlich .ogg/OPUS ist. Das kann nur der eigene Abruf von WhatsApp zum Sendezeitpunkt. Eine caption bei einer Audionachricht mitzusenden ist kein Längenfehler; das Feld existiert im Schema dieses Arms nicht, daher schlägt es als unbekannte Eigenschaft fehl. Siehe im Hub Medien per URL senden und Wenn Medien fehlschlagen.

Eine eingehende Audionachricht lesen

Eine eingehende Audionachricht enthält dasselbe audio-Objekt, zusätzlich ein id und mime_type, die Bird beim Abruf der Datei ermittelt hat, und kein caption in beiden Richtungen. Siehe WhatsApp-Audio empfangen für die vollständige eingehende Struktur, die whatsapp.received-Payload und worauf Sie achten sollten.

Limits und Fehlerfälle

  • Das Kundenservice-Fenster muss offen sein. Audio ist eine Service-Nachricht, die nur innerhalb eines offenen Fensters zugestellt werden kann; siehe im Hub Kundenservice-Fenster.
  • Bird lehnt http ab; WhatsApp selbst würde es abrufen. Siehe im Hub Medien per URL senden für die vollständige Formprüfung.
  • Ein abgelehnter Abruf wird trotzdem berechnet. Siehe im Hub Wenn Medien fehlschlagen. Der spezifische Ablehnungstext von WhatsApp für Audio wurde nicht unabhängig gemessen; betrachten Sie die Zuordnung als per Symmetrie abgeleitet und nicht pro Ursache bestätigt.
  • Das voice-Flag ändert, wie der Client des Empfängers die Nachricht darstellt, nicht was Bird validiert. voice: true stellt sie als Sprachnotiz dar: automatischer Download, ein Inline-Mikrofon-Icon und Transkriptionsmöglichkeit. Dafür ist eine .ogg-Datei mit OPUS-Codec in mono nötig; jedes andere Format wird trotzdem gesendet, aber die Transkription schlägt auf Empfängerseite fehl. voice ist standardmäßig false.
  • Den Play-Icon-Schwellenwert und das "played"-Signal von WhatsApp macht Bird nicht zugänglich. WhatsApp dokumentiert ein Client-Verhalten bei kleinen Sprachnotizen und einen Abgespielt-Status, aber Bird bildet beides nicht ab; bauen Sie keine Integration, die erwartet, eines von beiden über die API zurückzulesen.
  • WhatsApp speichert eine abgerufene URL etwa 10 Minuten im Cache. Ein erneutes Senden derselben URL innerhalb dieses Zeitfensters liefert den ersten Abruf erneut aus; variieren Sie die URL, um einen neuen Abruf zu erzwingen.

Nächste Schritte