# 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

```json
{
  "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"
}
```

| Campo       | O que contém                                                                     |
| ----------- | -------------------------------------------------------------------------------- |
| `id`        | O arquivo armazenado, para passar como `media_id` ao baixar os bytes             |
| `url`       | Uma URL Bird, acessada com sua chave API                                         |
| `mime_type` | O tipo de mídia que WhatsApp reportou para o arquivo, como `image/jpeg`          |
| `caption`   | O 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](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) 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](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) 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:

```json
{
  "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

- [Como o recebimento funciona](/docs/guides/whatsapp/receiving-whatsapp): o envelope de entrada, download de mídia e o webhook `whatsapp.received`
- [Mensagens de imagem WhatsApp](/docs/guides/whatsapp/message-types/images): o lado de envio do mesmo braço
- [Recebendo documentos](/docs/guides/whatsapp/receiving-whatsapp/documents): o mesmo formato de mídia, com o nome de arquivo do remetente
- [Eventos WhatsApp](/docs/guides/whatsapp/events): a lista completa de eventos, via API ou webhooks

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)