Pular para conteúdo

SEND_MEDIA - Enviar Mídia Genérica

O que é este Node?

O SEND_MEDIA é o node responsável por enviar arquivos de mídia genéricos via WhatsApp Business API (imagens, vídeos, documentos ou áudios).

Por que este Node existe?

Comunicação visual é essencial. O SEND_MEDIA existe para:

  1. Flexibilidade: Enviar qualquer tipo de mídia com um único node
  2. Compartilhamento: Enviar arquivos, fotos, vídeos
  3. Legendas: Adicionar texto explicativo à mídia
  4. Múltiplos formatos: Suportar diversos tipos de arquivo
  5. IDs ou URLs: Aceitar mídia por link ou ID já enviado

Como funciona internamente?

Quando o SEND_MEDIA é executado, o sistema:

  1. Detecta tipo de mídia: Determina se é image, video, document ou audio
  2. Valida fonte: Verifica se tem mediaUrl ou mediaId
  3. Constrói payload: Cria objeto com tipo correto e parâmetros
  4. Adiciona caption: Inclui legenda se fornecida
  5. Envia para API: POST para Graph API v18.0
  6. Retorna resultado: message_id e status

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 quando precisar enviar qualquer tipo de mídia:

Casos de uso

  1. Enviar comprovante: PDF, imagem de boleto
  2. Catálogo de produtos: Fotos de itens
  3. Tutoriais: Vídeos explicativos
  4. Áudio: Mensagens de voz pré-gravadas
  5. Documentos: Contratos, manuais, relatórios

Quando NÃO usar SEND_MEDIA

  • Tipos específicos: Prefira SEND_IMAGE, SEND_VIDEO, SEND_DOCUMENT para clareza
  • Stickers: Use SEND_STICKER ao invés
  • Localização: Use SEND_LOCATION ao invés

Parâmetros Detalhados

mediaUrl (string, condicional)

O que é: URL pública do arquivo de mídia a ser enviado. Obrigatório se mediaId não fornecido.

Padrão: Nenhum

Flow completo para testar:

{
  "name": "Teste SEND_MEDIA - Media URL",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Enviar Mídia",
        "parameters": {
          "operation": "send_media",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "mediaUrl": "https://exemplo.com/imagem.jpg",
          "mediaCaption": "Confira esta imagem!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mídia enviada com sucesso!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: URL deve ser HTTPS e publicamente acessível. WhatsApp fará download do arquivo.

mediaId (string, condicional)

O que é: ID de mídia já enviada previamente ao WhatsApp. Obrigatório se mediaUrl não fornecido.

Padrão: Nenhum

Flow completo para testar:

{
  "name": "Teste SEND_MEDIA - Media ID",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Enviar Mídia por ID",
        "parameters": {
          "operation": "send_media",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "mediaId": "1234567890123456",
          "mediaCaption": "Reenviando arquivo"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mídia reenviada via ID!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Use ID retornado de envio anterior para reenviar mesmo arquivo sem re-upload.

mediaCaption (string, opcional)

O que é: Texto descritivo que acompanha a mídia (legenda).

Padrão: Nenhum

Flow completo para testar:

{
  "name": "Teste SEND_MEDIA - Caption",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Enviar com Legenda",
        "parameters": {
          "operation": "send_media",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "mediaUrl": "https://exemplo.com/produto.jpg",
          "mediaCaption": "🎁 Produto em Destaque\n\nCaneca Personalizada\nR$ 29,90\n\nCompre já!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mídia com legenda enviada!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Caption aparece como texto abaixo da mídia no WhatsApp.

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "send_media"
accessToken string Sim Token de acesso da WhatsApp Business API
phoneNumberId string Sim ID do número WhatsApp Business
recipientPhone string Sim Número do destinatário
mediaUrl string Condicional URL da mídia (obrigatório se sem mediaId)
mediaId string Condicional ID da mídia (obrigatório se sem mediaUrl)
mediaCaption string Não Legenda da mídia

Exemplo 1: Enviar Catálogo de Produtos

Objetivo: Enviar múltiplas imagens de produtos com descrição.

JSON para Importar

{
  "name": "Catálogo WhatsApp - SEND_MEDIA",
  "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": "Saudação",
        "parameters": {
          "message": "🛍️ Bem-vindo à nossa loja!\n\nConfira nossos produtos em destaque:"
        }
      }
    },
    {
      "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_media",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "mediaUrl": "https://loja.com/images/produto1.jpg",
          "mediaCaption": "🎧 Fone Bluetooth Premium\nR$ 149,90\nFrete Grátis!\n\nCódigo: FON001"
        }
      }
    },
    {
      "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_media",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "mediaUrl": "https://loja.com/images/produto2.jpg",
          "mediaCaption": "⌚ Smartwatch Pro\nR$ 299,90\n12x sem juros\n\nCódigo: SMT002"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Finalizar",
        "parameters": {
          "message": "💬 Interessou? Responda com o código do produto!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "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": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🛍️ Bem-vindo à nossa loja! Confira nossos produtos em destaque:
[Aguarda 2s]
[Imagem: produto1.jpg]
🎧 Fone Bluetooth Premium
R$ 149,90
Frete Grátis!
Código: FON001

[Aguarda 2s]
[Imagem: produto2.jpg]
⌚ Smartwatch Pro
R$ 299,90
12x sem juros
Código: SMT002

Sistema: 💬 Interessou? Responda com o código do produto!

Exemplo 2: Enviar Comprovante

Objetivo: Enviar comprovante de pagamento em PDF após confirmação.

JSON para Importar

{
  "name": "Envio de Comprovante - SEND_MEDIA",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Dados Pagamento",
        "parameters": {
          "variableName": "payment",
          "value": {
            "customerPhone": "5511999999999",
            "orderId": "ORD-12345",
            "amount": "R$ 350,00",
            "receiptUrl": "https://sistema.com/receipts/12345.pdf"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Notificar",
        "parameters": {
          "message": "✅ Pagamento confirmado!\n\nPedido: {{payment.orderId}}\nValor: {{payment.amount}}\n\nEnviando comprovante..."
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Enviar Comprovante",
        "parameters": {
          "operation": "send_media",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "{{payment.customerPhone}}",
          "mediaUrl": "{{payment.receiptUrl}}",
          "mediaCaption": "📄 Comprovante de Pagamento\n\nPedido: {{payment.orderId}}\nValor: {{payment.amount}}\n\nGuarde este documento para referência futura."
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Concluir",
        "parameters": {
          "message": "🎉 Obrigado pela compra!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "message_1" },
    { "source": "message_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Pagamento confirmado!
Pedido: ORD-12345
Valor: R$ 350,00
Enviando comprovante...

[PDF: comprovante-12345.pdf]
📄 Comprovante de Pagamento
Pedido: ORD-12345
Valor: R$ 350,00
Guarde este documento para referência futura.

Sistema: 🎉 Obrigado pela compra!

Resposta do Node

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "5511999999999",
      "wa_id": "5511999999999"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNBMzYxNzQyQ0JGRjREMTU0QzFEAA=="
    }
  ]
}

Formatos Suportados

Imagens

  • JPG/JPEG, PNG
  • Máximo: 5MB

Vídeos

  • MP4, 3GPP
  • Máximo: 16MB

Documentos

  • PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
  • Máximo: 100MB

Áudios

  • AAC, MP3, AMR, OGG (codec Opus)
  • Máximo: 16MB

Boas Práticas

✅ SIM:

  • Use HTTPS para mediaUrl
  • Otimize tamanho de arquivos antes de enviar
  • Use mediaId para reenviar mesmo arquivo (economiza bandwidth)
  • Inclua caption descritivo para contexto
  • Valide formato e tamanho antes de enviar

❌ NÃO:

  • Não envie URLs HTTP (apenas HTTPS aceito)
  • Não ultrapasse limites de tamanho por tipo
  • Não envie arquivos protegidos por senha
  • Não use URLs que expiram rapidamente
  • Não envie mídia sem verificar formato suportado

Dicas

💡 Cache de mídia: WhatsApp armazena mídia por 30 dias. Use mediaId para reenvios.

💡 URLs públicas: Certifique-se que URL não requer autenticação.

💡 Tamanho: Comprima imagens/vídeos grandes para melhor performance.

💡 Caption limits: Imagens e vídeos suportam caption, áudios não.

💡 Download timeout: WhatsApp tem 5 segundos para baixar arquivo da URL.

Próximo Node

→ SEND_IMAGE - Enviar especificamente imagens → SEND_DOCUMENT - Enviar especificamente documentos → SEND_VIDEO - Enviar especificamente vídeos → SEND_AUDIO - Enviar especificamente áudios