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);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
audio={"url": "https://cdn.example.com/vm/9f2.ogg"},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Audio: &bird.WhatsAppAudioSend{Url: "https://cdn.example.com/vm/9f2.ogg"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$audio = (new WhatsAppMessageSendRequestAudio())
->setUrl('https://cdn.example.com/vm/9f2.ogg');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
audio: $audio,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--audio https://cdn.example.com/vm/9f2.ogg \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"audio": {
"url": "https://cdn.example.com/vm/9f2.ogg"
},
"from": "+13124495648",
"to": "+16505551234"
}
}curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"audio": {
"url": "https://cdn.example.com/vm/9f2.ogg"
}
}'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
| Feld | Grenze | Geprüft von |
|---|---|---|
| Dateigröße | 16 MB | nur WhatsApp, beim Abruf (async) |
| Format | AAC, AMR, MP3, M4A oder OGG mit dem OPUS-Codec, mono | nur WhatsApp, beim Abruf (async) |
| voice: true | erfordert .ogg/OPUS, mono; andere Formate lassen die Transkription fehlschlagen | nur WhatsApp, beim Abruf (async) |
| caption | kein gültiges Feld | Bird, bei Annahme (422, Schema-Ablehnung) |
| url | absolut, https, hat einen Host, kein rohes Leerzeichen | Bird, 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
- WhatsApp-Service-Nachrichten: das Kundenservice-Fenster und das Modell, das alle Service-Nachrichten teilen
- Video: für einen Videoclip statt Audio
- Sticker: ein weiterer Media-Arm ohne Bildunterschrift-Feld
- WhatsApp-Nachrichten senden: der Request-Envelope, das 202-Modell und sicheres erneutes Versuchen
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten