> ## 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 Vídeo

> Envie vídeos com legenda opcional via WhatsApp e outros canais

# Mensagem de Vídeo

O tipo `VIDEO` permite enviar arquivos de vídeo para o destinatário, com legenda opcional.

## Payload

```json theme={null}
{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "VIDEO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/videos/tutorial.mp4",
    "caption": "Tutorial: como configurar sua conta",
    "filename": "tutorial-configuracao.mp4",
    "mimetype": "video/mp4"
  }
}
```

## Campos

<ParamField body="content.type" type="string" required>
  Deve ser `"VIDEO"`.
</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 vídeo codificado em Base64. Use este campo **ou** `downloadUrl`/`externalDownloadUrl`.
</ParamField>

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

<ParamField body="content.externalDownloadUrl" type="string">
  URL externa de download do vídeo. Alternativa a `downloadUrl`/`base64` quando o arquivo já está hospedado fora da sua aplicação.
</ParamField>

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

<ParamField body="content.filename" type="string" required>
  Nome do arquivo de vídeo. **Obrigatório** para mensagens de mídia -- a ausência retorna `400`.
</ParamField>

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

<ParamField body="content.isGIF" type="boolean" default="false">
  Quando `true`, o vídeo é enviado/identificado como GIF (reprodução curta em loop, sem áudio). Padrão `false`.
</ParamField>

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

<ParamField body="content.downloadProviderUrl" type="string">
  URL de download da mídia no provedor. Preenchido pela plataforma em mensagens **recebidas**.
</ParamField>

## Formatos Suportados

| Formato | MIME Type          | Observação                      |
| ------- | ------------------ | ------------------------------- |
| MP4     | `video/mp4`        | Formato mais compatível         |
| 3GP     | `video/3gpp`       | Formato legado, menor qualidade |
| AVI     | `video/x-msvideo`  | Suporte limitado                |
| MKV     | `video/x-matroska` | Suporte limitado                |

<Note>
  O formato **MP4 (H.264)** oferece a melhor compatibilidade entre dispositivos e provedores. Recomendamos usar este formato sempre que possível.
</Note>

## Exemplos

### Vídeo via URL com legenda

<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": "VIDEO",
        "to": {
          "type": "WHATSAPP",
          "number": "5511999999999"
        },
        "downloadUrl": "https://cdn.suaempresa.com/videos/demo-produto.mp4",
        "caption": "Veja nosso novo produto em acao!",
        "filename": "demo-produto.mp4",
        "mimetype": "video/mp4"
      }
    }'
  ```

  ```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": "VIDEO",
              "to": {
                  "type": "WHATSAPP",
                  "number": "5511999999999"
              },
              "downloadUrl": "https://cdn.suaempresa.com/videos/demo-produto.mp4",
              "caption": "Veja nosso novo produto em acao!",
              "filename": "demo-produto.mp4",
              "mimetype": "video/mp4"
          }
      }
  )
  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: "VIDEO",
          to: {
            type: "WHATSAPP",
            number: "5511999999999",
          },
          downloadUrl: "https://cdn.suaempresa.com/videos/demo-produto.mp4",
          caption: "Veja nosso novo produto em acao!",
          filename: "demo-produto.mp4",
          mimetype: "video/mp4",
        },
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Vídeo via Base64

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "VIDEO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZj...",
    "caption": "Video de apresentacao do imovel",
    "filename": "imovel-tour.mp4",
    "mimetype": "video/mp4"
  }
}
```

### Vídeo sem legenda

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "VIDEO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/videos/instrucoes-montagem.mp4",
    "filename": "instrucoes-montagem.mp4",
    "mimetype": "video/mp4"
  }
}
```

### Vídeo como GIF

Defina `isGIF` como `true` para enviar o vídeo como GIF (loop curto, sem áudio).

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "VIDEO",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "downloadUrl": "https://cdn.suaempresa.com/videos/promo-loop.mp4",
    "isGIF": true,
    "filename": "promo-loop.mp4",
    "mimetype": "video/mp4"
  }
}
```

<Warning>
  Vídeos muito grandes podem demorar para serem processados e enviados. O WhatsApp tem um limite de aproximadamente **16 MB** para vídeos. Considere comprimir ou reduzir a resolução de vídeos longos antes de enviar.
</Warning>

<Tip>
  Para vídeos grandes, sempre use `downloadUrl` em vez de `base64`. Codificar vídeos em Base64 aumenta o tamanho do payload em cerca de 33%, além de consumir mais memória na sua aplicação.
</Tip>

## Resposta

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

## Recebimento

Quando o seu canal recebe um vídeo, a plataforma entrega um webhook com `content.type` igual a `VIDEO`. O envelope segue a [estrutura comum de mensagens recebidas](/mensagens/visao-geral) e o `content` traz os campos de mídia abaixo.

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

<ResponseField name="content.from" type="Address">
  Endereço de quem enviou o vídeo. No 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 recebida. Guarde-o para responder ou citar posteriormente.
</ResponseField>

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

<ResponseField name="content.filename" type="string">
  Nome do arquivo de vídeo.
</ResponseField>

<ResponseField name="content.mimetype" type="string">
  Tipo MIME do vídeo (ex.: `video/mp4`).
</ResponseField>

<ResponseField name="content.isGIF" type="boolean">
  `true` quando o vídeo recebido é um GIF.
</ResponseField>

<ResponseField name="content.mediaId" type="string">
  Identificador da mídia no storage, usado para baixar o conteúdo.
</ResponseField>

<ResponseField name="content.downloadUrl" type="string">
  URL para download do vídeo, quando disponível.
</ResponseField>

<ResponseField name="content.externalDownloadUrl" type="string">
  URL externa para download do vídeo, quando disponível.
</ResponseField>

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

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

<ResponseField name="content.isStatusMessage" type="boolean">
  `true` quando a mensagem é proveniente de um Status.
</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.quotedMessage" type="object">
  Presente quando o vídeo é resposta a outra mensagem. Veja [Mensagem de Texto](/mensagens/texto#respondendo-a-uma-mensagem-quote-reply).
</ResponseField>

<Note>
  O conteúdo binário do vídeo **não** vem embutido no webhook. Use `mediaId`, `downloadUrl` ou `externalDownloadUrl` para obter o arquivo. Quando a mídia ainda está sendo processada, a URL de download é entregue posteriormente pelo evento [`DOWNLOAD_AVAILABLE`](/recebendo-eventos) (campo `externalDownloadUrl`).
</Note>

### Exemplo de webhook recebido

```json theme={null}
{
  "packageId": "019a1234-5678-7abc-def0-123456789ac2",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "correlationId": null,
  "content": {
    "type": "VIDEO",
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999998888@s.whatsapp.net",
      "lid": "271283019378755@lid",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Minha Empresa"
    },
    "messageId": "3EB08209536937A66D8435",
    "mediaId": "01948f2c-9c1a-7d3e-b2a4-6f0e5c8a1d90",
    "downloadUrl": "https://storage.messagefy.io/media/01948f2c-9c1a-7d3e-b2a4-6f0e5c8a1d90.mp4",
    "caption": "Veja o produto funcionando!",
    "filename": "demo-cliente.mp4",
    "mimetype": "video/mp4",
    "isGIF": false,
    "isFromMe": false,
    "isForwarded": false,
    "isGroupMessage": false,
    "isStatusMessage": false,
    "isHistoryMessage": false,
    "deliveryStrategy": 0,
    "priority": 0,
    "deliveryDeadline": null,
    "timestamp": "2025-12-01T14:36:00+00:00"
  },
  "timestamp": "2025-12-01T14:36:00.1000000+00:00",
  "providerMetadata": null
}
```