Pular para conteúdo

WHATSAPP SEND TEMPLATE - Enviar Template Pré-aprovado

O que é este Node?

O WHATSAPP SEND TEMPLATE é o node responsável por enviar mensagens baseadas em templates pré-aprovados pelo Meta para iniciar conversas ou enviar notificações estruturadas.

Por que este Node existe?

WhatsApp Business exige templates aprovados para iniciar conversas. O SEND TEMPLATE existe para:

  1. Iniciar conversas: WhatsApp só permite iniciar conversa com template aprovado
  2. Marketing aprovado: Enviar campanhas promocionais dentro das regras do Meta
  3. Notificações estruturadas: Enviar alertas padronizados (confirmações, lembretes, etc.)
  4. Compliance: Garantir que mensagens seguem políticas do WhatsApp Business
  5. Personalização em escala: Templates suportam variáveis dinâmicas

Como funciona internamente?

Quando o SEND TEMPLATE é executado, o sistema:

  1. Valida credenciais: Verifica accessToken e phoneNumberId
  2. Valida template: Confirma que templateName e templateLanguage existem
  3. Valida destinatário: Garante que recipientPhone está presente
  4. Formata parâmetros: Processa templateParameters (texto, moeda, data)
  5. Monta payload: Estrutura JSON conforme especificação da API
  6. Envia requisição: POST para WhatsApp Graph API
  7. Retorna resultado: Confirma envio com ID da mensagem

Código interno (whatsapp-meta-executor.service.ts:546-593): 

private async sendTemplate(data: WhatsAppMetaNodeData): Promise<any> {
  const template: any = {
    name: data.templateName,
    language: {
      code: data.templateLanguage
    }
  };

  if (data.templateParameters && data.templateParameters.length > 0) {
    template.components = [
      {
        type: 'body',
        parameters: data.templateParameters.map(param => {
          switch (param.type) {
            case 'text':
              return { type: 'text', text: param.text };
            case 'currency':
              return { type: 'currency', currency: param.currency };
            case 'date_time':
              return { type: 'date_time', date_time: param.date_time };
            default:
              return { type: 'text', text: param.text };
          }
        })
      }
    ];
  }

  const payload = {
    messaging_product: 'whatsapp',
    to: data.recipientPhone,
    type: 'template',
    template
  };

  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 TEMPLATE sempre que precisar iniciar conversa ou enviar notificação estruturada:

Casos de uso:

  1. Iniciar atendimento: Enviar primeira mensagem para cliente (obrigatório usar template)
  2. Confirmação de pedido: Template com variáveis do pedido
  3. Notificação de entrega: Atualizações de status de envio
  4. Código de verificação: OTP/2FA para autenticação
  5. Lembrete de pagamento: Notificar sobre vencimentos
  6. Promoções: Campanhas de marketing aprovadas pelo Meta

Quando NÃO usar SEND TEMPLATE:

  • Conversa já iniciada: Use SEND_MESSAGE para respostas
  • Mensagem sem template: Templates precisam ser criados e aprovados primeiro
  • Conteúdo dinâmico livre: Templates têm estrutura fixa, use SEND_MESSAGE para flexibilidade

Parâmetros Detalhados

templateName (string, obrigatório)

O que é: Nome único do template criado no Meta Business Manager.

Como criar templates: 1. Acesse Meta Business Manager 2. Vá em WhatsApp Manager > Message Templates 3. Crie novo template (aguarde aprovação - pode levar 24h) 4. Use o nome exato do template aprovado

Flow completo para testar:

{
  "name": "Teste WhatsApp Send Template - TemplateName",
  "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 Template",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "templateName": "hello_world",
          "templateLanguage": "pt_BR"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Template 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: Use "hello_world" (template padrão do WhatsApp) ou nome do seu template aprovado.

templateLanguage (string, obrigatório)

O que é: Código do idioma do template (ISO 639-1 + país).

Códigos comuns: - pt_BR - Português do Brasil - en_US - Inglês (EUA) - es_ES - Espanhol (Espanha) - es_MX - Espanhol (México)

Flow completo para testar:

{
  "name": "Teste WhatsApp Send Template - Language",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "switch_1",
      "type": "switch",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Escolher Idioma",
        "parameters": {
          "variable": "idioma_escolhido",
          "cases": [
            { "value": "portugues", "targetNodeId": "whatsapp_pt" },
            { "value": "ingles", "targetNodeId": "whatsapp_en" },
            { "value": "espanhol", "targetNodeId": "whatsapp_es" }
          ]
        }
      }
    },
    {
      "id": "whatsapp_pt",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 50 },
      "data": {
        "label": "Template PT-BR",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "templateName": "boas_vindas",
          "templateLanguage": "pt_BR"
        }
      }
    },
    {
      "id": "whatsapp_en",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 150 },
      "data": {
        "label": "Template EN-US",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "templateName": "welcome",
          "templateLanguage": "en_US"
        }
      }
    },
    {
      "id": "whatsapp_es",
      "type": "whatsapp_meta",
      "position": { "x": 500, "y": 250 },
      "data": {
        "label": "Template ES-ES",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "templateName": "bienvenida",
          "templateLanguage": "es_ES"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 150 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "switch_1" },
    { "source": "whatsapp_pt", "target": "end_1" },
    { "source": "whatsapp_en", "target": "end_1" },
    { "source": "whatsapp_es", "target": "end_1" }
  ]
}

Teste: Configure variável idioma_escolhido e envie template no idioma correto!

templateParameters (array, opcional)

O que é: Array de parâmetros para preencher variáveis do template ({{1}}, {{2}}, etc.).

Tipos suportados: - text: Texto simples - currency: Valores monetários - date_time: Datas e horários

Flow completo para testar:

{
  "name": "Teste WhatsApp Send Template - Parameters",
  "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 Cliente",
        "parameters": {
          "message": "Digite o nome do cliente:",
          "variable": "cliente_nome"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Número Pedido",
        "parameters": {
          "message": "Digite o número do pedido:",
          "variable": "pedido_numero"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Valor Pedido",
        "parameters": {
          "message": "Digite o valor do pedido:",
          "variable": "pedido_valor",
          "decimals": 2
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Enviar Confirmação",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "5511999999999",
          "templateName": "confirmacao_pedido",
          "templateLanguage": "pt_BR",
          "templateParameters": [
            { "type": "text", "text": "{{cliente_nome}}" },
            { "type": "text", "text": "{{pedido_numero}}" },
            { "type": "text", "text": "{{pedido_valor}}" }
          ]
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Confirmação enviada para {{cliente_nome}}!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "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": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Template precisa ter placeholders {{1}}, {{2}}, {{3}} que serão substituídos pelos parâmetros!

Parâmetros

Campo Tipo Obrigatório Descrição
operation string Sim Deve ser "send_template"
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)
templateName string Sim Nome do template aprovado pelo Meta
templateLanguage string Sim Código do idioma (ex: pt_BR, en_US)
templateParameters array Não Parâmetros para substituir variáveis do template

Exemplo 1: Confirmação de Pedido com Template

Objetivo: Enviar confirmação estruturada usando template aprovado

Template necessário no Meta: 

Nome: confirmacao_pedido
Categoria: TRANSACTIONAL
Idioma: pt_BR

Conteúdo:
Olá {{1}}! 👋

✅ Seu pedido #{{2}} foi confirmado com sucesso!

💰 Valor: R$ {{3}}
📦 Status: Em preparação

Obrigado pela preferência!

JSON para Importar

{
  "name": "WhatsApp Template - Confirmação Pedido",
  "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",
        "parameters": {
          "message": "Nome do cliente:",
          "variable": "nome"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Pedido",
        "parameters": {
          "message": "Número do pedido:",
          "variable": "pedido"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Valor",
        "parameters": {
          "message": "Valor total:",
          "variable": "valor",
          "decimals": 2
        }
      }
    },
    {
      "id": "input_3",
      "type": "input",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Telefone",
        "parameters": {
          "message": "Telefone do cliente (ex: 5511999999999):",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Enviar Template",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "{{telefone}}",
          "templateName": "confirmacao_pedido",
          "templateLanguage": "pt_BR",
          "templateParameters": [
            { "type": "text", "text": "{{nome}}" },
            { "type": "text", "text": "{{pedido}}" },
            { "type": "text", "text": "{{valor}}" }
          ]
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Confirmação",
        "parameters": {
          "message": "✅ Template enviado para {{nome}} ({{telefone}})"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1500, "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": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Nome do cliente:
Usuário: Maria Silva
Sistema: Número do pedido:
Usuário: 12345
Sistema: Valor total:
Usuário: 299.90
Sistema: Telefone do cliente (ex: 5511999999999):
Usuário: 5511988887777
[WhatsApp Template enviado]
Sistema: ✅ Template enviado para Maria Silva (5511988887777)

Exemplo 2: Código de Verificação (OTP)

Objetivo: Enviar código de autenticação 2FA

Template necessário no Meta: 

Nome: codigo_verificacao
Categoria: AUTHENTICATION
Idioma: pt_BR

Conteúdo:
🔐 SEU CÓDIGO DE VERIFICAÇÃO

*{{1}}*

⚠️ Não compartilhe este código.
Válido por 5 minutos.

JSON para Importar

{
  "name": "WhatsApp Template - Código OTP",
  "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": "Telefone",
        "parameters": {
          "message": "Digite seu telefone (ex: 5511999999999):",
          "variable": "telefone"
        }
      }
    },
    {
      "id": "random_1",
      "type": "random",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Gerar Código",
        "parameters": {
          "min": 100000,
          "max": 999999,
          "variable": "codigo_otp"
        }
      }
    },
    {
      "id": "whatsapp_1",
      "type": "whatsapp_meta",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Enviar OTP",
        "parameters": {
          "operation": "send_template",
          "accessToken": "SEU_TOKEN",
          "phoneNumberId": "SEU_PHONE_ID",
          "recipientPhone": "{{telefone}}",
          "templateName": "codigo_verificacao",
          "templateLanguage": "pt_BR",
          "templateParameters": [
            { "type": "text", "text": "{{codigo_otp}}" }
          ]
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "✅ Código {{codigo_otp}} enviado para {{telefone}}"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Validar Código",
        "parameters": {
          "message": "Digite o código recebido:",
          "variable": "codigo_digitado"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 1300, "y": 100 },
      "data": {
        "label": "Verificar",
        "parameters": {
          "condition": "{{codigo_digitado}} == {{codigo_otp}}",
          "trueNodeId": "message_ok",
          "falseNodeId": "message_erro"
        }
      }
    },
    {
      "id": "message_ok",
      "type": "message",
      "position": { "x": 1500, "y": 50 },
      "data": {
        "label": "Código Correto",
        "parameters": {
          "message": "✅ Código verificado! Acesso liberado."
        }
      }
    },
    {
      "id": "message_erro",
      "type": "message",
      "position": { "x": 1500, "y": 150 },
      "data": {
        "label": "Código Incorreto",
        "parameters": {
          "message": "❌ Código inválido. Tente novamente."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "random_1" },
    { "source": "random_1", "target": "whatsapp_1" },
    { "source": "whatsapp_1", "target": "message_1" },
    { "source": "message_1", "target": "number_1" },
    { "source": "number_1", "target": "condition_1" },
    { "source": "message_ok", "target": "end_1" },
    { "source": "message_erro", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite seu telefone (ex: 5511999999999):
Usuário: 5511988887777
[Código gerado: 456789]
[WhatsApp Template enviado]
Sistema: ✅ Código 456789 enviado para 5511988887777
Sistema: Digite o código recebido:
Usuário: 456789
Sistema: ✅ Código verificado! Acesso liberado.

Resposta do Node

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

Categorias de Templates

UTILITY (Transacional)

  • Confirmações de pedidos
  • Atualizações de conta
  • Alertas de segurança
  • Notificações de entrega

AUTHENTICATION (Autenticação)

  • Códigos OTP
  • Verificação em duas etapas
  • Redefinição de senha

MARKETING (Marketing)

  • Promoções
  • Ofertas especiais
  • Campanhas
  • Requer opt-in do usuário

Boas Práticas

✅ SIM:

  • Sempre crie e aprove templates no Meta Business Manager antes de usar
  • Use categoria correta: UTILITY para transacional, AUTHENTICATION para OTP
  • Teste templates em números de teste antes de produção
  • Use variáveis {{1}}, {{2}}, etc. para personalização
  • Mantenha templates simples e objetivos (aprovação mais rápida)
  • Respeite limites: templates podem ter até 1024 caracteres
  • Use templateLanguage correto (pt_BR para Brasil)

❌ NÃO:

  • Não use templates não aprovados (erro 404)
  • Não misture idiomas (template pt_BR com language en_US)
  • Não envie marketing sem opt-in do usuário
  • Não abuse de templates promocionais (pode resultar em bloqueio)
  • Não use parâmetros que não existem no template
  • Não espere aprovação instantânea (pode levar 24h ou mais)

Dicas

💡 Aprovação rápida: Templates simples sem links externos são aprovados mais rápido 💡 Variáveis: Use {{1}}, {{2}}, {{3}} em ordem sequencial 💡 Categorias: UTILITY e AUTHENTICATION têm menos restrições que MARKETING 💡 Teste: Meta fornece template "hello_world" pré-aprovado para testes 💡 Idiomas: Crie versões do template para cada idioma que precisar 💡 Rejeições: Se template for rejeitado, revise política do WhatsApp Business 💡 Rate limiting: Templates contam no limite de 80 msg/segundo 💡 Custo: Templates iniciam conversas - verifique custos na sua região

Próximo Node

→ SEND_MESSAGE - Responder dentro de conversa ativa → SEND_INTERACTIVE - Adicionar botões ao template → CREATE_TEMPLATE - Criar templates via API