Variáveis Globais - Referência de Variáveis de Sistema do ChatMaxima

Referência das Variáveis Globais do ChatMaxima (campos de sistema sys_) usadas para personalizar bots, transmissões e respostas automáticas com dados de contato e sessão.

Visão Geral

As Variáveis Globais, também chamadas de Variáveis de Sistema, são marcadores integrados que o ChatMaxima resolve automaticamente em tempo de execução. Elas dão acesso a informações sobre o contato atual, a conversa, a mensagem, a plataforma e a mídia sem nenhuma configuração. Toda Variável Global começa com o prefixo sys_ e é envolvida em chaves simples, como {sys_account_contact_name}.

Use as Variáveis Globais em qualquer lugar onde você precise personalizar conteúdo, rotear conversas ou passar contexto para integrações: blocos do construtor de bots, modelos de transmissão, respostas automáticas, modelos de mensagem e cargas úteis de API ou webhook.

Como Inserir uma Variável Global

Em qualquer campo de entrada compatível, basta digitar { e um seletor aparece listando todas as Variáveis Globais e Atributos Personalizados disponíveis. Selecione o que você quer e o ChatMaxima o insere no formato correto.

Clique no campo onde você quer inserir a variável
Digite uma única chave de abertura {
Escolha a variável no menu suspenso que aparece
O seletor insere o token completo, por exemplo {sys_account_contact_name}

Nota: Os nomes das variáveis diferenciam maiúsculas de minúsculas. Sempre use chaves simples em torno do nome da variável.

Variáveis Globais Suportadas

Variable	Description
`{sys_account_contact_name}`	Nome do contato associado à sessão do chatbot
`{sys_account_contact_email}`	Endereço de e-mail do contato que interage com o chatbot
`{sys_account_contact_mobile}`	Número de celular associado à conta do contato
`{sys_contact_reference_id}`	ID de referência da conversa atual
`{sys_current_message}`	Mensagem atual sendo processada em um bot
`{sys_account_platform}`	Plataforma atual processada em um bot (por exemplo, WhatsApp, Facebook, Telegram)
`{sys_current_date_time}`	Data e hora atuais no momento da execução
`{sys_current_page_url}`	URL da página da web onde o chatbot está ativo no momento
`{sys_current_conversation}`	Histórico completo da conversa, incluindo mensagens e carimbos de data/hora
`{sys_ai_intent}`	Intenção detectada a partir da consulta do usuário em blocos MaxIA (por exemplo, `general_query`, `human_agent`, `booking_request`)
`{sys_current_media}`	URL, tipo e nome do arquivo da mídia mais recente (imagem, vídeo, áudio, documento) enviada pelo usuário, como um objeto JSON. Use `{sys_current_media.url}` ou `{sys_current_media.type}` para campos específicos

Variáveis de Contato

Estas resolvem para dados armazenados no perfil do contato.

{sys_account_contact_name} é a variável mais comum para personalização. Use-a em saudações, modelos de transmissão e mensagens de confirmação.
{sys_account_contact_email} e {sys_account_contact_mobile} são úteis para passar a identidade para webhooks, sincronização de CRM e fluxos de verificação.
{sys_contact_reference_id} identifica de forma única o tópico da conversa, útil ao correlacionar eventos entre sistemas.

Variáveis de Conversa

Estas descrevem a mensagem atual e o histórico.

{sys_current_message} contém o texto que o usuário acabou de enviar. Use-a para repetir a entrada de volta, registrá-la ou passá-la para um bloco de API.
{sys_current_conversation} contém o histórico completo do chat com carimbos de data/hora, útil para resumo por IA ou contexto de transferência.

Variáveis de Canal e Contexto

{sys_account_platform} permite ramificar a lógica por canal, por exemplo, enviando uma mensagem diferente no WhatsApp e no Widget Web.
{sys_current_page_url} captura onde o visitante estava no seu site quando começou a conversar. Útil para roteamento ou análises.
{sys_current_date_time} carimba o momento da execução, útil para carimbos de data/hora em tickets ou sistemas posteriores.

Variáveis de IA e Mídia

{sys_ai_intent} é preenchida por blocos MaxIA após a detecção de intenção. Ramifique seu bot com base em se o usuário quer human_agent, booking_request, general_query e assim por diante.
{sys_current_media} é um objeto JSON que descreve o arquivo mais recente que o usuário enviou. Acesse campos individuais com notação de ponto:

{sys_current_media.url}
{sys_current_media.type}
{sys_current_media.filename}

Variáveis Globais vs Atributos Personalizados

O ChatMaxima suporta dois tipos de marcadores dinâmicos. Ambos aparecem no mesmo seletor {.

	Variáveis Globais	Atributos Personalizados
Prefixo	`sys_`	Nenhum (você escolhe o nome)
Criado por	ChatMaxima (integrado)	Você, nas configurações de Contatos
Exemplos	`{sys_account_contact_name}`, `{sys_current_message}`	`{company_name}`, `{order_id}`, `{plan_type}`
Origem do valor	Sessão, perfil do contato, mensagem ou contexto da plataforma	Armazenado em cada contato, preenchido manualmente, por importação de CSV, por bloco de bot ou por API
Use quando	O dado é algo que o ChatMaxima já conhece	O dado é específico da lógica do seu negócio

Onde Usar Variáveis Globais

As Variáveis Globais funcionam em toda a plataforma sempre que o seletor { estiver disponível:

Blocos do Construtor de Bots: Enviar Mensagem, Enviar E-mail, Bloco de API, Bloco de Webhook, Bloco Condicional, Bloco Definir Atributo e a maioria dos outros blocos aceitam variáveis em seus campos de texto e de parâmetro.
Modelos de transmissão: Mapeie os marcadores de modelos aprovados do WhatsApp ({{1}}, {{2}}) para Variáveis Globais ao criar uma transmissão.
Respostas automáticas e respostas prontas: Personalize mensagens de ausência e respostas salvas.
Prompts de IA da Base de Conhecimento: Passe o contexto da sessão para o prompt de sistema do seu agente de IA.
Webhooks e integrações: Inclua variáveis em URLs de webhook, cabeçalhos e corpos de requisição para encaminhar o contexto a sistemas externos.

Exemplos de Casos de Uso

Personalizar uma transmissão do WhatsApp

Modelo aprovado:

Hello {{1}}, your order {{2}} has been confirmed.

No compositor de transmissão, mapeie {{1}} para {sys_account_contact_name} e {{2}} para seu atributo personalizado {order_id}. Cada destinatário recebe uma mensagem como "Hello Priya, your order ORD-1042 has been confirmed."

Cumprimentar pelo nome em um bot

Coloque um bloco Enviar Mensagem no início do seu fluxo com:

Hi {sys_account_contact_name}, how can we help you today?

Se o contato não tiver nome registrado, o marcador resolve para vazio, então adicione uma ramificação de fallback quando necessário.

Rotear por intenção de IA

Use {sys_ai_intent} em um Bloco Condicional após um bloco MaxIA:

Se {sys_ai_intent} for igual a human_agent, roteie para o chat ao vivo
Se {sys_ai_intent} for igual a booking_request, vá para o seu fluxo de agendamento
Caso contrário, continue com o fluxo de perguntas frequentes

Passar contexto para um webhook

No corpo de um Bloco de Webhook:

{
  "name": "{sys_account_contact_name}",
  "phone": "{sys_account_contact_mobile}",
  "message": "{sys_current_message}",
  "platform": "{sys_account_platform}",
  "page": "{sys_current_page_url}"
}

O ChatMaxima substitui cada variável pelo valor ao vivo antes de enviar a requisição.

Encaminhar um arquivo enviado para o seu backend

Se um usuário enviar uma imagem e você precisar salvá-la no servidor, use:

{
  "file_url": "{sys_current_media.url}",
  "file_type": "{sys_current_media.type}",
  "file_name": "{sys_current_media.filename}"
}

Melhores Práticas

Valide os dados do seu contato: Se uma Variável Global como {sys_account_contact_mobile} estiver ausente para um contato, o marcador resolve para vazio. Limpe os dados dos seus contatos antes de transmitir.
Combine com Atributos Personalizados: Use Variáveis Globais para dados de identidade e de sessão, e Atributos Personalizados para campos específicos do negócio, como números de pedido, tipos de plano ou datas de compromisso.
Teste antes de enviar: Execute uma transmissão de teste ou uma sessão de bot com seu próprio registro de contato para confirmar que cada variável resolve corretamente.
Use a notação de ponto para variáveis JSON: {sys_current_media} retorna um objeto JSON. Sempre acesse campos específicos como {sys_current_media.url} em vez de usar o objeto completo em texto simples.
Evite codificar valores fixos: Sempre que você digitaria o nome, celular ou e-mail de um contato, recorra a uma Variável Global em vez disso.

Solução de Problemas

A variável aparece como texto literal na saída

Verifique se a variável está envolvida em chaves simples, não duplas: {sys_account_contact_name} está correto, {{sys_account_contact_name}} não está (chaves duplas são a sintaxe de marcador de modelos da Meta, usada apenas dentro de modelos aprovados do WhatsApp).
Confirme que a grafia corresponde exatamente ao seletor. As variáveis diferenciam maiúsculas de minúsculas.
Certifique-se de que você está usando a variável em um campo compatível. Alguns campos de texto simples fora dos editores de bot, transmissão e modelo não interpretam variáveis.

A variável resolve para vazio

Verifique se os dados subjacentes existem no perfil do contato (por exemplo, se o contato realmente tem um nome ou celular salvo).
Para {sys_ai_intent}, confirme que um bloco MaxIA foi executado antes do ponto onde a variável é usada.
Para {sys_current_media}, confirme que o usuário enviou mídia nesta sessão.

Precisa de um valor que o ChatMaxima não expõe

Se o valor de que você precisa não estiver na lista de Variáveis Globais, crie um Atributo Personalizado e preencha-o através do perfil do contato, de uma importação de CSV, de uma chamada de API ou de um bloco de bot Definir Atributo.