Sign inGet started

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);
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

CampoLimiteAplicado por
Tamanho do arquivo100 MBApenas WhatsApp, na busca (async)
Tipo de arquivoPDF, Word, Excel, PowerPoint ou texto simples renderizam de forma confiável no cliente WhatsApp; outros tipos são transmitidos, mas não são suportadosApenas WhatsApp, na busca (async)
captionaté 1.024 caracteresBird, no aceite (422)
filename1 a 100 caracteresBird, no aceite (422); esse limite é do próprio Bird, já que WhatsApp não documenta limite de nome de arquivo
urlabsoluta, https, tem host, sem espaço brutoBird, 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