WHATSAPP SEND MEDIA - Enviar Mídia (Imagem, Vídeo, Documento, Áudio)

O que é este Node?

O WHATSAPP SEND MEDIA é o node responsável por enviar arquivos de mídia pelo WhatsApp Business API: imagens, vídeos, documentos, áudios e stickers.

Por que este Node existe?

Comunicação rica requer mais que texto. O SEND MEDIA existe para:

Compartilhar documentos: Enviar PDFs, planilhas, contratos, faturas
Enviar comprovantes: Imagens de pagamento, recibos, fotos
Compartilhar vídeos: Tutoriais, demonstrações, campanhas
Enviar áudios: Mensagens de voz personalizadas, notificações
Catálogos visuais: Fotos de produtos, portfolios, cardápios
Onboarding: Guias visuais, manuais em PDF, vídeos explicativos

Como funciona internamente?

Quando o SEND MEDIA é executado, o sistema:

Valida credenciais: Verifica accessToken e phoneNumberId
Identifica tipo de mídia: Determina se é image, video, document ou audio
Valida URL ou ID: Confirma que mediaUrl ou mediaId está presente
Formata payload: Estrutura JSON com tipo de mídia específico
Adiciona caption: Inclui legenda se fornecida
Envia requisição: POST para WhatsApp Graph API
Retorna resultado: Confirma envio com ID da mensagem

Código interno (whatsapp-meta-executor.service.ts:393-434):

private async sendMedia(data: WhatsAppMetaNodeData): Promise<any> {
  const mediaType = this.getMediaType(data.operation!);
  const mediaUrl = this.getMediaUrl(data);
  const mediaId = this.getMediaId(data);
  const caption = this.getMediaCaption(data);

  const mediaObject: any = {};

  if (mediaId) {
    mediaObject.id = mediaId;
  } else {
    mediaObject.link = mediaUrl;
  }

  if (caption) {
    mediaObject.caption = caption;
  }

  if (data.operation === 'send_document' && data.documentFilename) {
    mediaObject.filename = data.documentFilename;
  }

  const payload = {
    messaging_product: 'whatsapp',
    to: data.recipientPhone,
    type: mediaType,
    [mediaType]: mediaObject
  };

  const response: AxiosResponse = await axios.post(
    `${this.WHATSAPP_API_BASE}/${data.phoneNumberId}/messages`,
    payload,
    {
      headers: {
        'Authorization': `Bearer ${data.accessToken}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
}

Quando você DEVE usar este Node?

Use SEND MEDIA sempre que precisar enviar arquivos pelo WhatsApp:

Casos de uso:

Imagens: Fotos de produtos, comprovantes, screenshots, memes
Vídeos: Tutoriais, demonstrações, vídeos promocionais
Documentos: PDFs (contratos, faturas), planilhas, apresentações
Áudios: Mensagens de voz, notificações sonoras, podcasts
Cardápios: Imagens de pratos, menus em PDF
Catálogos: Portfolios visuais, lookbooks
Comprovantes: Recibos, tickets, vouchers

Quando NÃO usar SEND MEDIA:

Texto simples: Use SEND_MESSAGE para mensagens de texto
Arquivos muito grandes: WhatsApp tem limites de tamanho (veja tabela abaixo)
Múltiplos arquivos: Envie um por vez (com DELAY entre eles)

Tipos de Mídia e Limites

Tipo	Formatos Suportados	Tamanho Máximo	Campo
Imagem	JPEG, PNG	5 MB	imageUrl / imageId
Vídeo	MP4, 3GPP	16 MB	videoUrl / videoId
Documento	PDF, DOC, XLS, TXT, etc.	100 MB	documentUrl / documentId
Áudio	AAC, MP3, AMR, OGG	16 MB	audioUrl / audioId

Parâmetros Detalhados

operation (string, obrigatório)

O que é: Tipo de mídia a enviar.

Valores aceitos: - send_image - Enviar imagem - send_video - Enviar vídeo - send_document - Enviar documento - send_audio - Enviar áudio - send_media - Auto-detecta tipo (genérico)

imageUrl / imageId (string, condicional)

O que é: URL pública da imagem OU ID de mídia já enviada para WhatsApp.

Quando usar URL: - Hospede imagem em servidor público (HTTPS obrigatório) - WhatsApp baixará a imagem do URL - Mais lento, mas mais simples

Quando usar ID: - Upload prévio para WhatsApp Media API - Reutilizar mídia já enviada - Mais rápido

Flow completo para testar (URL):

{
  "name": "Teste WhatsApp Send Media - Image URL",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "URL da Imagem",
        "parameters": {
          "message": "Cole a URL da imagem:",
          "variable": "imagem_url"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Enviar Imagem",
        "parameters": {
          "operation": "send_image",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "imageUrl": "{{imagem_url}}",
          "imageCaption": "Imagem enviada via Lumina Flow!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Imagem enviada!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Cole URL de imagem pública (ex: https://exemplo.com/imagem.jpg)

imageCaption / videoCaption / documentCaption (string, opcional)

O que é: Legenda/texto que acompanha a mídia.

Flow completo para testar:

{
  "name": "Teste WhatsApp Send Media - Caption",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome do Produto",
        "parameters": {
          "message": "Nome do produto:",
          "variable": "produto_nome"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Preço",
        "parameters": {
          "message": "Preço do produto:",
          "variable": "produto_preco",
          "decimals": 2
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Enviar Foto do Produto",
        "parameters": {
          "operation": "send_image",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "imageUrl": "https://exemplo.com/produto.jpg",
          "imageCaption": "🛍️ {{produto_nome}}\n💰 R$ {{produto_preco}}\n\n✨ Disponível em estoque!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "number_1" },
    { "source": "number_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "end_1" }
  ]
}

Teste: Caption aparece abaixo da imagem com informações do produto!

documentFilename (string, opcional)

O que é: Nome do arquivo quando baixado pelo usuário. Apenas para documentos.

Flow completo para testar:

{
  "name": "Teste WhatsApp Send Media - Document",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Número da Fatura",
        "parameters": {
          "message": "Digite o número da fatura:",
          "variable": "fatura_numero"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Enviar Fatura PDF",
        "parameters": {
          "operation": "send_document",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "documentUrl": "https://exemplo.com/faturas/{{fatura_numero}}.pdf",
          "documentFilename": "Fatura_{{fatura_numero}}.pdf",
          "documentCaption": "📄 Fatura #{{fatura_numero}}\n\nObrigado pela preferência!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Fatura #{{fatura_numero}} enviada!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Documento aparece com nome personalizado no WhatsApp do usuário!

Parâmetros

Campo	Tipo	Obrigatório	Descrição
operation	string	Sim	send_image, send_video, send_document, send_audio
accessToken	string	Sim	Token da WhatsApp Business API
phoneNumberId	string	Sim	ID do número de telefone WhatsApp
recipientPhone	string	Sim	Telefone do destinatário (formato: 5511999999999)
imageUrl / imageId	string	Condicional	URL ou ID da imagem (para send_image)
videoUrl / videoId	string	Condicional	URL ou ID do vídeo (para send_video)
documentUrl / documentId	string	Condicional	URL ou ID do documento (para send_document)
audioUrl / audioId	string	Condicional	URL ou ID do áudio (para send_audio)
imageCaption	string	Não	Legenda da imagem
videoCaption	string	Não	Legenda do vídeo
documentCaption	string	Não	Legenda do documento
documentFilename	string	Não	Nome do arquivo de documento

Exemplo 1: Enviar Comprovante de Pagamento

Objetivo: Enviar imagem de comprovante após pagamento

JSON para Importar

{
  "name": "WhatsApp Media - Comprovante de Pagamento",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome do Cliente",
        "parameters": {
          "message": "Nome do cliente:",
          "variable": "cliente_nome"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Número do Pedido",
        "parameters": {
          "message": "Número do pedido:",
          "variable": "pedido_numero"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Valor Pago",
        "parameters": {
          "message": "Valor pago:",
          "variable": "valor_pago",
          "decimals": 2
        }
      }
    },
    {
      "id": "input_3",
      "type": "input",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "URL do Comprovante",
        "parameters": {
          "message": "URL da imagem do comprovante:",
          "variable": "comprovante_url"
        }
      }
    },
    {
      "id": "input_4",
      "type": "input",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Telefone (ex: 5511999999999):",
          "variable": "cliente_telefone"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Enviar Comprovante",
        "parameters": {
          "operation": "send_image",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "{{cliente_telefone}}",
          "imageUrl": "{{comprovante_url}}",
          "imageCaption": "✅ PAGAMENTO CONFIRMADO\n\n👤 Cliente: {{cliente_nome}}\n📦 Pedido: #{{pedido_numero}}\n💰 Valor: R$ {{valor_pago}}\n\nObrigado pela preferência! 🎉"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Comprovante enviado para {{cliente_nome}}!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "number_1" },
    { "source": "number_1", "target": "input_3" },
    { "source": "input_3", "target": "input_4" },
    { "source": "input_4", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Nome do cliente:
Usuário: João Silva
Sistema: Número do pedido:
Usuário: 12345
Sistema: Valor pago:
Usuário: 150.50
Sistema: URL da imagem do comprovante:
Usuário: https://exemplo.com/comprovante.jpg
Sistema: Telefone (ex: 5511999999999):
Usuário: 5511988887777
[WhatsApp Image enviada]
Sistema: ✅ Comprovante enviado para João Silva!

Exemplo 2: Enviar Múltiplas Mídias (Catálogo)

Objetivo: Enviar sequência de imagens de produtos com delay

JSON para Importar

{
  "name": "WhatsApp Media - Catálogo de Produtos",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Intro",
        "parameters": {
          "message": "📸 Confira nosso catálogo de produtos!"
        }
      }
    },
    {
      "id": "delay_1",
      "type": "delay",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Aguardar",
        "parameters": {
          "duration": 2,
          "unit": "seconds"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Produto 1",
        "parameters": {
          "operation": "send_image",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "imageUrl": "https://exemplo.com/produto1.jpg",
          "imageCaption": "🛍️ Produto 1: Camiseta Básica\n💰 R$ 49,90"
        }
      }
    },
    {
      "id": "delay_2",
      "type": "delay",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Aguardar",
        "parameters": {
          "duration": 2,
          "unit": "seconds"
        }
      }
    },
    {
      "id": "whatsapp_2",
      "type": "whatsapp_meta",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Produto 2",
        "parameters": {
          "operation": "send_image",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "imageUrl": "https://exemplo.com/produto2.jpg",
          "imageCaption": "🛍️ Produto 2: Calça Jeans\n💰 R$ 129,90"
        }
      }
    },
    {
      "id": "delay_3",
      "type": "delay",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Aguardar",
        "parameters": {
          "duration": 2,
          "unit": "seconds"
        }
      }
    },
    {
      "id": "whatsapp_3",
      "type": "whatsapp_meta",
      "position": { "x": 1500, "y": 100 },
      "data": {
        "label": "Produto 3",
        "parameters": {
          "operation": "send_image",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "imageUrl": "https://exemplo.com/produto3.jpg",
          "imageCaption": "🛍️ Produto 3: Tênis Esportivo\n💰 R$ 199,90"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1700, "y": 100 },
      "data": {
        "label": "Finalizar",
        "parameters": {
          "message": "✨ Gostou de algum produto? Responda com o número!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "delay_1" },
    { "source": "delay_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "delay_2" },
    { "source": "delay_2", "target": "whatsapp_2" },
    { "source": "whatsapp_2", "target": "delay_3" },
    { "source": "delay_3", "target": "whatsapp_3" },
    { "source": "whatsapp_3", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 📸 Confira nosso catálogo de produtos!
[2 segundos]
[Imagem 1 enviada com caption]
[2 segundos]
[Imagem 2 enviada com caption]
[2 segundos]
[Imagem 3 enviada com caption]
Sistema: ✨ Gostou de algum produto? Responda com o número!

Resposta do Node

{
  "success": true,
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "5511999999999",
        "wa_id": "5511999999999"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNBMDhBRjg3QTQyRjI2RTFCNDFBAA=="
      }
    ]
  },
  "executionTime": 2134,
  "logs": ["WhatsApp Meta send_image operation completed successfully"]
}

Boas Práticas

✅ SIM:

Use HTTPS para URLs de mídia (HTTP não funciona)
Otimize imagens antes de enviar (compressão sem perda de qualidade)
Use captions descritivos com emojis
Respeite limites de tamanho (5MB imagem, 16MB vídeo, 100MB documento)
Use DELAY entre múltiplas mídias (2-3 segundos)
Hospede arquivos em servidor confiável e rápido
Use documentFilename personalizado para melhor UX
Valide URLs antes de enviar (404 causará erro)

❌ NÃO:

Não use URLs sem HTTPS (será rejeitado)
Não envie arquivos corrompidos ou formatos não suportados
Não ultrapasse limites de tamanho (mensagem falhará)
Não envie múltiplas mídias sem delay (pode ser considerado spam)
Não use URLs temporários que expiram rápido
Não envie vídeos muito longos (considere dividir)
Não esqueça de testar URLs antes de produção

Dicas

💡 HTTPS obrigatório: WhatsApp só aceita URLs com certificado SSL válido 💡 Compressão: Use ferramentas como TinyPNG para imagens antes de enviar 💡 CDN: Hospede mídias em CDN para entrega mais rápida 💡 Formatos: JPEG/PNG para imagens, MP4 para vídeos, PDF para documentos 💡 Thumbnails: Vídeos automaticamente geram thumbnail no WhatsApp 💡 Áudio: Use para mensagens personalizadas (mais humano que texto) 💡 IDs reutilizáveis: Upload uma vez, use mediaId para envios futuros (economia de banda) 💡 Caption limits: Caption pode ter até 1024 caracteres

Próximo Node

→ SEND_MESSAGE - Enviar texto simples → SEND_INTERACTIVE - Adicionar botões e interatividade → GET_MEDIA - Baixar mídia recebida