Mensagens de documento WhatsApp
Uma mensagem de documento carrega uma URL pública que WhatsApp busca no momento do envio, com uma legenda opcional e um nome de arquivo opcional. É o maior tipo de mídia, e o único que carrega tanto uma legenda quanto um nome de arquivo.
Enviar um documento
Defina document.url:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
document: { url: "https://cdn.example.com/invoices/a1b2c3.pdf" },
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
document={"url": "https://cdn.example.com/invoices/a1b2c3.pdf"},
)
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",
Document: &bird.WhatsAppDocumentSend{Url: "https://cdn.example.com/invoices/a1b2c3.pdf"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$document = (new WhatsAppMessageSendRequestDocument())
->setUrl('https://cdn.example.com/invoices/a1b2c3.pdf');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
document: $document,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--document https://cdn.example.com/invoices/a1b2c3.pdf \
--from +13124495648 \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
},
"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",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf"
}
}'A forma completa adiciona caption e filename:
Exemplo de código
{
"to": "+16505551234",
"from": "+13124495648",
"document": {
"url": "https://cdn.example.com/invoices/a1b2c3.pdf",
"caption": "Your invoice for order A1B2C3",
"filename": "invoice-a1b2c3.pdf"
}
}from é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado por Bird.
Limites
| Campo | Limite | Aplicado por |
|---|---|---|
| Tamanho do arquivo | 100 MB | Apenas WhatsApp, na busca (async) |
| Tipo de arquivo | PDF, Word, Excel, PowerPoint ou texto simples renderizam de forma confiável no cliente WhatsApp; outros tipos são transmitidos, mas não são suportados | Apenas WhatsApp, na busca (async) |
| caption | até 1.024 caracteres | Bird, no aceite (422) |
| filename | 1 a 100 caracteres | Bird, no aceite (422); esse limite é do próprio Bird, já que WhatsApp não documenta limite de nome de arquivo |
| url | absoluta, https, tem host, sem espaço bruto | Bird, no aceite (422) |
Bird verifica o formato da URL e o comprimento da legenda e do nome de arquivo antes de qualquer coisa ser enfileirada. Ele não verifica o tamanho nem o tipo real do arquivo; apenas a busca do próprio WhatsApp no momento do envio pode fazê-lo. Consulte no hub envio de mídia por URL e quando a mídia falha.
Leitura de um documento recebido
Um documento recebido carrega o mesmo objeto document, além de um id e mime_type que Bird aprendeu ao buscar o arquivo. Ambos estão ausentes em uma leitura de mensagem enviada, já que Bird nunca buscou o arquivo que enviou, e filename em um documento recebido é o que o dispositivo do contato forneceu. Consulte Recebendo documentos WhatsApp para a leitura completa do recebimento, o payload whatsapp.received e o que observar.
Limites e modos de falha
- A janela de atendimento ao cliente precisa estar aberta. Documentos são mensagens de serviço, entregáveis apenas dentro de uma janela aberta; consulte no hub a janela de atendimento ao cliente.
- Bird rejeita http; WhatsApp em si buscaria o arquivo. Consulte no hub o envio de mídia por URL para a verificação completa de formato.
- Uma busca rejeitada ainda é cobrada, e este é o tipo de mídia com maior probabilidade de encontrar isso. Com 100 MB, um documento é a maior coisa que você pode enviar, e Bird não verifica nada sobre os bytes reais no aceite. Consulte no hub quando a mídia falha para media_rejected e o fato da cobrança em caso de falha. O texto de rejeição específico de documento vindo de WhatsApp não foi medido de forma independente como o de imagem, então trate o mapeamento como inferido por simetria e não confirmado por causa.
- Omitir filename não significa que o destinatário não verá nenhum nome. WhatsApp deriva um nome a partir do caminho da URL, que pode ser um hash opaco ou slug em vez de algo legível. Defina filename explicitamente para controlar o que realmente aparece.
- O limite de 100 caracteres de filename é uma escolha do próprio Bird, não um limite de WhatsApp. WhatsApp não documenta nenhum limite de comprimento de nome de arquivo.
- WhatsApp mantém em cache uma URL buscada por cerca de 10 minutos. Reenviar a mesma URL dentro dessa janela serve novamente a primeira busca; varie a URL para forçar uma nova.
Próximos passos
- Mensagens de serviço WhatsApp: a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
- Imagens: para uma foto ou gráfico em vez de um arquivo
- Templates: para mensagens que você pode enviar depois que a janela for fechada
- Envio de mensagens WhatsApp: a estrutura da solicitação, o modelo 202 e tentativas seguras de reenvio
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