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

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

string

required

Deve ser "IMAGE".

Address

required

Endereço do destinatário. Veja formatos de endereço.

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.

string

URL pública para download da imagem. A MessageFy fará o download e enviará ao destinatário. Alternativa ao base64.

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.

string

Identificador da mídia no storage. Preenchido pela plataforma nas mensagens recebidas; normalmente não é necessário no envio.

string

URL de download da imagem no provedor. Preenchido nas mensagens recebidas; não é necessário no envio.

string

Legenda exibida junto com a imagem. Opcional.

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”.

string

Tipo MIME da imagem. Recomendado informar para processamento correto.

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.

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

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"
    }
  }'

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

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

Enviar imagem via URL

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

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.

Imagem sem legenda

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

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

{
  "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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.

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

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

string

Sempre "IMAGE" para imagens recebidas.

Address

Endereço de quem enviou a imagem. Para WhatsApp: jid, lid, number, name.

Address

Endereço do destinatário (o seu canal ou o grupo/chat que recebeu a mensagem).

string

Identificador da mensagem no provedor. Guarde-o para responder ou reagir posteriormente.

string

Identificador da mídia no storage da plataforma.

string

URL para baixar a imagem recebida. Pode ainda não estar disponível no primeiro webhook enquanto a mídia é processada (veja abaixo).

string

Legenda enviada junto com a imagem, quando houver.

string

Nome do arquivo da imagem.

string

Tipo MIME da imagem (ex: image/jpeg).

boolean

true quando a imagem veio de um grupo. Nesse caso, from identifica o participante autor.

boolean

true quando a imagem foi encaminhada.

boolean

true quando a mensagem vem da sincronização de histórico do dispositivo.

boolean

true se a mensagem foi enviada para uma lista de transmissão (broadcast list).

boolean

true se a mensagem foi enviada para um grupo de avisos da comunidade.

boolean

true se a mensagem foi enviada para o grupo de avisos da comunidade.

true se a mensagem foi enviada para um canal/newsletter.

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, cujo campo externalDownloadUrl corresponde à mesma imagem (referenciada por messageId).

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Mensagem de Imagem

Mensagem de Imagem

Payload

Campos

Formatos Suportados

Exemplos

Enviar imagem via Base64

Enviar imagem via URL

Imagem sem legenda

Imagem como resposta a uma mensagem

Resposta

Recebimento

​Mensagem de Imagem

​Payload

​Campos

​Formatos Suportados

​Exemplos

​Enviar imagem via Base64

​Enviar imagem via URL

​Imagem sem legenda

​Imagem como resposta a uma mensagem

​Resposta

​Recebimento

Mensagem de Imagem

Payload

Campos

Formatos Suportados

Exemplos

Enviar imagem via Base64

Enviar imagem via URL

Imagem sem legenda

Imagem como resposta a uma mensagem

Resposta

Recebimento