Sign inGet started

Mensagens de imagem WhatsApp

Uma mensagem de imagem carrega uma URL pública que WhatsApp busca no momento do envio, com uma legenda opcional abaixo dela.

Enviar uma imagem

Defina image.url:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);
A estrutura completa adiciona um caption opcional:
Exemplo de código
{
  "to": "+16505551234",
  "from": "+13124495648",
  "image": {
    "url": "https://cdn.example.com/receipts/a1b2c3.png",
    "caption": "Your receipt for order A1B2C3"
  }
}
image não tem o campo filename. 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 arquivo5 MBsomente WhatsApp, ao buscar (async)
Tipo de arquivoJPEG ou PNGsomente WhatsApp, ao buscar (async)
captionaté 1.024 caracteresBird, ao aceitar (422)
urlabsoluta, https, tem host, sem espaço brutoBird, ao aceitar (422)
Bird verifica o formato da URL e o comprimento da legenda antes de enfileirar qualquer coisa. Ele não verifica o tamanho ou tipo real do arquivo; somente a busca do WhatsApp no momento do envio pode fazer isso. Consulte envio de mídia por URL do hub para saber o que essa verificação de formato cobre, e quando a mídia falha para o que acontece quando a busca do WhatsApp rejeita o arquivo.

Lendo uma imagem recebida

Uma imagem recebida carrega o mesmo objeto image, mais um id e mime_type que Bird obteve ao buscar o arquivo. Ambos estão ausentes em uma leitura de mensagem enviada, já que Bird nunca buscou o arquivo que enviou. Consulte Recebendo imagens WhatsApp para a leitura completa de entrada, o payload whatsapp.received e o que observar.

Limites e modos de falha

  • A janela de atendimento ao cliente precisa estar aberta. Imagens são mensagens de serviço, entregáveis somente dentro de uma janela aberta; consulte a janela de atendimento ao cliente do hub.
  • Bird rejeita http; WhatsApp mesmo é que buscaria. Essa distinção, e o restante da verificação de formato da URL, estão em envio de mídia por URL do hub.
  • Um arquivo grande demais, um tipo MIME errado ou uma URL inacessível falham da mesma forma, e depois de você ser cobrado. Consulte quando a mídia falha do hub para media_rejected e o fato da cobrança em caso de falha.
  • WhatsApp armazena em cache uma URL buscada por cerca de 10 minutos. Reenviar a mesma URL dentro dessa janela reutiliza a primeira busca em vez de buscar novamente; altere a URL (um parâmetro de query, por exemplo) para forçar uma nova busca.

Próximos passos