# 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`:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/message-types/images.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/message-types/images.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/message-types/images.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/message-types/images.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/message-types/images.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/message-types/images.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/message-types/images.curl.md)

A estrutura completa adiciona um `caption` opcional:

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

| Campo              | Limite                                        | Aplicado por                        |
| ------------------ | --------------------------------------------- | ----------------------------------- |
| Tamanho do arquivo | 5 MB                                          | somente WhatsApp, ao buscar (async) |
| Tipo de arquivo    | JPEG ou PNG                                   | somente WhatsApp, ao buscar (async) |
| `caption`          | até 1.024 caracteres                          | Bird, ao aceitar (`422`)            |
| `url`              | absoluta, `https`, tem host, sem espaço bruto | Bird, 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](/docs/guides/whatsapp/message-types#sending-media-by-url) do hub para saber o que essa verificação de formato cobre, e [quando a mídia falha](/docs/guides/whatsapp/message-types#when-media-fails) 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](/docs/guides/whatsapp/receiving-whatsapp/images) 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](/docs/guides/whatsapp/message-types#the-customer-service-window) 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](/docs/guides/whatsapp/message-types#sending-media-by-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](/docs/guides/whatsapp/message-types#when-media-fails) 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

- [Mensagens de serviço WhatsApp](/docs/guides/whatsapp/message-types): a janela de atendimento ao cliente e o modelo que toda mensagem de serviço compartilha
- [Vídeo](/docs/guides/whatsapp/message-types/video): a mesma estrutura para um clipe de vídeo
- [Documentos](/docs/guides/whatsapp/message-types/documents): para um PDF, planilha ou outro arquivo
- [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp): o envelope de solicitação, o modelo `202` e novas tentativas seguras

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