Mensagens de áudio WhatsApp
Uma mensagem de áudio carrega uma URL pública que WhatsApp busca no momento do envio. Ela não tem legenda e pode, opcionalmente, ser renderizada como nota de voz.
Enviar uma mensagem de áudio
Defina 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"
}
}'A forma completa adiciona a flag opcional voice, o único outro campo que audio possui:
Exemplo de código
{
"to": "+16505551234",
"from": "+13124495648",
"audio": { "url": "https://cdn.example.com/voice/9f2e4a.ogg", "voice": true }
}audio não tem o campo caption. from é obrigatório em toda mensagem de serviço: um número que seu espaço de trabalho possui, não um gerenciado por Bird.
Limites
| Campo | Limite | Aplicado por |
|---|---|---|
| Tamanho do arquivo | 16 MB | Apenas WhatsApp, no fetch (async) |
| Formato | AAC, AMR, MP3, M4A ou OGG com o codec OPUS, mono | Apenas WhatsApp, no fetch (async) |
| voice: true | requer .ogg/OPUS, mono; outros formatos fazem a transcrição falhar | Apenas WhatsApp, no fetch (async) |
| caption | não é um campo válido | Bird, no accept (422, rejeição de schema) |
| url | absoluta, https, tem host, sem espaço bruto | Bird, no accept (422) |
Bird verifica a forma da URL antes de qualquer coisa ser enfileirada; não verifica o tamanho real do arquivo, o formato ou o codec, e não verifica se um envio voice: true é de fato .ogg/OPUS. Apenas o próprio fetch de WhatsApp no momento do envio consegue fazer isso. Enviar um caption em uma mensagem de áudio não é um erro de tamanho; o campo não existe no schema desse braço, então falha como propriedade não reconhecida. Veja no hub envio de mídia por URL e quando a mídia falha.
Leitura de uma mensagem de áudio recebida
Uma mensagem de áudio recebida carrega o mesmo objeto audio, além de um id e mime_type que Bird aprendeu ao buscar o arquivo, e nenhum caption em nenhuma direção. Veja Recebendo áudio WhatsApp para a leitura completa da entrada, o payload whatsapp.received e o que observar.
Limites e modos de falha
- A janela de atendimento ao cliente precisa estar aberta. Áudio é uma mensagem de serviço, entregável apenas dentro de uma janela aberta; veja no hub a janela de atendimento ao cliente.
- Bird rejeita http; WhatsApp mesmo buscaria o conteúdo. Veja no hub envio de mídia por URL para a verificação completa da forma.
- Um fetch rejeitado ainda é cobrado. Veja no hub quando a mídia falha. O texto de rejeição específico de áudio de WhatsApp não foi medido de forma independente, então trate o mapeamento como inferido por simetria e não confirmado por causa.
- A flag voice muda como o cliente do destinatário renderiza a mensagem, não o que Bird valida. voice: true renderiza como nota de voz: faz download automático, exibe um ícone de microfone inline e pode ser transcrita. Para funcionar corretamente, é preciso um arquivo .ogg codificado com OPUS, mono; qualquer outro formato ainda é enviado, mas a transcrição falha no lado do destinatário. voice tem o padrão false.
- O limiar do ícone de reprodução de WhatsApp e o sinal de "played" não são algo que Bird expõe. WhatsApp documenta um comportamento do cliente em torno de notas de voz curtas e um estado de reproduzido, mas Bird não modela nenhum dos dois; não construa uma integração que espere ler qualquer um deles de volta a partir da API.
- WhatsApp armazena em cache uma URL buscada por cerca de 10 minutos. Reenviar a mesma URL dentro dessa janela serve o primeiro fetch novamente; varie a URL para forçar uma nova busca.
Próximos passos
- Mensagens de serviço WhatsApp: a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
- Vídeo: para um clipe de vídeo em vez de áudio
- Stickers: outro braço de mídia sem campo de legenda
- Enviando mensagens WhatsApp: o envelope da solicitação, o modelo 202 e retentativas seguras
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação