Documentação
Sign inGet started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Recebendo imagens WhatsApp

Uma foto ou imagem que um contato envia chega como uma mensagem recebida contendo image: uma referência ao arquivo que Bird armazenou para você, além da legenda que ele digitou abaixo dela.

O que uma imagem recebida contém

Exemplo de código
{
  "id": "wam_01kya19eknftrs2s6p82asmvnh",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "image": {
    "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
    "mime_type": "image/jpeg",
    "caption": "Is this the right part?"
  },
  "created_at": "2026-08-25T09:04:11Z"
}
CampoO que contém
idO arquivo armazenado, para passar como media_id ao baixar os bytes
urlUma URL Bird, acessada com sua chave API
mime_typeO tipo de mídia que WhatsApp reportou para o arquivo, como image/jpeg
captionO texto que o contato digitou abaixo da imagem; ausente quando não enviou nenhum
id e mime_type aparecem apenas em uma imagem recebida: Bird descobre ambos ao baixar o arquivo, e nunca armazenou o que você enviou. Uma imagem enviada retorna com o url que você forneceu e sem id.
Trate mime_type como um relato de WhatsApp e não como uma garantia, e use-o como critério em vez da extensão do arquivo em url, que não contém nenhuma.

Baixando os bytes

url e id apontam para o mesmo arquivo armazenado: passe o ID da mensagem e o id de mídia para o método de mídia do canal, em qualquer SDK, no CLI ou via cURL. A seção baixando mídia recebida do hub traz essa chamada em todas as linguagens, junto com as regras de redirecionamento e cabeçalho que ela segue.
A mensagem e sua mídia expiram juntas, 30 dias após a chegada da mensagem; a seção baixando mídia recebida do hub define essa janela e o que as leituras retornam após ela passar. Armazene qualquer imagem de que você precise por mais tempo enquanto a mensagem ainda estiver legível.

O payload do webhook

whatsapp.received carrega o braço image no envelope do evento, referência de mídia e tudo mais:
Exemplo de código
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:04:11.118Z",
  "data": {
    "whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "image": {
      "id": "waf_01kyb2m4xq7whs0d8n3prv6tez",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kya19eknftrs2s6p82asmvnh/media/waf_01kyb2m4xq7whs0d8n3prv6tez",
      "mime_type": "image/jpeg",
      "caption": "Is this the right part?"
    },
    "tags": null,
    "metadata": null
  }
}
O webhook dispara quando a mensagem chega, que também é quando a janela de retenção começa, então um endpoint que enfileira o download em vez de fazê-lo inline tem a janela inteira para se recuperar.

Pontos de atenção

  • A legenda pertence ao contato. Ela chega como texto simples, sem formatação ou informação de entidades, então renderize-a como texto.
  • Uma imagem por mensagem. Um contato que envia várias fotos produz várias mensagens recebidas, cada uma com seu próprio id e sua própria referência de mídia. Agrupe-as por from e horário de chegada; nenhum array as reúne.

Próximos passos

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