> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mensagem de Imagem

> Envie imagens com legenda opcional via WhatsApp e outros canais

# Mensagem de Imagem

O tipo `IMAGE` permite enviar imagens para o destinatário. Você pode fornecer a imagem via **Base64** ou via **URL de download**.

## Payload

```json theme={null}
{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "IMAGE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "caption": "Foto do produto",
    "filename": "produto.jpg",
    "mimetype": "image/jpeg"
  }
}
```

## Campos

<ParamField body="content.type" type="string" required>
  Deve ser `"IMAGE"`.
</ParamField>

<ParamField body="content.to" type="Address" required>
  Endereço do destinatário. Veja [formatos de endereço](/mensagens/visao-geral#enderecamento-address).
</ParamField>

<ParamField body="content.base64" type="string">
  Conteúdo da imagem codificado em Base64. Use este campo **ou** `downloadUrl`/`externalDownloadUrl`, não em conjunto. Limite de \~70MB no conteúdo decodificado.
</ParamField>

<ParamField body="content.downloadUrl" type="string">
  URL pública para download da imagem. A MessageFy fará o download e enviará ao destinatário. Alternativa ao `base64`.
</ParamField>

<ParamField body="content.externalDownloadUrl" type="string">
  URL externa de uma imagem já hospedada. Use para arquivos grandes (acima de \~70MB), em vez de `base64`. Também é o campo preenchido nas mensagens recebidas.
</ParamField>

<ParamField body="content.mediaId" type="string">
  Identificador da mídia no storage. Preenchido pela plataforma nas mensagens recebidas; normalmente não é necessário no envio.
</ParamField>

<ParamField body="content.downloadProviderUrl" type="string">
  URL de download da imagem no provedor. Preenchido nas mensagens recebidas; não é necessário no envio.
</ParamField>

<ParamField body="content.caption" type="string">
  Legenda exibida junto com a imagem. Opcional.
</ParamField>

<ParamField body="content.filename" type="string" required>
  Nome do arquivo (ex: `foto.jpg`). **Obrigatório** para mensagens de mídia -- a ausência
  retorna `400` com o erro "Filename is required for media messages".
</ParamField>

<ParamField body="content.mimetype" type="string">
  Tipo MIME da imagem. Recomendado informar para processamento correto.
</ParamField>

<Warning>
  O campo `base64` é validado pela API. Se o conteúdo não for um Base64 válido, a requisição será rejeitada com erro `"Invalid Base64 in media message."`. Para arquivos acima de \~70MB, envie por `externalDownloadUrl` em vez de `base64`, ou a requisição retorna `MEDIA_TOO_LARGE`.
</Warning>

## Formatos Suportados

| Formato | MIME Type    | Observação                        |
| ------- | ------------ | --------------------------------- |
| JPEG    | `image/jpeg` | Formato mais comum, amplo suporte |
| PNG     | `image/png`  | Suporte a transparência           |
| WebP    | `image/webp` | Formato otimizado para web        |

## Exemplos

### Enviar imagem via Base64

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: sua-api-key-aqui" \
    -d '{
      "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "content": {
        "type": "IMAGE",
        "to": {
          "type": "WHATSAPP",
          "number": "5511999999999"
        },
        "base64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAA...",
        "caption": "Comprovante de pagamento",
        "filename": "comprovante.jpg",
        "mimetype": "image/jpeg"
      }
    }'
  ```

  ```python Python theme={null}
  import requests
  import base64

  # Ler imagem e converter para Base64
  with open("comprovante.jpg", "rb") as f:
      image_base64 = base64.b64encode(f.read()).decode("utf-8")

  response = requests.post(
      "https://api-dev.messagefy.io/api/v1/message/SendMessage",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "sua-api-key-aqui"
      },
      json={
          "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "content": {
              "type": "IMAGE",
              "to": {
                  "type": "WHATSAPP",
                  "number": "5511999999999"
              },
              "base64": image_base64,
              "caption": "Comprovante de pagamento",
              "filename": "comprovante.jpg",
              "mimetype": "image/jpeg"
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  import { readFileSync } from "fs";

  const imageBase64 = readFileSync("comprovante.jpg").toString("base64");

  const response = await fetch(
    "https://api-dev.messagefy.io/api/v1/message/SendMessage",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key-aqui",
      },
      body: JSON.stringify({
        channelId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        content: {
          type: "IMAGE",
          to: {
            type: "WHATSAPP",
            number: "5511999999999",
          },
          base64: imageBase64,
          caption: "Comprovante de pagamento",
          filename: "comprovante.jpg",
          mimetype: "image/jpeg",
        },
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Enviar imagem via URL

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "IMAGE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/imagens/promocao-verao.png",
    "caption": "Promocao de verao - 30% de desconto!",
    "filename": "promocao-verao.png",
    "mimetype": "image/png"
  }
}
```

<Tip>
  Usar `downloadUrl` é mais eficiente para imagens grandes, pois evita o overhead de codificação Base64 no corpo da requisição. A URL deve ser publicamente acessível.
</Tip>

### Imagem sem legenda

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "IMAGE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/imagens/qrcode-pix.png",
    "filename": "qrcode-pix.png",
    "mimetype": "image/png"
  }
}
```

### Imagem como resposta a uma mensagem

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "IMAGE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/comprovantes/12345.jpg",
    "caption": "Segue o comprovante solicitado",
    "filename": "comprovante.jpg",
    "mimetype": "image/jpeg",
    "quotedMessage": {
      "messageId": "20CFBA298FAB68AA75D3B369EDB5C805",
      "participant": "5511999999999@s.whatsapp.net",
      "body": "Pode enviar o comprovante?",
      "type": "TEXT"
    }
  }
}
```

## Resposta

```json theme={null}
{
  "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

<Note>
  Após o envio, você receberá um webhook `MESSAGE_SENT` confirmando que a imagem foi enviada ao provedor, e um `MESSAGE_DELIVERED` quando o destinatário receber.
</Note>

## Recebimento

Quando um contato envia uma imagem para o seu canal, a MessageFy entrega um webhook com `content.type` igual a `"IMAGE"`. O conteúdo vem dentro do envelope `Package` (veja [Recebendo Eventos](/recebendo-eventos)).

```json theme={null}
{
  "packageId": "019a1234-5678-7abc-def0-123456789ac2",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "correlationId": null,
  "content": {
    "type": "IMAGE",
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Minha Empresa"
    },
    "messageId": "3EB08209536937A66D8435",
    "mediaId": "a1b2c3d4e5f6",
    "externalDownloadUrl": "https://storage.messagefy.io/media/a1b2c3d4e5f6.jpg?...",
    "caption": "Olha essa foto!",
    "filename": "foto_produto.jpg",
    "mimetype": "image/jpeg",
    "isFromMe": false,
    "isGroupMessage": false,
    "isForwarded": false,
    "isStatusMessage": false,
    "isHistoryMessage": false,
    "timestamp": "2025-12-01T14:36:00+00:00"
  },
  "timestamp": "2025-12-01T14:36:00.100+00:00",
  "echoMessage": false,
  "providerMetadata": null
}
```

<ResponseField name="content.type" type="string">
  Sempre `"IMAGE"` para imagens recebidas.
</ResponseField>

<ResponseField name="content.from" type="Address">
  Endereço de quem enviou a imagem. Para WhatsApp: `jid`, `lid`, `number`, `name`.
</ResponseField>

<ResponseField name="content.to" type="Address">
  Endereço do destinatário (o seu canal ou o grupo/chat que recebeu a mensagem).
</ResponseField>

<ResponseField name="content.messageId" type="string">
  Identificador da mensagem no provedor. Guarde-o para responder ou reagir posteriormente.
</ResponseField>

<ResponseField name="content.mediaId" type="string">
  Identificador da mídia no storage da plataforma.
</ResponseField>

<ResponseField name="content.externalDownloadUrl" type="string">
  URL para baixar a imagem recebida. Pode ainda não estar disponível no primeiro webhook enquanto a mídia é processada (veja abaixo).
</ResponseField>

<ResponseField name="content.caption" type="string">
  Legenda enviada junto com a imagem, quando houver.
</ResponseField>

<ResponseField name="content.filename" type="string">
  Nome do arquivo da imagem.
</ResponseField>

<ResponseField name="content.mimetype" type="string">
  Tipo MIME da imagem (ex: `image/jpeg`).
</ResponseField>

<ResponseField name="content.isGroupMessage" type="boolean">
  `true` quando a imagem veio de um grupo. Nesse caso, `from` identifica o participante autor.
</ResponseField>

<ResponseField name="content.isForwarded" type="boolean">
  `true` quando a imagem foi encaminhada.
</ResponseField>

<ResponseField name="content.isHistoryMessage" type="boolean">
  `true` quando a mensagem vem da sincronização de histórico do dispositivo.
</ResponseField>

<ResponseField name="content.isBroadcast" type="boolean">
  `true` se a mensagem foi enviada para uma lista de transmissão (broadcast list).
</ResponseField>

<ResponseField name="content.isAnnounceGroup" type="boolean">
  `true` se a mensagem foi enviada para um grupo de avisos da comunidade.
</ResponseField>

<ResponseField name="content.isCommunityNotices" type="boolean">
  `true` se a mensagem foi enviada para o grupo de avisos da comunidade.
</ResponseField>

<ResponseField name="content.isNewsletter" type="boolean">
  `true` se a mensagem foi enviada para um canal/newsletter.
</ResponseField>

<Note>
  A imagem pode chegar antes do download da mídia concluir. Quando `externalDownloadUrl` ainda não estiver preenchida, a URL de download é entregue depois pelo evento [`DOWNLOAD_AVAILABLE`](/recebendo-eventos), cujo campo `externalDownloadUrl` corresponde à mesma imagem (referenciada por `messageId`).
</Note>