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

> Envie documentos e arquivos como PDF, planilhas e outros formatos

# 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

```json theme={null}
{
  "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

<ParamField body="content.type" type="string" required>
  Deve ser `"DOCUMENT"`.
</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 do arquivo codificado em Base64. Use este campo **ou** `downloadUrl`. Limite aproximado de 70MB por mídia em Base64.
</ParamField>

<ParamField body="content.downloadUrl" type="string">
  URL pública para download do arquivo. Use este campo **ou** `base64`.
</ParamField>

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

<ParamField body="content.externalDownloadUrl" type="string">
  URL externa para download do arquivo. Alternativa a `base64`/`downloadUrl` quando o arquivo está hospedado fora do seu domínio.
</ParamField>

<ParamField body="content.downloadProviderUrl" type="string">
  URL de download gerada pelo provedor. Presente principalmente em mensagens recebidas; não precisa ser informada no envio.
</ParamField>

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

<ParamField body="content.filename" type="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`.
</ParamField>

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

<Warning>
  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.
</Warning>

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

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

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

### Enviar documento via Base64

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
  }
}
```

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

## Resposta

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

<ResponseField name="content.type" type="string">
  Sempre `"DOCUMENT"`.
</ResponseField>

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

<ResponseField name="content.to" type="Address">
  Endereço do destinatário (o seu canal).
</ResponseField>

<ResponseField name="content.messageId" type="string">
  Identificador da mensagem, útil para responder (quote) ou marcar como lida.
</ResponseField>

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

<ResponseField name="content.downloadUrl" type="string">
  URL para download do documento.
</ResponseField>

<ResponseField name="content.externalDownloadUrl" type="string">
  URL externa para download do documento.
</ResponseField>

<ResponseField name="content.downloadProviderUrl" type="string">
  URL de download gerada pelo provedor.
</ResponseField>

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

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

<ResponseField name="content.mimetype" type="string">
  Tipo MIME do documento (ex.: `application/pdf`).
</ResponseField>

<ResponseField name="content.isFromMe" type="boolean">
  `true` quando a mensagem foi enviada pelo próprio canal.
</ResponseField>

<ResponseField name="content.isGroupMessage" type="boolean">
  `true` quando o documento veio de um grupo.
</ResponseField>

<ResponseField name="content.isForwarded" type="boolean">
  `true` quando o documento foi encaminhado.
</ResponseField>

<ResponseField name="content.isStatusMessage" type="boolean">
  `true` quando a mensagem é um status (story).
</ResponseField>

<ResponseField name="content.isHistoryMessage" type="boolean">
  `true` quando a mensagem veio da sincronização de histórico.
</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>

<ResponseField name="content.timestamp" type="string">
  Data e hora da mensagem no formato ISO 8601.
</ResponseField>

<Note>
  Os campos do envelope (`packageId`, `correlationId`, `channelId`, `timestamp`, `providerMetadata`, `echoMessage`) são comuns a todos os webhooks. Veja [Recebendo Eventos](/recebendo-eventos) para a descrição completa do envelope `Package`.
</Note>

<Tip>
  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.
</Tip>