Pular para conteúdo

SEND_DOCUMENT - Enviar Documento

O que é este Node?

O SEND_DOCUMENT é o node responsável por enviar documentos (PDF, DOC, XLS, etc.) via WhatsApp Business API.

Por que este Node existe?

Documentos são essenciais em negócios. O SEND_DOCUMENT existe para:

  1. Compartilhar arquivos: Enviar contratos, propostas, relatórios
  2. Nome personalizado: Definir nome de arquivo exibido
  3. Legenda descritiva: Adicionar contexto ao documento
  4. Formatos profissionais: Suportar PDF, Office, etc.
  5. Tamanho grande: Até 100MB por arquivo

Como funciona internamente?

Quando o SEND_DOCUMENT é executado, o sistema:

  1. Valida fonte: Verifica documentUrl ou documentId
  2. Extrai nome: Usa documentFilename ou nome original
  3. Constrói payload: Cria objeto tipo 'document'
  4. Adiciona caption: Inclui legenda se fornecida
  5. Envia para API: POST com tipo document
  6. Retorna message_id: Confirma envio

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_DOCUMENT quando precisar enviar arquivos profissionais:

Casos de uso

  1. Contratos: Enviar termos de serviço, contratos assinados
  2. Propostas comerciais: PDF com orçamentos detalhados
  3. Comprovantes: Recibos, notas fiscais
  4. Relatórios: Planilhas Excel, apresentações PowerPoint
  5. Manuais: Guias de usuário, documentação técnica

Quando NÃO usar SEND_DOCUMENT

  • Imagens: Use SEND_IMAGE para fotos
  • Vídeos: Use SEND_VIDEO para conteúdo audiovisual
  • Áudios: Use SEND_AUDIO para gravações

Parâmetros Detalhados

documentUrl (string, condicional)

O que é: URL pública HTTPS do documento. Obrigatório se documentId não fornecido.

Padrão: Nenhum

Flow completo para testar:

{
  "name": "Teste SEND_DOCUMENT - Document 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 PDF",
        "parameters": {
          "operation": "send_document",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "documentUrl": "https://exemplo.com/contrato.pdf",
          "documentFilename": "Contrato-Servico.pdf",
          "documentCaption": "Segue o contrato para análise"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Documento enviado!"
        }
      }
    },
    {
      "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 acessível publicamente.

documentId (string, condicional)

O que é: ID de documento já enviado ao WhatsApp. Obrigatório se documentUrl não fornecido.

Padrão: Nenhum

Flow completo para testar:

{
  "name": "Teste SEND_DOCUMENT - Document 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": "Reenviar Documento",
        "parameters": {
          "operation": "send_document",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511888888888",
          "documentId": "1234567890123456",
          "documentCaption": "Reenviando o documento solicitado"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Documento reenviado 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 de documento enviado anteriormente para economizar bandwidth.

documentFilename (string, opcional)

O que é: Nome personalizado do arquivo que será exibido no WhatsApp.

Padrão: Nome original do arquivo

Flow completo para testar:

{
  "name": "Teste SEND_DOCUMENT - Filename",
  "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 Nome Custom",
        "parameters": {
          "operation": "send_document",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "documentUrl": "https://storage.com/files/abc123.pdf",
          "documentFilename": "Proposta-Comercial-Janeiro-2025.pdf",
          "documentCaption": "Proposta válida até 31/01/2025"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Arquivo enviado com nome personalizado!"
        }
      }
    },
    {
      "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: Nome exibido no WhatsApp será "Proposta-Comercial-Janeiro-2025.pdf".

documentCaption (string, opcional)

O que é: Texto descritivo que acompanha o documento (legenda).

Padrão: Nenhum

Flow completo para testar:

{
  "name": "Teste SEND_DOCUMENT - 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_document",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "documentUrl": "https://docs.com/manual.pdf",
          "documentFilename": "Manual-Usuario.pdf",
          "documentCaption": "📖 Manual do Usuário\n\nVersão 2.0 - Janeiro 2025\n\nLeia com atenção para aproveitar todos os recursos!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Manual enviado com instruções!"
        }
      }
    },
    {
      "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 junto ao documento.

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "send_document"
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
documentUrl string Condicional URL do documento (obrigatório se sem documentId)
documentId string Condicional ID do documento (obrigatório se sem documentUrl)
documentFilename string Não Nome personalizado do arquivo
documentCaption string Não Legenda do documento

Exemplo 1: Enviar Contrato Assinado

Objetivo: Enviar contrato após assinatura digital com instruções.

JSON para Importar

{
  "name": "Envio de Contrato - SEND_DOCUMENT",
  "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 do Contrato",
        "parameters": {
          "variableName": "contract",
          "value": {
            "customerName": "Maria Silva",
            "customerPhone": "5511999999999",
            "contractId": "CONT-2025-001",
            "signedPdfUrl": "https://docs.empresa.com/contracts/signed-001.pdf",
            "validUntil": "31/12/2025"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Notificar",
        "parameters": {
          "message": "✅ Contrato assinado com sucesso!\n\nOlá {{contract.customerName}}, seu contrato está pronto.\n\nEnviando documento..."
        }
      }
    },
    {
      "id": "delay_1",
      "type": "delay",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Aguardar",
        "parameters": {
          "duration": 2,
          "unit": "seconds"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Enviar Contrato",
        "parameters": {
          "operation": "send_document",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "{{contract.customerPhone}}",
          "documentUrl": "{{contract.signedPdfUrl}}",
          "documentFilename": "Contrato-{{contract.contractId}}-Assinado.pdf",
          "documentCaption": "📄 Contrato Assinado\n\nID: {{contract.contractId}}\nCliente: {{contract.customerName}}\nValidade: {{contract.validUntil}}\n\n✅ Este documento possui validade jurídica.\n\nGuarde-o para referência futura."
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Finalizar",
        "parameters": {
          "message": "🎉 Tudo certo! Obrigado pela confiança.\n\nSe tiver dúvidas, estamos à disposição."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "message_1" },
    { "source": "message_1", "target": "delay_1" },
    { "source": "delay_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Contrato assinado com sucesso!
Olá Maria Silva, seu contrato está pronto.
Enviando documento...

[Aguarda 2s]

[PDF: Contrato-CONT-2025-001-Assinado.pdf]
📄 Contrato Assinado
ID: CONT-2025-001
Cliente: Maria Silva
Validade: 31/12/2025

✅ Este documento possui validade jurídica.
Guarde-o para referência futura.

Sistema: 🎉 Tudo certo! Obrigado pela confiança.
Se tiver dúvidas, estamos à disposição.

Exemplo 2: Enviar Relatório Mensal

Objetivo: Enviar relatório financeiro mensal em Excel.

JSON para Importar

{
  "name": "Relatório Mensal - SEND_DOCUMENT",
  "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 do Relatório",
        "parameters": {
          "variableName": "report",
          "value": {
            "clientName": "João Oliveira",
            "clientPhone": "5511888888888",
            "month": "Janeiro",
            "year": "2025",
            "reportUrl": "https://storage.empresa.com/reports/jan2025-client123.xlsx",
            "totalRevenue": "R$ 125.450,00",
            "totalExpenses": "R$ 78.320,00"
          }
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Saudação",
        "parameters": {
          "message": "📊 Relatório Mensal Disponível\n\nOlá {{report.clientName}}!\n\nSeu relatório de {{report.month}}/{{report.year}} está pronto."
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Enviar Relatório",
        "parameters": {
          "operation": "send_document",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "{{report.clientPhone}}",
          "documentUrl": "{{report.reportUrl}}",
          "documentFilename": "Relatorio-Financeiro-{{report.month}}-{{report.year}}.xlsx",
          "documentCaption": "📊 Relatório Financeiro - {{report.month}}/{{report.year}}\n\n💰 Receitas: {{report.totalRevenue}}\n💸 Despesas: {{report.totalExpenses}}\n\nAbra no Excel para ver detalhes completos."
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Finalizar",
        "parameters": {
          "message": "📞 Dúvidas sobre o relatório?\n\nEstamos à disposição para explicar qualquer item."
        }
      }
    },
    {
      "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: 📊 Relatório Mensal Disponível
Olá João Oliveira!
Seu relatório de Janeiro/2025 está pronto.

[Excel: Relatorio-Financeiro-Janeiro-2025.xlsx]
📊 Relatório Financeiro - Janeiro/2025

💰 Receitas: R$ 125.450,00
💸 Despesas: R$ 78.320,00

Abra no Excel para ver detalhes completos.

Sistema: 📞 Dúvidas sobre o relatório?
Estamos à disposição para explicar qualquer item.

Resposta do Node

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

Formatos Suportados

  • PDF: Formato universal, recomendado
  • Microsoft Office: DOC, DOCX, XLS, XLSX, PPT, PPTX
  • OpenOffice: ODT, ODS, ODP
  • Outros: TXT, CSV, RTF

Tamanho máximo: 100MB

Boas Práticas

✅ SIM:

  • Use PDF para documentos finais (melhor compatibilidade)
  • Defina documentFilename descritivo e organizado
  • Inclua versão e data no nome do arquivo
  • Use caption para resumir conteúdo do documento
  • Comprima arquivos grandes antes de enviar

❌ NÃO:

  • Não envie documentos protegidos por senha (WhatsApp não suporta)
  • Não use nomes de arquivo genéricos ("documento.pdf")
  • Não ultrapasse 100MB
  • Não envie formatos não suportados (.exe, .zip)
  • Não exponha dados sensíveis no caption

Dicas

💡 Nomenclatura: Use padrão "Tipo-Identificador-Data.ext" (ex: Contrato-CONT001-2025-01.pdf)

💡 PDF/A: Use formato PDF/A para arquivamento de longo prazo

💡 Compressão: Comprima PDFs com imagens usando ferramentas online

💡 Segurança: Nunca envie documentos com dados bancários/senhas

💡 Versionamento: Inclua versão no filename para rastreabilidade

Próximo Node

→ SEND_IMAGE - Enviar imagens → SEND_MEDIA - Enviar mídia genérica → SEND_MESSAGE - Enviar texto simples