Pular para conteúdo

SEND_MESSAGE - Enviar Mensagem de Texto

O que é este Node?

O SEND_MESSAGE é o node responsável por enviar mensagens de texto via WhatsApp Business API usando a Meta Cloud API.

Por que este Node existe?

Chatbots precisam enviar mensagens. O SEND_MESSAGE existe para:

  1. Comunicação básica: Enviar texto simples para usuários
  2. Integração oficial: Usar API oficial do WhatsApp Meta
  3. Preview de URLs: Exibir preview automático de links
  4. Resposta automatizada: Responder conversas de forma programática
  5. Escalabilidade: Enviar mensagens sem limite de conexões

Como funciona internamente?

Quando o SEND_MESSAGE é executado, o sistema:

  1. Valida credenciais: Verifica accessToken e phoneNumberId
  2. Valida destinatário: Confirma recipientPhone no formato correto
  3. Constrói payload: Cria objeto JSON com messaging_product e text
  4. Envia requisição: POST para Graph API v18.0
  5. Se erro: Retorna erro de autenticação ou API
  6. Se sucesso: Retorna message_id e status

Código interno (whatsapp-meta-executor.service.ts:368-391): 

private async sendMessage(data: WhatsAppMetaNodeData): Promise<any> {
  const payload = {
    messaging_product: 'whatsapp',
    to: data.recipientPhone,
    type: 'text',
    text: {
      preview_url: data.previewUrl || false,
      body: data.messageText
    }
  };

  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_MESSAGE quando precisar enviar texto via WhatsApp:

Casos de uso

  1. Confirmação de pedido: "Seu pedido #1234 foi confirmado!"
  2. Notificações: "Você tem uma nova mensagem"
  3. Respostas automáticas: "Obrigado pelo contato, já vamos te atender"
  4. Compartilhar links: "Acesse nosso site: https://exemplo.com"
  5. Follow-up: "Tudo certo com seu pedido?"

Quando NÃO usar SEND_MESSAGE

  • Enviar imagens: Use SEND_IMAGE ao invés
  • Enviar documentos: Use SEND_DOCUMENT ao invés
  • Mensagens com botões: Use SEND_INTERACTIVE ao invés
  • Templates aprovados: Use SEND_TEMPLATE ao invés

Parâmetros Detalhados

accessToken (string, obrigatório)

O que é: Token de acesso da WhatsApp Business API gerado no Facebook Business.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste SEND_MESSAGE - Access Token",
  "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 Mensagem",
        "parameters": {
          "operation": "send_message",
          "accessToken": "SEU_ACCESS_TOKEN_AQUI",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "messageText": "Teste de envio"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mensagem 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: Substitua SEU_ACCESS_TOKEN_AQUI pelo token real e execute. O destinatário receberá a mensagem.

phoneNumberId (string, obrigatório)

O que é: ID do número de telefone WhatsApp Business registrado no Meta.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste SEND_MESSAGE - Phone Number 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 Mensagem",
        "parameters": {
          "operation": "send_message",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "SEU_PHONE_NUMBER_ID",
          "recipientPhone": "5511999999999",
          "messageText": "Testando Phone Number ID"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mensagem enviada do número correto!"
        }
      }
    },
    {
      "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: Encontre seu phoneNumberId no painel do WhatsApp Business no Meta Developer Portal.

recipientPhone (string, obrigatório)

O que é: Número de telefone do destinatário no formato internacional (sem + ou espaços).

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste SEND_MESSAGE - Recipient Phone",
  "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 Mensagem",
        "parameters": {
          "operation": "send_message",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "messageText": "Olá! Esta é uma mensagem de teste."
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mensagem enviada para {{recipientPhone}}!"
        }
      }
    },
    {
      "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: Formato: 5511999999999 (país + DDD + número). Sem +, parênteses ou espaços.

messageText (string, obrigatório)

O que é: Texto da mensagem a ser enviada. Suporta até 4096 caracteres.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste SEND_MESSAGE - Message Text",
  "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 Mensagem",
        "parameters": {
          "operation": "send_message",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "messageText": "🎉 Olá! Bem-vindo ao nosso serviço.\n\nEstamos felizes em ter você aqui!\n\nSe precisar de ajuda, é só chamar."
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mensagem com formatação 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: Suporta quebras de linha (\n), emojis e até 4096 caracteres.

previewUrl (boolean, opcional)

O que é: Se true, exibe preview automático de URLs na mensagem.

Padrão: false

Flow completo para testar:

{
  "name": "Teste SEND_MESSAGE - Preview 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 com Preview",
        "parameters": {
          "operation": "send_message",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "5511999999999",
          "messageText": "Confira nosso site: https://www.example.com",
          "previewUrl": true
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Link enviado com preview!"
        }
      }
    },
    {
      "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: Com previewUrl true, o WhatsApp exibirá card com imagem, título e descrição do link.

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "send_message"
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 (formato: 5511999999999)
messageText string Sim Texto da mensagem (até 4096 caracteres)
previewUrl boolean Não Exibir preview de URLs (padrão: false)

Exemplo 1: Confirmação de Pedido

Objetivo: Enviar confirmação automática de pedido com número e link de rastreamento.

JSON para Importar

{
  "name": "Confirmação de Pedido WhatsApp",
  "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 Pedido",
        "parameters": {
          "variableName": "order",
          "value": {
            "id": "12345",
            "customer": "João Silva",
            "phone": "5511999999999",
            "total": "R$ 299,90",
            "trackingUrl": "https://rastreio.com/12345"
          }
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Enviar Confirmação",
        "parameters": {
          "operation": "send_message",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "{{order.phone}}",
          "messageText": "🎉 Pedido Confirmado!\n\nOlá {{order.customer}}!\n\nSeu pedido #{{order.id}} foi confirmado com sucesso.\n\n💰 Valor: {{order.total}}\n\n📦 Acompanhe seu pedido: {{order.trackingUrl}}\n\nObrigado pela preferência!",
          "previewUrl": true
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Log",
        "parameters": {
          "message": "✅ Confirmação enviada para {{order.customer}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Confirmação enviada para João Silva

[WhatsApp para 5511999999999]:
🎉 Pedido Confirmado!

Olá João Silva!

Seu pedido #12345 foi confirmado com sucesso.

💰 Valor: R$ 299,90

📦 Acompanhe seu pedido: https://rastreio.com/12345

Obrigado pela preferência!

Exemplo 2: Lembrete de Agendamento

Objetivo: Enviar lembrete de consulta/agendamento 24h antes.

JSON para Importar

{
  "name": "Lembrete de Agendamento WhatsApp",
  "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 Agendamento",
        "parameters": {
          "variableName": "appointment",
          "value": {
            "patientName": "Maria Santos",
            "patientPhone": "5511888888888",
            "date": "15/01/2025",
            "time": "14:30",
            "doctor": "Dr. Carlos Oliveira",
            "specialty": "Cardiologia",
            "address": "Rua das Flores, 123 - São Paulo"
          }
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Enviar Lembrete",
        "parameters": {
          "operation": "send_message",
          "accessToken": "EAAxxxxxxxx",
          "phoneNumberId": "123456789",
          "recipientPhone": "{{appointment.patientPhone}}",
          "messageText": "🏥 Lembrete de Consulta\n\nOlá {{appointment.patientName}}!\n\nEste é um lembrete da sua consulta:\n\n📅 Data: {{appointment.date}}\n⏰ Horário: {{appointment.time}}\n👨‍⚕️ Médico: {{appointment.doctor}}\n🏥 Especialidade: {{appointment.specialty}}\n\n📍 Local:\n{{appointment.address}}\n\nPor favor, chegue 15 minutos antes.\n\nPara cancelar ou remarcar, entre em contato conosco.",
          "previewUrl": false
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Log",
        "parameters": {
          "message": "📱 Lembrete enviado para {{appointment.patientName}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 📱 Lembrete enviado para Maria Santos

[WhatsApp para 5511888888888]:
🏥 Lembrete de Consulta

Olá Maria Santos!

Este é um lembrete da sua consulta:

📅 Data: 15/01/2025
⏰ Horário: 14:30
👨‍⚕️ Médico: Dr. Carlos Oliveira
🏥 Especialidade: Cardiologia

📍 Local:
Rua das Flores, 123 - São Paulo

Por favor, chegue 15 minutos antes.

Para cancelar ou remarcar, entre em contato conosco.

Resposta do Node

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

Boas Práticas

✅ SIM:

  • Use previewUrl: true quando enviar links
  • Formate mensagens com quebras de linha (\n)
  • Inclua emojis para tornar mensagem mais amigável
  • Valide formato do recipientPhone (apenas números)
  • Mantenha mensagens abaixo de 1000 caracteres para melhor legibilidade

❌ NÃO:

  • Não envie SPAM ou mensagens não solicitadas
  • Não ultrapasse 4096 caracteres por mensagem
  • Não use recipientPhone com +, espaços ou parênteses
  • Não envie mensagens promocionais fora da janela de 24h (use templates)
  • Não exponha accessToken em logs ou frontend

Dicas

💡 Janela de 24h: Você pode enviar mensagens de texto livremente apenas dentro de 24h após última mensagem do usuário. Fora disso, use templates aprovados.

💡 Formatação: WhatsApp suporta negrito, itálico e ~tachado~ usando markdown.

💡 Múltiplas linhas: Use \n para quebras de linha e criar mensagens mais legíveis.

💡 Rate limiting: WhatsApp Business API tem limites de mensagens por segundo. Consulte tier do seu número.

💡 Testes: Use números de teste fornecidos pelo WhatsApp Business para desenvolvimento.

Próximo Node

→ SEND_TEMPLATE - Enviar mensagens template aprovadas → SEND_INTERACTIVE - Enviar mensagens com botões → SEND_IMAGE - Enviar imagens