Mensagem de Documento

O tipo DOCUMENT permite enviar arquivos e documentos para o destinatário. Ideal para envio de PDFs, planilhas, contratos e qualquer outro tipo de arquivo.

Payload

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "DOCUMENT",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/docs/contrato.pdf",
    "caption": "Contrato de prestacao de servicos",
    "filename": "contrato-servicos.pdf",
    "mimetype": "application/pdf"
  }
}

Campos

string

required

Deve ser "DOCUMENT".

Address

required

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

string

Conteúdo do arquivo codificado em Base64. Use este campo ou downloadUrl. Limite aproximado de 70MB por mídia em Base64.

string

URL pública para download do arquivo. Use este campo ou base64.

string

Identificador da mídia já armazenada na plataforma. Preenchido pela plataforma nas mensagens recebidas; no envio, normalmente não é informado.

string

URL externa para download do arquivo. Alternativa a base64/downloadUrl quando o arquivo está hospedado fora do seu domínio.

string

URL de download gerada pelo provedor. Presente principalmente em mensagens recebidas; não precisa ser informada no envio.

string

Legenda exibida junto com o documento. Opcional.

string

required

Nome do arquivo com extensão. Este nome será exibido para o destinatário ao receber o documento. Obrigatório para mensagens de mídia — a ausência retorna 400.

string

Tipo MIME do documento. Recomendado informar para processamento correto.

O campo filename é essencial para documentos. Sem ele, o destinatário pode receber o arquivo sem nome ou com um nome genérico, dificultando a identificação do conteúdo.

Formatos Comuns

Formato	MIME Type	Extensão
PDF	`application/pdf`	`.pdf`
Word	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	`.docx`
Excel	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	`.xlsx`
CSV	`text/csv`	`.csv`
ZIP	`application/zip`	`.zip`
Texto	`text/plain`	`.txt`

Exemplos

Enviar PDF via URL

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": "DOCUMENT",
      "to": {
        "type": "WHATSAPP",
        "number": "5511999999999"
      },
      "downloadUrl": "https://cdn.suaempresa.com/faturas/fatura-2026-04.pdf",
      "caption": "Fatura referente a abril/2026",
      "filename": "fatura-abril-2026.pdf",
      "mimetype": "application/pdf"
    }
  }'

import requests

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": "DOCUMENT",
            "to": {
                "type": "WHATSAPP",
                "number": "5511999999999"
            },
            "downloadUrl": "https://cdn.suaempresa.com/faturas/fatura-2026-04.pdf",
            "caption": "Fatura referente a abril/2026",
            "filename": "fatura-abril-2026.pdf",
            "mimetype": "application/pdf"
        }
    }
)
print(response.json())

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: "DOCUMENT",
        to: {
          type: "WHATSAPP",
          number: "5511999999999",
        },
        downloadUrl: "https://cdn.suaempresa.com/faturas/fatura-2026-04.pdf",
        caption: "Fatura referente a abril/2026",
        filename: "fatura-abril-2026.pdf",
        mimetype: "application/pdf",
      },
    }),
  }
);
const data = await response.json();
console.log(data);

Enviar documento via Base64

{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "DOCUMENT",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "base64": "JVBERi0xLjcKCjEgMCBvYmoKPDwKL1R5cGUg...",
    "caption": "Relatorio mensal de vendas",
    "filename": "relatorio-vendas-abril.pdf",
    "mimetype": "application/pdf"
  }
}

Enviar planilha Excel

{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "DOCUMENT",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/relatorios/estoque.xlsx",
    "caption": "Planilha de controle de estoque atualizada",
    "filename": "controle-estoque.xlsx",
    "mimetype": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
  }
}

Para documentos grandes, prefira usar downloadUrl em vez de base64. Isso reduz significativamente o tamanho da requisição HTTP e melhora a performance.

Resposta

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

Recebimento

Quando um contato envia um documento para o seu canal, a plataforma entrega um webhook com content.type igual a DOCUMENT. O arquivo não vem embutido no corpo do webhook: use os campos de download (downloadUrl / externalDownloadUrl) ou o mediaId para obtê-lo.

{
  "packageId": "019a1234-5678-7abc-def0-123456789abc",
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": null,
  "content": {
    "type": "DOCUMENT",
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999999999@s.whatsapp.net",
      "number": "5511999999999",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Minha Empresa"
    },
    "messageId": "3EB08209536937A66D8436",
    "isFromMe": false,
    "isGroupMessage": false,
    "isForwarded": false,
    "isStatusMessage": false,
    "isHistoryMessage": false,
    "mediaId": "e2b1c9a0-4c2f-4c8a-9f1e-7b6d5a4c3b2a",
    "downloadUrl": "https://storage.messagefy.io/media/e2b1c9a0-contrato.pdf",
    "externalDownloadUrl": "https://storage.messagefy.io/media/e2b1c9a0-contrato.pdf",
    "caption": "Segue o contrato assinado",
    "filename": "contrato-assinado.pdf",
    "mimetype": "application/pdf",
    "timestamp": "2025-12-01T14:37:00+00:00"
  },
  "timestamp": "2025-12-01T14:37:00.100+00:00",
  "providerMetadata": null
}

Campos recebidos

string

Sempre "DOCUMENT".

Address

Endereço de quem enviou o documento. Para WhatsApp, traz jid, lid, number e name.

Address

Endereço do destinatário (o seu canal).

string

Identificador da mensagem, útil para responder (quote) ou marcar como lida.

string

Identificador da mídia armazenada na plataforma.

string

URL para download do documento.

string

URL externa para download do documento.

string

URL de download gerada pelo provedor.

string

Legenda enviada junto com o documento, quando houver.

string

Nome do arquivo recebido.

string

Tipo MIME do documento (ex.: application/pdf).

boolean

true quando a mensagem foi enviada pelo próprio canal.

boolean

true quando o documento veio de um grupo.

boolean

true quando o documento foi encaminhado.

boolean

true quando a mensagem é um status (story).

boolean

true quando a mensagem veio da sincronização de histórico.

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.

string

Data e hora da mensagem no formato ISO 8601.

Os campos do envelope (packageId, correlationId, channelId, timestamp, providerMetadata, echoMessage) são comuns a todos os webhooks. Veja Recebendo Eventos para a descrição completa do envelope Package.

A mídia pode ainda estar em processamento no momento do webhook. Nesse caso, aguarde o evento DOWNLOAD_AVAILABLE, cujo externalDownloadUrl corresponde à URL de download do documento.

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 Documento

Mensagem de Documento

Payload

Campos

Formatos Comuns

Exemplos

Enviar PDF via URL

Enviar documento via Base64

Enviar planilha Excel

Resposta

Recebimento

Campos recebidos

​Mensagem de Documento

​Payload

​Campos

​Formatos Comuns

​Exemplos

​Enviar PDF via URL

​Enviar documento via Base64

​Enviar planilha Excel

​Resposta

​Recebimento

​Campos recebidos

Mensagem de Documento

Payload

Campos

Formatos Comuns

Exemplos

Enviar PDF via URL

Enviar documento via Base64

Enviar planilha Excel

Resposta

Recebimento

Campos recebidos