Sign inGet started

Wiadomości audio WhatsApp

Wiadomość audio zawiera publiczny URL, który WhatsApp pobiera w momencie wysyłki. Nie ma podpisu i opcjonalnie może być wyświetlona jako notatka głosowa.

Wyślij wiadomość audio

Ustaw 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);
Pełna struktura dodaje opcjonalną flagę voice, jedyne dodatkowe pole, które ma audio:
Przykład kodu
{
  "to": "+16505551234",
  "from": "+13124495648",
  "audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}
audio nie ma w ogóle pola caption. from jest wymagane w każdej wiadomości serwisowej: numer należący do Twojego obszaru roboczego, nie zarządzany przez Bird.

Limity

PoleOgraniczenieWymuszane przez
Rozmiar pliku16 MBtylko WhatsApp, przy pobraniu (async)
FormatAAC, AMR, MP3, M4A lub OGG z kodekiem OPUS, monotylko WhatsApp, przy pobraniu (async)
voice: truewymaga .ogg/OPUS, mono; inne formaty powodują niepowodzenie transkrypcjitylko WhatsApp, przy pobraniu (async)
captionnieprawidłowe poleBird, przy przyjęciu (422, odrzucenie schematu)
urlbezwzględny, https, ma hosta, bez surowych spacjiBird, przy przyjęciu (422)
Bird sprawdza strukturę URL-a, zanim cokolwiek zostanie zakolejkowane; nie weryfikuje rzeczywistego rozmiaru pliku, formatu ani kodeka i nie sprawdza, czy wysyłka voice: true to faktycznie .ogg/OPUS. Może to zrobić tylko samo pobranie przez WhatsApp w momencie wysyłki. Wysłanie caption w wiadomości audio to nie błąd długości: to pole nie istnieje w schemacie tego wariantu, więc kończy się odrzuceniem jako nierozpoznana właściwość. Zobacz w hubie wysyłanie mediów przez URL i gdy media się nie dostarczą.

Odczyt przychodzącej wiadomości audio

Przychodząca wiadomość audio zawiera ten sam obiekt audio, a dodatkowo id i mime_type, które Bird poznał po pobraniu pliku, i żadnego caption w żadnym kierunku. Zobacz Odbieranie audio WhatsApp, aby poznać pełny odczyt przychodzący, ładunek whatsapp.received i na co uważać.

Limity i tryby awarii

  • Okno obsługi klienta musi być otwarte. Audio to wiadomość serwisowa, dostarczalna tylko w otwartym oknie; zobacz w hubie okno obsługi klienta.
  • Bird odrzuca http; WhatsApp samo by go pobrało. Zobacz w hubie wysyłanie mediów przez URL, aby poznać pełną walidację struktury.
  • Odrzucone pobranie i tak jest naliczane. Zobacz w hubie gdy media się nie dostarczą. Tekst odrzucenia audio od WhatsApp nie został niezależnie zmierzony, więc traktuj mapowanie jako wywnioskowane przez symetrię, a nie potwierdzone dla każdej przyczyny.
  • Flaga voice zmienia sposób renderowania wiadomości w kliencie odbiorcy, a nie to, co waliduje Bird. voice: true renderuje ją jako notatkę głosową: automatycznie pobiera, wyświetla ikonę mikrofonu inline i umożliwia transkrypcję. Wymaga to pliku .ogg zakodowanego w OPUS, mono; każdy inny format nadal się wysyła, ale transkrypcja po stronie odbiorcy nie działa. voice domyślnie przyjmuje false.
  • Próg ikony odtwarzania i sygnał "played" po stronie WhatsApp nie są udostępniane przez Bird. WhatsApp dokumentuje zachowanie klienta dotyczące krótkich notatek głosowych i stanu odtworzenia, ale Bird nie modeluje żadnego z nich; nie buduj integracji, która oczekuje odczytu któregokolwiek z nich z API.
  • WhatsApp buforuje pobrany URL przez około 10 minut. Ponowne wysłanie identycznego URL-a w tym oknie zwraca wynik pierwszego pobrania; zmień URL, aby wymusić nowe pobranie.

Następne kroki