# Recebendo documentos WhatsApp

Um PDF, planilha ou qualquer outro arquivo que um contato anexa chega como uma mensagem recebida contendo `document`: a referência de mídia compartilhada, mais o nome que o próprio dispositivo dele deu ao arquivo.

## O que um documento recebido contém

```json
{
  "id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "document": {
    "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
    "mime_type": "application/pdf",
    "filename": "invoice-A1B2C3.pdf"
  },
  "created_at": "2026-08-25T09:15:02Z"
}
```

| Campo       | O que contém                                                                            |
| ----------- | --------------------------------------------------------------------------------------- |
| `id`        | O arquivo armazenado, para passar como `media_id` ao buscar os bytes                    |
| `url`       | Uma URL Bird, buscada com sua chave API                                                 |
| `mime_type` | O tipo de mídia que WhatsApp reportou para o arquivo, como `application/pdf`            |
| `filename`  | O nome que o remetente deu ao arquivo; ausente quando a mensagem não trouxe nenhum      |
| `caption`   | O texto que o contato digitou abaixo do documento; ausente quando ele não enviou nenhum |

`filename` é o único campo que o lado de envio e o lado de recebimento usam de forma diferente: em um envio, é o nome que você quer exibir no chat; em uma mensagem recebida, é o que o dispositivo do contato forneceu.

## Buscando os bytes

Passe o ID da mensagem e o `id` da mídia para o método de mídia do canal. O guia [buscando mídia recebida](/docs/guides/whatsapp/receiving-whatsapp#fetching-inbound-media) traz essa chamada em todas as linguagens, junto com as regras de redirecionamento e cabeçalho que ela segue, e define a janela de retenção em que o arquivo fica disponível.

**Não grave `filename` em disco assim que chegar.** É texto controlado por um atacante vindo de um remetente não autenticado: pode conter separadores de caminho, sequências de travessia, uma segunda extensão enganosa ou um nome que colide com um arquivo que você já possui. Gere sua própria chave de armazenamento a partir do `id` da mídia, mantenha `filename` como rótulo de exibição e decida o que fazer com o arquivo a partir de `mime_type`, não da extensão que o nome alega.

## O payload do webhook

`whatsapp.received` contém o braço `document` no envelope de evento:

```json
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:15:02.336Z",
  "data": {
    "whatsapp_id": "wam_01kyd6s0qfxv8t4k7n1yze6rhc",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "document": {
      "id": "waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "url": "https://platform.bird.com/v1/whatsapp/messages/wam_01kyd6s0qfxv8t4k7n1yze6rhc/media/waf_01kyd5p6zs9yju2f0p5rtx8vgb",
      "mime_type": "application/pdf",
      "filename": "invoice-A1B2C3.pdf"
    },
    "tags": null,
    "metadata": null
  }
}
```

Um fluxo de sinistros ou onboarding que coleta documentação pode rotear pelo `mime_type` aqui e enfileirar a busca, já que os bytes continuam disponíveis por toda a janela de retenção.

## Pontos de atenção

- **`mime_type` é o que WhatsApp reporta sobre o arquivo e não diz nada sobre o que há dentro dele.** Escaneie tudo o que você aceitar de um contato e valide a estrutura interna do arquivo antes de analisá-lo.
- **Legenda e nome de arquivo são campos diferentes.** Um contato que digita uma nota ao anexar o arquivo preenche `caption`; `filename` ainda vem do dispositivo dele.

## Próximos passos

- [Como o recebimento funciona](/docs/guides/whatsapp/receiving-whatsapp): o envelope de entrada, busca de mídia e o webhook `whatsapp.received`
- [Mensagens de documento WhatsApp](/docs/guides/whatsapp/message-types/documents): o lado de envio do mesmo braço
- [Recebendo imagens](/docs/guides/whatsapp/receiving-whatsapp/images): o mesmo formato de mídia para a foto de um documento
- [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)