---
title: "Mensagem de template WhatsApp variavel"
slug: "mensagem-de-template-whatsapp-variavel"
updated: 2026-10-23T17:48:11Z
published: 2026-10-23T17:48:11Z
canonical: "docs.omnisiga.ai/mensagem-de-template-whatsapp-variavel"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Propriedade | Obrigatória? | Para que serve |
| --- | --- | --- |
| `templateName` | Sim | Nome do template aprovado no WhatsApp. Sem ela, a caixa trata como “template não encontrado”. |
| `bodyParams` | Não | Lista de parâmetros do corpo do template. Cada item pode ser um texto simples ou um objeto com `payload`. Cada item vira um parâmetro do tipo texto. |
| `phoneNumberId` | Recomendada | Identificador do número de envio do WhatsApp usado para despachar a mensagem. Normalmente já vem no objeto de template. |
| `language` | Recomendada | Idioma do template (por exemplo, `pt_BR`). Normalmente já vem no objeto de template. |
| `headerParam` | Não | Parâmetro do cabeçalho (texto ou mídia), no formato de objeto com `payload`. |
| `location` | Não | Quando presente, a mensagem é enviada como template de localização, com `latitude`, `longitude`, `address` e `name`. |
| `buttonComponents` | Não | Componentes de botão do template. |
| `templateData` | Não | Dados adicionais do template, encaminhados como estão. |

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:

| Conteúdo da variável | Comportamento |
| --- | --- |
| O template direto (objeto ou texto JSON com `templateName`) | O template é usado imediatamente. |
| Um objeto que contém o template em uma das propriedades (por exemplo, `formData` com `formData.template`) | A caixa procura o template nas propriedades diretas do objeto. |
| Um texto que não é JSON válido, ou objeto sem `templateName` | Tratado como “template não encontrado”: `wppTemplateError` é preenchida e nada é enviado. |

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**:

| Campo | Valor |
| --- | --- |
| Nome do elemento | `Enviar confirmação por template` |
| Variável do telefone de destino | `telefoneDestino` |
| Variável com o template da mensagem | `templateMensagem` |
| Em caso de sucesso de envio de mensagem, vai para: | `Confirmar envio` |
| Caso haja alguma falha no envio da mensagem, vai para: | `Avisar falha no envio` |

```
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:

| Situação | Mensagem |
| --- | --- |
| Campo “Variável com o template da mensagem” vazio | “O campo 'Variável com o template da mensagem' não foi informado” |
| Campo “Variável do telefone de destino” vazio | “O campo 'Variável do telefone de destino' não foi informado” |

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

| Recurso | Mensagem de template WhatsApp | Mensagem de template WhatsApp por variável |
| --- | --- | --- |
| Escolha do template | Fixada na configuração da caixa, a partir dos templates aprovados do número selecionado. | Escolhida em tempo de execução, a partir de uma variável. |
| Número de envio | Selecionado na caixa. | Vem no objeto de template (`phoneNumberId`). |
| Número de destino | Variável informada na caixa. | Variável informada na caixa. |
| Parâmetros do corpo, cabeçalho, mídia, localização e cartões | Preenchidos no painel, com preview do template. | Vêm no objeto de template (propriedades `bodyParams`, `headerParam`, `location`, `buttonComponents`). |
| Quando usar | Template e parâmetros conhecidos na hora de desenhar o fluxo. | Template ou parâmetros definidos apenas durante a execução. |

## 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.

---