Substituições e fórmulas

Substituições são variáveis no formato {{...}} que são inseridas em textos de mensagens, campos de ações e templates de botões quando uma reação é disparada. Substituições não reconhecidas são mantidas como estão. Além das variáveis, há fórmulas para cálculos. O botão "Substituições" no editor de mensagem facilita a inserção de variáveis.

Dados do remetente

  • {{first_name}}, {{last_name}} — nome e sobrenome.
  • {{username}} — @username do usuário.
  • {{user_id}} — ID numérico do Telegram.

Dados do evento e do chat

  • {{text}} (também {{received_message}}) — texto da mensagem recebida.
  • {{message_id}} (também {{received_message_id}}) — ID da mensagem recebida.
  • {{chat_id}}, {{chat_title}} (também {{chat_name}}) — chat onde o evento ocorreu.
  • {{topic_id}}, {{topic_url}} — tópico (para fóruns).

Data e hora

  • {{date}} — data (AAAA-MM-DD), {{time}} — hora (HH:MM), {{datetime}} — data e hora.
  • Formatação: {{date:DD.MM.YYYY HH:mm}} — tokens YYYY, YY, MM, DD, HH, mm, ss.

Parâmetros do usuário

  • {{param.chave}} (também {{params.chave}} ou {{recipient.chave}}) — valor do parâmetro do assinante. Os parâmetros são preenchidos pelas ações "Alterar parâmetros", "Salvar mensagem" e pelas respostas no diálogo.

Contexto de execução (ctx)

  • {{ctx.chave}} (também {{context.chave}}) — valores temporários da execução atual: dados do webhook recebido, resultados de ações (requisição web, consulta a fonte, IA), dados restaurados do botão (Carry), elementos do loop.
  • No loop de lista, o elemento fica acessível pelo seu alias, por exemplo {{item.name}}.

Fórmulas

A construção {{= expressão}} avalia uma expressão diretamente no texto. O mesmo motor funciona na ação "Cálculo" e nas condições da tabela de decisão. Nas expressões, você pode referenciar parâmetros e valores de ctx pelo nome, usar aritmética, comparações, lógica e dezenas de funções (ROUND, IF, CONCAT etc.).

Exemplo: {{= ROUND(param.total * 0.9) }} — desconto de 10% sobre o total do parâmetro.

Sintaxe completa e lista de funções em Fórmulas.

HTML nas substituições

As mensagens são enviadas com marcação HTML. Para que um valor substituído não quebre o layout (por exemplo, quando um nome de usuário contém <), os valores substituídos são escapados por padrão: os caracteres HTML viram texto seguro. As tags que você escreve diretamente no texto da reação (<b>, <a>, …) ficam intactas.

Se um valor já contém marcação pronta (por exemplo, um anúncio salvo em um parâmetro com <b>...</b>) e você quer inseri-lo como está, prefixe a substituição com &:

  • {{& key}} — inserção bruta para as substituições {{...}}.
  • {&user:key}, {&recipient:key}, {&global:key} — inserção bruta para as substituições de namespace.

O prefixo & desativa o escape apenas para aquela substituição — você assume a responsabilidade pela confiança na origem do valor. É melhor deixar escapados os tokens controlados pelo assinante ({{first_name}}, …).

Ao importar bots de outros construtores, as substituições de namespace {user:…}/{recipient:…}/{global:…} são migradas automaticamente para a forma bruta {&…} — geralmente contêm valores com marcação pronta, como funcionava no construtor de origem.

Sobre o formato

As substituições {{...}} funcionam em textos, legendas, corpos de requisições e templates de botões. Dê aos parâmetros e chaves de ctx nomes curtos e em inglês (email, total, order_id) — são mais fáceis de usar como substituições.

Próximos passos