Download de Midias Recebidas

Conceituacao

Quando um contato envia uma imagem, audio, video ou documento pelo WhatsApp, a Ogmma API processa a midia automaticamente e disponibiliza uma URL para download no payload do webhook.

Este guia mostra como acessar e baixar essas midias no N8N, com exemplos praticos e fluxos completos.

Pre-requisito

Certifique-se de que voce ja configurou o recebimento de webhooks no N8N antes de continuar.

Como Funciona

Quando uma mensagem com midia e recebida, a Ogmma executa o seguinte fluxo automaticamente:

Contato envia imagem/audio/video/documento pelo WhatsApp
                    |
                    v
    Ogmma Worker recebe a mensagem
                    |
                    v
    Worker baixa a midia do WhatsApp
                    |
                    v
    Worker faz upload para o armazenamento (S3)
                    |
                    v
    Mensagem salva no banco com URL da midia
                    |
                    v
    Webhook "message.received" disparado com mediaUrl pronta
                    |
                    v
    N8N recebe o evento com a URL para download

Voce nao precisa interagir com o WhatsApp diretamente. A midia ja esta disponivel para download quando o webhook chega ao N8N.

Payload do Webhook com Midia

Quando o evento message.received contem uma midia, o campo mediaUrl vem preenchido:

Exemplo: Imagem

{
  "event": "message.received",
  "timestamp": "2025-01-15T10:45:00.000Z",
  "data": {
    "messageId": "665f2b3c4d5e6f7a8b9c0d1e",
    "conversationId": "665e0b1a2c3d4e5f6a7b8c9d",
    "channelId": "665d9a0b1c2d3e4f5a6b7c8d",
    "from": "5511999998888",
    "type": "image",
    "content": "Segue o comprovante de pagamento",
    "mediaUrl": "https://oapi.ogmma.com.br/v1/media/665f2b3c4d5e6f7a8b9c0d1e",
    "contact": {
      "id": "665c8901a2b3c4d5e6f7a8b9",
      "name": "Joao Silva",
      "phone": "5511999998888"
    }
  }
}

Exemplo: Audio

{
  "event": "message.received",
  "timestamp": "2025-01-15T10:46:30.000Z",
  "data": {
    "messageId": "665f3c4d5e6f7a8b9c0d1e2f",
    "conversationId": "665e0b1a2c3d4e5f6a7b8c9d",
    "channelId": "665d9a0b1c2d3e4f5a6b7c8d",
    "from": "5511999998888",
    "type": "audio",
    "content": "",
    "mediaUrl": "https://oapi.ogmma.com.br/v1/media/665f3c4d5e6f7a8b9c0d1e2f",
    "contact": {
      "id": "665c8901a2b3c4d5e6f7a8b9",
      "name": "Joao Silva",
      "phone": "5511999998888"
    }
  }
}

Exemplo: Documento

{
  "event": "message.received",
  "timestamp": "2025-01-15T10:48:00.000Z",
  "data": {
    "messageId": "665f4d5e6f7a8b9c0d1e2f30",
    "conversationId": "665e0b1a2c3d4e5f6a7b8c9d",
    "channelId": "665d9a0b1c2d3e4f5a6b7c8d",
    "from": "5511999998888",
    "type": "document",
    "content": "Contrato assinado",
    "mediaUrl": "https://oapi.ogmma.com.br/v1/media/665f4d5e6f7a8b9c0d1e2f30",
    "contact": {
      "id": "665c8901a2b3c4d5e6f7a8b9",
      "name": "Joao Silva",
      "phone": "5511999998888"
    }
  }
}

Campos Relevantes

Campo	Tipo	Descricao
`data.type`	string	Tipo da mensagem: `text`, `image`, `video`, `audio`, `document`
`data.mediaUrl`	string \| null	URL para download da midia. `null` para mensagens de texto.
`data.content`	string	Legenda (caption) da midia, se houver. Vazio para audios sem legenda.

Endpoint de Download

`GET /v1/media/:messageId`

Este endpoint retorna a midia associada a uma mensagem.

Propriedade	Valor
URL	`https://oapi.ogmma.com.br/v1/media/{messageId}`
Metodo	`GET`
Autenticacao	Nao requerida
Resposta	`302 Redirect` para URL temporaria de download

Como funciona:

Recebe o messageId da mensagem
Busca a mensagem no banco de dados
Gera uma nova URL temporaria de download (presigned URL)
Redireciona (HTTP 302) para a URL temporaria

Sem autenticacao

O endpoint /v1/media/:messageId nao requer autenticacao. Basta acessar a URL com o messageId e o download comeca automaticamente. Isso facilita o uso em nodes HTTP do N8N e em tags HTML (<img>, <audio>, <video>).

Exemplo com cURL

curl -L "https://oapi.ogmma.com.br/v1/media/665f2b3c4d5e6f7a8b9c0d1e" \
  --output imagem.jpg

O flag -L faz o cURL seguir o redirect 302 automaticamente.

Respostas

Status	Descricao
`302`	Redirect para URL temporaria de download
`400`	Mensagem nao possui midia
`404`	Mensagem nao encontrada
`500`	Erro interno ao servir midia

Passo a Passo no N8N

Passo 1: Receber o Webhook

Use o Webhook node configurado para message.received (veja Receber Webhooks).

Passo 2: Verificar se a Mensagem tem Midia

Adicione um IF node para verificar se a mensagem contem midia:

Campo	Valor
Condicao	`{{ $json.data.mediaUrl }}` is not empty

[Webhook] --> [IF: tem mediaUrl?]
  --> Sim: [Download da midia]
  --> Nao: [Processar mensagem de texto]

Passo 3: Baixar a Midia

Adicione um HTTP Request node para baixar o arquivo:

Campo	Valor
Method	`GET`
URL	`{{ $json.data.mediaUrl }}`
Response Format	`File`
Output Field	`data`

Redirect automatico

O N8N segue redirects HTTP 302 automaticamente. Voce so precisa apontar para a mediaUrl e o download acontece.

Passo 4: Usar o Arquivo

Apos o download, o arquivo fica disponivel como binario no campo data. Voce pode:

Salvar no Google Drive: Conecte um node Google Drive com Upload File
Enviar por e-mail: Use um node Email com o arquivo como anexo
Salvar em disco: Use um node Write Binary File
Processar com IA: Envie para OpenAI Vision, Google Cloud Vision, etc.
Encaminhar para outro canal: Use o endpoint de envio de imagem da Ogmma API

Workflow Completo: Salvar Midias no Google Drive

Este exemplo salva automaticamente todas as midias recebidas em uma pasta do Google Drive.

Arquitetura

[Webhook: message.received]
    |
    v
[IF: tem mediaUrl?]
    |
    +--> Sim: [HTTP Request: download] --> [Google Drive: upload]
    |
    +--> Nao: [No Operation]

Configuracao Detalhada

1. Webhook Node

Campo	Valor
HTTP Method	`POST`
Path	`ogmma-media`
Response Mode	`Immediately`
Response Code	`200`

2. IF Node

Campo	Valor
Condicao	`{{ $json.data.type }}` is not equal to `text`

3. HTTP Request Node (Download)

Campo	Valor
Method	`GET`
URL	`{{ $json.data.mediaUrl }}`
Response Format	`File`
Output Field	`data`

4. Google Drive Node (Upload)

Campo	Valor
Operation	`Upload`
File Name	`{{ $('Webhook').item.json.data.contact.name }}_{{ $('Webhook').item.json.data.messageId }}.jpg`
Parent Folder	ID da pasta no Google Drive
Binary Property	`data`

Workflow Completo: Rotear por Tipo de Midia

Este exemplo processa cada tipo de midia de forma diferente.

Arquitetura

[Webhook: message.received]
    |
    v
[IF: tem mediaUrl?]
    |
    +--> Nao: [Processar texto]
    |
    +--> Sim: [Switch: tipo de midia]
                |
                +--> image    --> [HTTP Request: download] --> [Salvar/Processar imagem]
                +--> audio    --> [HTTP Request: download] --> [Transcrever audio]
                +--> document --> [HTTP Request: download] --> [Salvar documento]
                +--> video    --> [HTTP Request: download] --> [Salvar video]

Switch Node

Campo	Valor
Mode	`Rules`
Data Type	`String`
Value	`{{ $json.data.type }}`

Regras

#	Operacao	Valor	Saida
1	Equals	`image`	"Imagem"
2	Equals	`audio`	"Audio"
3	Equals	`document`	"Documento"
4	Equals	`video`	"Video"

Tipos de Midia Suportados

Tipo (`data.type`)	Formatos Comuns	Descricao
`image`	JPG, PNG, WebP, GIF	Fotos e imagens
`audio`	OGG, MP3, AAC, M4A	Mensagens de voz e audios
`video`	MP4, 3GP	Videos gravados ou encaminhados
`document`	PDF, DOCX, XLSX, CSV, TXT	Documentos e arquivos

Troubleshooting

mediaUrl retorna 404

messageId invalido? Verifique se o messageId do payload esta correto
Mensagem foi deletada? A midia pode ter sido removida do sistema

mediaUrl retorna 400

A mensagem existe mas nao possui midia (tipo text). Verifique o campo type antes de tentar o download.

Download retorna arquivo corrompido

Verifique se o Response Format do HTTP Request node esta como File (nao JSON ou Text)
Certifique-se de que o Output Field esta preenchido (ex: data)

Arquivo muito grande / timeout

O N8N tem limites de tamanho de arquivo dependendo do plano
Para arquivos grandes (videos longos, documentos pesados), considere salvar diretamente no Google Drive ou S3 usando os nodes nativos

Proximo Passo

Auto-Resposta -- combine download de midias com respostas automaticas
Workflows Avancados -- cenarios complexos com IA, transcricao de audio e OCR

Conceituacao​

Como Funciona​

Payload do Webhook com Midia​

Exemplo: Imagem​

Exemplo: Audio​

Exemplo: Documento​

Campos Relevantes​

Endpoint de Download​

GET /v1/media/:messageId​

Exemplo com cURL​

Respostas​

Passo a Passo no N8N​

Passo 1: Receber o Webhook​

Passo 2: Verificar se a Mensagem tem Midia​

Passo 3: Baixar a Midia​

Passo 4: Usar o Arquivo​

Workflow Completo: Salvar Midias no Google Drive​

Arquitetura​

Configuracao Detalhada​

1. Webhook Node​

2. IF Node​

3. HTTP Request Node (Download)​

4. Google Drive Node (Upload)​

Workflow Completo: Rotear por Tipo de Midia​

Arquitetura​

Switch Node​

Regras​

Tipos de Midia Suportados​

Troubleshooting​

mediaUrl retorna 404​

mediaUrl retorna 400​

Download retorna arquivo corrompido​

Arquivo muito grande / timeout​

Proximo Passo​

Conceituacao

Como Funciona

Payload do Webhook com Midia

Exemplo: Imagem

Exemplo: Audio

Exemplo: Documento

Campos Relevantes

Endpoint de Download

`GET /v1/media/:messageId`

Exemplo com cURL

Respostas

Passo a Passo no N8N

Passo 1: Receber o Webhook

Passo 2: Verificar se a Mensagem tem Midia

Passo 3: Baixar a Midia

Passo 4: Usar o Arquivo

Workflow Completo: Salvar Midias no Google Drive

Arquitetura

Configuracao Detalhada

1. Webhook Node

2. IF Node

3. HTTP Request Node (Download)

4. Google Drive Node (Upload)

Workflow Completo: Rotear por Tipo de Midia

Arquitetura

Switch Node

Regras

Tipos de Midia Suportados

Troubleshooting

mediaUrl retorna 404

mediaUrl retorna 400

Download retorna arquivo corrompido

Arquivo muito grande / timeout

Proximo Passo