Variáveis de modelo de mensagens do Zendesk: Um guia completo para 2026

As variáveis de modelo de mensagens do Zendesk são a chave para personalizar conversas com clientes em escala. Se você está pré-preenchendo dados do cliente, passando contexto entre sistemas ou construindo respostas dinâmicas de agentes de IA, entender como usar essas variáveis de forma eficaz pode transformar suas operações de suporte.

Este guia cobre tudo o que você precisa saber sobre as variáveis de modelo de mensagens do Zendesk: o que são, como a sintaxe funciona e maneiras práticas de implementá-las em seus fluxos de trabalho de suporte.

O que são variáveis de modelo de mensagens do Zendesk?

Variáveis de modelo no Zendesk são espaços reservados que inserem dados dinamicamente em suas mensagens. Pense nelas como etiquetas que dizem ao Zendesk: "Coloque o nome do cliente aqui" ou "Insira o número do pedido ali".

Essas variáveis servem a três propósitos principais:

• Personalização: Dirigir-se aos clientes pelo nome, referenciar seus pedidos específicos ou reconhecer seu histórico de conta
• Automação: Passar dados entre seu site, agentes de IA e agentes humanos sem intervenção manual
• Preservação do contexto: Manter os detalhes da conversa à medida que os clientes se movem entre bots e suporte humano

Existem três tipos de variáveis com as quais você trabalhará:

Variáveis de sistema vêm integradas ao Zendesk. Isso inclui nomes de clientes, endereços de e-mail, IDs de tickets e outros campos padrão que o Zendesk rastreia automaticamente.

Variáveis personalizadas são aquelas que você mesmo cria. Você pode definir uma variável produto_escolhido para rastrear o que um cliente selecionou, ou uma variável nível_de_prioridade para indicar urgência.

Variáveis de sessão são uma adição mais recente que persiste nos fluxos de conversação. Ao contrário das variáveis específicas da etapa, elas seguem o cliente por meio de várias respostas ou ramificações de diálogo em seu agente de IA.

Na eesel AI, abordamos as variáveis com uma filosofia semelhante: o contexto deve seguir o cliente naturalmente. Nossos colegas de equipe de IA retêm o histórico de conversas e os dados do cliente em todas as interações, sem configuração complexa.

Entendendo a sintaxe das variáveis de modelo de mensagens do Zendesk

O Zendesk oferece várias opções de sintaxe, dependendo do que você está tentando realizar. Acertar isso é crucial, pois misturá-las é um dos erros mais comuns que vemos.

Sintaxe abreviada para mensagens ricas

A sintaxe abreviada permite adicionar botões, imagens e elementos interativos a mensagens onde a formatação rica pode não estar disponível de outra forma.

Veja como funciona na prática. Se você enviar uma mensagem com este texto:

Obrigado por entrar em contato! %[Ver pedido](https://shop.com/order/123) %[Falar com um agente](reply:escalate)

O Zendesk o converte em uma mensagem com dois botões clicáveis: um com link para a página do pedido e outro que envia "escalate" como um payload de resposta.

Sintaxe de inserção de modelo

Para inserir um modelo pré-definido em uma mensagem, use esta sintaxe:

%((template:nome_do_modelo))%

Existe também uma sintaxe alternativa caso a padrão entre em conflito com outros sistemas de template:

%{{template:nome_do_modelo}}%

Se você incluir texto junto com a sintaxe do modelo, apenas o texto antes do modelo será enviado como uma mensagem separada. Qualquer texto após a sintaxe do modelo é ignorado.

Interpolação de variáveis

Para variáveis que você definiu em seus fluxos de agente de IA, use chaves duplas:

Olá {{nome_do_cliente}}, obrigado por entrar em contato sobre o pedido nº {{id_do_pedido}}.

Esta sintaxe funciona para:

• Variáveis de sessão que persistem entre as respostas
• Parâmetros capturados de chamadas de API (Application Programming Interface)
• Valores coletados em campos de formulário

Modelos de mensagens do WhatsApp

O WhatsApp usa uma sintaxe diferente com mais parâmetros:

&((
  namespace=[[namespace]]
  template=[[template_name]]
  fallback=[[fallback_text]]
  language=[[language_code]]
  body_text=[[parameter_1]]
  body_text=[[parameter_2]]
))&

Esta sintaxe inclui o namespace, nome do modelo, texto de fallback, idioma e parâmetros de texto do corpo da variável.

Erros de sintaxe comuns

Os erros mais frequentes que vemos envolvem:

• Usar chaves simples {variável} em vez de duplas {{variável}}
• Esquecer os sinais de porcentagem de fechamento na sintaxe do modelo
• Misturar os tipos de botão reply: e postback:
• Usar espaços em nomes de modelo ou variável (use hífens ou sublinhados em vez disso)

Usando variáveis de modelo de mensagens do Zendesk em agentes de IA

Os modelos de mensagens estruturadas são onde as variáveis realmente brilham nos agentes de IA do Zendesk. Esses modelos permitem que você crie experiências ricas e interativas sem escrever código.

Criando modelos de formulário

Os modelos de formulário coletam informações dos clientes de forma estruturada. Você pode criá-los em Agentes de IA - Avançado, navegando para Configurações > Integração de CRM (Customer Relationship Management) > Modelos.

Ao criar um modelo de formulário, você configurará:

Nome do modelo: Isso não pode conter espaços ou caracteres especiais. Apenas hífens e sublinhados são permitidos. O nome é o que você referenciará em sua sintaxe abreviada.

Tipos de campo: Escolha entre e-mail, texto ou selecionar (menu suspenso). Todos os rótulos de campo são limitados a 130 caracteres.

Nomes de variáveis: Cada campo cria uma variável com o nome que você especificar. Essas variáveis ficam disponíveis nas etapas de conversação subsequentes.

Bloquear entrada de mensagens: Uma configuração opcional que impede que os clientes digitem texto livre até que concluam o formulário.

Dica de melhor prática: Mantenha os formulários com cinco campos ou menos. Formulários mais longos apresentam taxas de abandono significativas, especialmente em dispositivos móveis.

Criando modelos JSON personalizados

Para interações mais complexas, como carrosséis, listas ou classificações NPS (Net Promoter Score), use modelos JSON (JavaScript Object Notation) personalizados. Estes exigem algum conhecimento técnico, mas oferecem maior flexibilidade.

A estrutura JSON segue o formato de mensagem estruturada do Zendesk. Você pode criar carrosséis com vários itens, cada um contendo uma imagem, título, descrição e botões de ação.

Adicionando modelos aos fluxos de conversação

Depois de criar um modelo, você precisa inseri-lo no diálogo do seu agente de IA:

1. Vá para a guia Modelos nas configurações do seu agente de IA
2. Clique no código abreviado para copiá-lo para a área de transferência
3. Abra o diálogo onde você deseja usá-lo
4. Cole o código abreviado em um bloco de mensagens do agente de IA

O modelo é renderizado automaticamente quando a conversa atinge essa etapa. Se você definiu variáveis no modelo (como nomes de campos de formulário), esses valores são capturados e podem ser usados posteriormente no fluxo.

Passando dados com campos personalizados e metadados

Um dos usos mais poderosos das variáveis de modelo de mensagens do Zendesk é passar dados entre seu site, o widget de mensagens e seu sistema de suporte.

Passando dados para o Web Widget

Você pode pré-preencher campos personalizados quando um cliente inicia uma conversa. Isso é útil para passar contexto como em qual página eles estão, qual produto estão visualizando ou o status da conta deles.

Aqui está a implementação em JavaScript:

zE("messenger:set", "conversationFields", [
  { id: "7662882404114", value: "Blade Runner" }
])

O ID é o ID do seu campo personalizado no Admin Center (Central de Administração). Você pode encontrá-lo indo para Admin Center > Objetos e regras > Tickets > Campos.

Requisito crítico: O campo personalizado deve ser definido como editável pelo usuário final. Se esta configuração estiver desativada, os dados não passarão.

Quando este código é executado, os dados são armazenados nos metadados da conversa com este formato:

{
  "metadata": {
    "zen:ticket_field:7662882404114": "Blade Runner"
  }
}

Recuperando metadados em agentes de IA

Para usar esses dados em seus fluxos de agente de IA, você precisa criar uma Ação:

1. No painel do AI Agents Advanced (Agentes de IA Avançado), vá para Conteúdo > Ações
2. Crie uma nova Ação com o destino "Sunshine Conversation"
3. Selecione a tarefa "Obter metadados da conversa"
4. Recupere o objeto de Metadados e salve-o como um parâmetro

Para o campo Chave, use a chave de metadados completa: zen:ticket_field:7662882404114 (substitua o ID pelo ID do seu campo real).

Depois que a ação for executada, você poderá acessar o valor em suas respostas usando a sintaxe {{nome_do_parâmetro}}.

Lidando com valores ausentes

Sempre considere os casos em que os metadados podem não estar presentes. Adicione uma etapa condicional que verifique se o seu parâmetro tem um valor e, em seguida, ramifique de acordo: mostre os dados pré-preenchidos se eles existirem ou peça a entrada do cliente se não existirem.

Atualizando metadados após o escalonamento

Você também pode enviar dados de volta para o Zendesk ao escalar para um agente humano. Crie uma ação "Atualizar metadados da conversa" com:

• Chave: zen:ticket_field:SEU_ID_DE_CAMPO
• Valor: {{sua_variável}}

Adicione esta ação ao seu bloco de Escalonamento. Quando a conversa é transferida para um agente, o campo do ticket é preenchido automaticamente com o valor da variável.

Limitações importantes:

• Campos do sistema, como assunto e status, não podem ser atualizados por meio de metadados do Sunshine Conversations
• Para campos suspensos, você deve passar o valor da tag associada, não o texto de exibição
• Para campos de pesquisa, passe o ID do objeto personalizado, usuário ou organização

Exemplos práticos de implementação

Vamos percorrer alguns cenários do mundo real onde as variáveis de modelo de mensagens do Zendesk fazem a diferença.

Exemplo 1: Pré-preenchendo o contexto do cliente da página da web

Uma empresa de comércio eletrônico deseja passar o produto que um cliente está visualizando para a conversa de suporte.

Configuração:

1. Crie um campo de texto personalizado "Produto Visualizado" no Zendesk
2. Adicione este JavaScript à página do produto:

   zE("messenger:set", "conversationFields", [
     { id: "123456789", value: "Fones de ouvido sem fio X1" }
   ])
   

3. Em seu agente de IA, crie uma ação para obter os metadados
4. Em sua mensagem de saudação: "Vejo que você está olhando para {{produto_visualizado}}. Você tem alguma dúvida sobre este item?"

Exemplo 2: Recomendações dinâmicas de produtos via API

Uma empresa de varejo deseja mostrar recomendações de produtos personalizadas com base no histórico de compras.

Configuração:

1. Crie uma etapa de chamada de API que busca recomendações usando o ID do cliente
2. Armazene a matriz retornada como uma variável (por exemplo, recomendações)
3. Use uma etapa Apresentar Carrossel com configuração dinâmica
4. Mapeie os campos do carrossel: Título = recommendation.name, Imagem = recommendation.image_url
5. Cada item do carrossel vincula à página do produto

Exemplo 3: Envio de formulário para fluxo de campo de ticket

Uma empresa de software deseja coletar informações de implantação antes de escalar para o suporte técnico.

Configuração:

1. Crie um modelo de formulário com campos: Ambiente (selecionar), Versão (texto), Tipo de problema (selecionar)
2. Adicione o formulário ao seu fluxo de escalonamento
3. Crie variáveis de cada campo: ambiente_de_implantação, versão_do_software, tipo_de_problema
4. Antes de escalar, atualize os metadados da conversa para cada campo
5. Quando o ticket é criado, esses campos são pré-preenchidos para o agente

Exemplo 4: Variáveis de sessão em fluxos de conversação

Uma empresa de viagens deseja lembrar o destino de um cliente em várias respostas.

Configuração:

1. Na resposta "Reservar uma viagem", use Apresentar Opções para coletar o destino
2. Armazene a seleção em {{destino_escolhido}}
3. Use "Link para outra resposta" para enviar o cliente para "Recomendações de hotéis"
4. Na resposta Hotéis, referencie {{destino_escolhido}} para mostrar opções relevantes
5. Mais tarde, link para "Recomendações de atividades" que também usa a mesma variável

Esta abordagem evita pedir ao cliente seu destino várias vezes.

Uma abordagem mais simples para variáveis de modelo com eesel AI

Se você está achando o sistema de variáveis do Zendesk complexo, você não está sozinho. Os múltiplos tipos de sintaxe, requisitos de metadados e permissões de campo criam uma curva de aprendizado acentuada.

Na eesel AI, adotamos uma abordagem diferente para contexto e variáveis. Nossos colegas de equipe de IA aprendem seu negócio desde o primeiro dia, conectando-se aos seus sistemas existentes: centrais de ajuda, tickets anteriores, macros e documentação. O contexto flui naturalmente pelas conversas sem configuração manual.

Veja como lidamos com o que o Zendesk faz com as variáveis de modelo:

Passagem de variáveis sem código: Em vez de escrever JavaScript para passar dados para o widget, a eesel AI se integra diretamente com sua plataforma de comércio eletrônico, CRM ou help desk. Dados do cliente, histórico de pedidos e detalhes da conta estão automaticamente disponíveis para a IA.

Retenção automática de contexto: As variáveis de sessão acontecem automaticamente. Se um cliente mencionar que está usando um dispositivo móvel em sua primeira mensagem, esse contexto persiste durante toda a conversa sem que você crie variáveis ou configure ações.

Instruções em linguagem simples: Em vez de aprender a sintaxe abreviada, você simplesmente diz à eesel AI o que fazer: "Se o pedido de reembolso for superior a 30 dias, recuse educadamente e ofereça crédito na loja." Sem código, sem sintaxe, sem fluxos complexos.

Implantação progressiva: Comece com a eesel AI redigindo respostas para seus agentes revisarem. À medida que você vê que ela entende seu negócio, expanda para a resolução autônoma completa. Você controla o ritmo com base no desempenho real.

Para equipes que já usam o Zendesk, a eesel AI se integra diretamente com seu help desk. A IA pode acessar suas macros existentes, artigos da central de ajuda e histórico de tickets, tornando a transição perfeita.

Melhores práticas e como começar

Se você estiver implementando variáveis de modelo de mensagens do Zendesk, aqui estão as recomendações com base no que vimos funcionar:

Convenções de nomenclatura

• Use nomes descritivos: email_do_cliente é melhor que campo1
• Mantenha letras minúsculas com sublinhados: número_do_pedido não NúmeroDoPedido
• Evite palavras reservadas do Zendesk: não use ticket, usuário ou organização como nomes de variáveis
• Mantenha curto: você estará digitando isso com frequência em blocos de mensagens

Testando antes de entrar em produção

Sempre teste seus fluxos de variáveis completamente:

• Teste com valores ausentes para garantir que a lógica condicional funcione
• Teste em diferentes canais (web widget, SDK (Software Development Kit) móvel, WhatsApp)
• Teste o caminho de escalonamento para verificar se os campos do ticket são preenchidos corretamente
• Use a visualização de conversa do Zendesk para verificar antes de publicar

Considerações de segurança

• Nunca passe dados confidenciais (números de cartão de crédito, senhas) por meio de metadados de conversa
• Revise quais campos são editáveis pelo usuário final; desative a edição para campos confidenciais
• Use tokens de API com permissões mínimas necessárias para integrações
• Audite regularmente seus campos e ações personalizados

Dicas de desempenho

• Minimize as chamadas de API; armazene dados em cache quando possível
• Use variáveis de sessão em vez de chamadas de API repetidas para dados que não mudam
• Mantenha os modelos de formulário curtos para reduzir o abandono
• Teste fluxos pesados em variáveis em dispositivos móveis para garantir um desempenho responsivo

Próximos passos

Comece simples. Escolha um caso de uso, como cumprimentar os clientes pelo nome ou pré-preencher um único campo personalizado. Sinta-se confortável com a sintaxe básica antes de construir fluxos complexos de várias variáveis.

Depois de dominar os fundamentos, explore a documentação do Zendesk sobre recursos avançados de modelo, como substituições de mensagens para Apple Messages for Business ou formatação específica do WhatsApp.