Mensagem de template WhatsApp variavel

A caixa Mensagem de template WhatsApp por variável envia uma mensagem de template do WhatsApp aprovado, mas diferente da caixa Mensagem de template WhatsApp, ela não fixa o template na configuração da caixa. Quem define qual template será enviado é o conteúdo de uma variável da sessão no momento da execução.

Isso é útil quando:

• o template (ou os parâmetros dele) só é definido durante a conversa — por exemplo, um valor recebido de uma integração, de um formulário ou montado em uma caixa de código;
• o mesmo fluxo precisa enviar templates diferentes conforme o caminho percorrido;
• o conteúdo da mensagem vem de um sistema externo, que devolve o template pronto em uma resposta.

Em execução, a caixa:

1. lê a variável informada em Variável com o template da mensagem e localiza o template nela;
2. lê a variável informada em Variável do telefone de destino e usa o número de quem receberá a mensagem;
3. monta a mensagem (corpo, cabeçalho, botões e localização, quando existirem no template) resolvendo referências {{variavel}} com os valores da sessão;
4. envia a mensagem pelo canal WhatsApp;
5. aguarda o status de entrega e desvia para a caixa de sucesso ou de falha.

Onde encontrar

1. Acesse Configuração > Fluxos.
2. Crie um fluxo ou abra uma versão existente no editor visual.
3. Na barra de ferramentas, abra o grupo Comunicação.
4. Adicione a caixa Mensagem de template WhatsApp por variável (ícone do WhatsApp) ao diagrama.
5. Selecione a caixa para abrir o painel de configuração.
6. Preencha os campos e clique em Aplicar.
7. Salve a versão do fluxo e publique ou ative a versão conforme o processo da organização.

Como a caixa funciona

Etapa anterior preenche as variáveis
  (template da mensagem e telefone de destino)
              │
              ▼
Mensagem de template WhatsApp por variável
              │  localiza o template na variável
              │  monta a mensagem e envia
              ▼
Aguarda o status de entrega
      ├── sent ou delivered ──► caixa de “Em caso de sucesso...”
      └── failed ────────────► caixa de “Caso haja alguma falha...”

Detalhes importantes do funcionamento:

• O template vem da variável. A caixa não lista templates na tela: ela procura o template dentro da variável indicada. O valor pode ser o próprio template (objeto ou texto JSON) ou um objeto que contém o template em uma de suas propriedades.
• O número de destino também vem de uma variável. A mensagem é enviada para o número gravado na variável informada em Variável do telefone de destino.
• Se o template não for encontrado, a caixa grava a variável de sessão wppTemplateError com a mensagem template nao encontrado na variavel <nome da variável> e não envia a mensagem — o fluxo não é interrompido por isso. Quando o template é encontrado, wppTemplateError é limpa (fica vazia). Uma Decisão ou caixa de código logo após o envio pode verificar essa variável para tratar o problema.
• Referências {{variavel}} são resolvidas na execução. Os valores de parâmetros do corpo, do cabeçalho e da localização aceitam o marcador {{nomeDaVariavel}}; na hora do envio, o valor atual da variável de sessão é colocado no lugar. Variável inexistente vira texto vazio.

A variável com o template da mensagem

O campo Variável com o template da mensagem aceita o nome da variável ou um caminho dentro dela (por exemplo, template ou formData.template). O conteúdo dessa variável deve descrever o template a ser enviado. A caixa reconhece como template um objeto (ou um texto JSON) que tenha ao menos a propriedade templateName (também são aceitos objetos com params ou bodyParams).

Propriedades reconhecidas no template:

Exemplo de conteúdo da variável templateMensagem:

{
  "templateName": "confirmacao_agendamento",
  "language": "pt_BR",
  "phoneNumberId": "123456789012345",
  "bodyParams": [
    "{{nomeCliente}}",
    "{{dataAgendamento}}"
  ]
}

Formas aceitas para o conteúdo da variável:

Os textos de bodyParams, o payload do headerParam e os campos de location aceitam referências {{variavel}}, resolvidas com os valores da sessão no momento do envio.

Importante: a variável precisa estar preenchida antes da caixa ser executada. Configure a etapa que grava o template (caixa de código, Requisição REST, WebHook, formulário etc.) antes dela no fluxo.

Nome do elemento

Identifica a caixa no diagrama. Exemplos: Enviar confirmação por template, Enviar boleto por template.

Variável do telefone de destino

Nome da variável da sessão que contém o número para quem a mensagem será enviada. Confira a grafia: o nome deve ser exatamente igual ao usado pela etapa que preenche a variável. É um campo obrigatório.

Variável com o template da mensagem

Nome da variável (ou caminho dentro dela) que contém o template da mensagem, conforme a seção anterior. É um campo obrigatório.

Em caso de sucesso de envio de mensagem, vai para:

Caixa de destino quando a mensagem é aceita para envio e o status de entrega retorna sent ou delivered.

Caso haja alguma falha no envio da mensagem, vai para:

Caixa de destino quando o status de entrega retorna failed. Recomendado sempre configurar — falhas de entrega acontecem (número inválido, template recusado, problema no canal). Se as duas navegações ficarem como Nenhum, a conversa não tem um caminho configurado após o envio.

Como configurar passo a passo

1. Prepare as variáveis

Antes da caixa, configure etapas que preencham:

• a variável com o template (objeto ou JSON com templateName e os parâmetros);
• a variável com o telefone de destino.

Exemplos de etapas de origem: Coletar dados (número do cliente), Requisição REST (resposta que traz o template), WebHook (payload recebido) e caixa de código (monta o objeto e grava com dialog.set).

2. Adicione e configure a caixa

1. Abra o grupo Comunicação e adicione a caixa Mensagem de template WhatsApp por variável.
2. Preencha o Nome do elemento.
3. Informe a Variável do telefone de destino.
4. Informe a Variável com o template da mensagem.
5. Selecione os destinos de sucesso e de falha.
6. Clique em Aplicar.
7. Salve a versão do fluxo.

3. Teste o caminho completo

1. Inicie uma nova sessão de teste pelo canal WhatsApp configurado.
2. Confirme que as variáveis de origem foram preenchidas antes da caixa.
3. Verifique se a mensagem chega no número de destino com os parâmetros corretos.
4. Confira se o fluxo seguiu pelo caminho de sucesso.
5. Repita o teste forçando um problema (por exemplo, uma variável de template vazia) e verifique o caminho de falha e a variável wppTemplateError.

Exemplo completo

Objetivo: confirmar um agendamento por WhatsApp, com o template escolhido em tempo de execução e o número coletado na conversa.

1. Coletar o número — caixa Coletar dados gravando na variável telefoneDestino.

2. Montar o template — caixa de código com o onEnter:

dialog.set('templateMensagem', JSON.stringify({
  templateName: 'confirmacao_agendamento',
  language: 'pt_BR',
  phoneNumberId: '123456789012345',
  bodyParams: ['{{nomeCliente}}', '{{dataAgendamento}}']
}));

3. Enviar — caixa Mensagem de template WhatsApp por variável:

Coletar dados (telefoneDestino)
      │
      ▼
Código: montar template (templateMensagem)
      │
      ▼
Enviar confirmação por template
      ├── sent/delivered ──► Confirmar envio
      └── failed ──────────► Avisar falha no envio

4. Conferir erros (opcional) — depois do envio, uma Decisão ou caixa de código pode verificar dialog.get('wppTemplateError'): se estiver preenchida, o template não foi localizado na variável e a mensagem não foi enviada.

Validações da caixa

Ao clicar em Aplicar, o builder verifica os dois campos de variável:

Em execução, quando o template não é localizado na variável (variável vazia, texto inválido ou caminho inexistente), a caixa grava wppTemplateError com a mensagem template nao encontrado na variavel <nome da variável> e não envia a mensagem.

Diferença entre as duas caixas de template WhatsApp

Boas práticas

• Preencha a variável do template antes da caixa e use exatamente o mesmo nome nos dois lugares.
• Prefira construir o objeto de template completo (com templateName, language e phoneNumberId) em uma etapa só, para facilitar a manutenção.
• Configure sempre o destino de falha e trate wppTemplateError quando o template puder faltar.
• Use referências {{variavel}} nos parâmetros para reaproveitar o mesmo objeto de template em conversas diferentes.
• Dê nomes funcionais às caixas (Enviar confirmação por template em vez de Novo).
• Teste os caminhos de sucesso e de falha em uma nova sessão antes de publicar a versão do fluxo.