Variáveis de AI Actions

Em qualquer lugar onde você pode digitar um valor em uma API Action (URL, headers, body ou query parameters), é possível injetar valores dinâmicos usando a sintaxe {{...}}. O Quickchat substitui esses placeholders no momento da requisição, logo antes de chamar o seu endpoint.

Clique no botão + Add AI Data ao lado de qualquer campo de valor para navegar por todas as variáveis disponíveis no cenário atual.

O botão + Add AI Data está disponível ao lado de cada campo de valor: a URL do endpoint, o valor de cada header, os campos do body e os query parameters.

Três categorias de variáveis

Categoria	Sintaxe	Quando é preenchida
Parâmetros de IA. Valores que seu Agente de IA extrai da conversa. Você os define na seção Parameters de cada Action.	{{order_number}}, {{customer_email}}	O Agente de IA os preenche na hora da chamada, com base nas regras que você escreveu na descrição de cada parâmetro.
Variáveis nativas. Contexto da conversa que o Quickchat injeta automaticamente.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Sempre disponíveis. O Quickchat as substitui em cada requisição.
Metadados de conversa. Pares chave-valor personalizados anexados à conversa.	{{metadata_<key>}}	Sempre que a chave correspondente existir na conversa (definida pelo widget, por uma integração de canal, pelo Smart Data Gathering ou pela API).

Dica

Cada variável é renderizada como uma pill colorida dentro do editor. Azul significa que é um parâmetro de IA ou uma variável nativa. Laranja significa que é uma variável de metadados ou um system token. Vermelho significa que o nome não corresponde a nada que o Quickchat reconheça (geralmente um erro de digitação).

O dropdown ”+ Add AI Data”

O dropdown lista todas as variáveis disponíveis para o cenário atual, agrupadas em cinco seções:

1. Parameters: os parâmetros de IA que você definiu nesta Action.
2. Visitor: quatro chaves de metadados capturadas automaticamente para cada visitante, quando o canal as fornece.
3. Metadata (used in recent conversations): chaves de metadados personalizadas vistas nas últimas 20 conversas deste cenário, com um valor de exemplo para cada uma.
4. Built-in: as sete variáveis de conversa que estão sempre disponíveis, com seu valor atual ou um exemplo exibido inline.
5. System Tokens: credenciais fornecidas por uma integração conectada (ex.: HubSpot, Telegram). Só aparece se a integração estiver conectada. Veja System Tokens abaixo.

O dropdown agrupa variáveis em seções. As linhas Built-in mostram o valor ao vivo quando já é conhecido (scenario_id) e exemplos e.g. … para as demais. O grupo Metadata (used in recent conversations) é reconstruído por cenário a partir de conversas reais recentes. A seção System Tokens (não mostrada aqui) aparece apenas quando uma integração está conectada.

Nota

A lista Metadata (used in recent conversations) é reconstruída a partir das 20 conversas mais recentes do seu cenário e fica em cache por 5 minutos por Agente de IA. Uma chave de metadados definida em uma conversa recém-criada pode levar até 5 minutos para aparecer nesta seção. Você pode sempre digitar {{metadata_<your_key>}} diretamente: o Quickchat não exige que a chave apareça no dropdown para a substituição funcionar.

Variáveis nativas

Estas sete variáveis estão sempre disponíveis. O dropdown + Add AI Data mostra o valor ao vivo (quando já conhecido) ou um valor de exemplo ao lado de cada linha.

Variável	Exemplo	O que é
{{scenario_id}}	abc123xyz	ID do Agente de IA ao qual a conversa pertence.
{{conversation_id}}	conv-d8a8…	Identificador único da conversa.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Link direto para esta conversa na Caixa de entrada (Inbox).
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Canal em que a conversa está acontecendo.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	Data e hora atuais em UTC no formato ISO 8601.
{{language}}	en, nl, de, fr, …	Código ISO 639-1 em minúsculas do idioma da conversa.
{{country}}	US, GB, NL, DE, …	Código de país ISO 3166-1 alpha-2 em maiúsculas.

Algumas observações úteis:

• {{scenario_id}} também é visível na URL do navegador enquanto você edita a Action. O dropdown + Add AI Data mostra o ID ao vivo do cenário que está sendo editado, não um exemplo.
• {{conversation_url}} é útil para postar links clicáveis no Slack, Jira ou qualquer outra ferramenta que se beneficie de um pulo direto de volta para a Caixa de entrada.
• {{language}} é derivado nesta ordem: do prefixo de URL da página (para Shopify Markets), dos metadados da conversa e, por fim, do idioma configurado do seu Agente de IA.
• {{country}} é derivado nesta ordem: do prefixo de URL da página, do TLD do host da URL e, por fim, de um fallback de idioma para país.

Metadados de conversa

O prefixo metadata_ é obrigatório. O Quickchat procura <key> nos metadados da conversa e substitui seu valor na requisição.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

Chaves de metadados do visitante

Estas quatro chaves descrevem a sessão do visitante e têm sua própria seção Visitor no dropdown. São capturadas automaticamente pelo canal, integração, widget/embed ou API. Você não precisa enviá-las por conta própria.

Variável	Capturada automaticamente por
{{metadata_fullPathURL}}	Widget de site, embed de site ou integrações de canal de chat que incluem o próprio widget (HubSpot, Intercom, etc.).
{{metadata_visitor_name}}	Perfil do canal de chat (Telegram, Slack, etc.), integrações de canal, Smart Data Gathering, seu widget/embed ou a API do Quickchat.
{{metadata_visitor_email}}	Perfil do canal de chat, integrações de canal, Smart Data Gathering, seu widget/embed ou a API do Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp e outros canais que reconhecem telefone, integrações de canal, Smart Data Gathering, seu widget/embed ou a API do Quickchat.

Chaves de metadados personalizadas

Você pode anexar pares chave-valor arbitrários a uma conversa e referenciá-los como {{metadata_<key>}}.

A partir do widget ou embed do site

Passe custom_params ao inicializar o widget. Veja a seção Canal Website: Advanced Features: Custom Parameters para o snippet completo.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

Referencie-os em qualquer Action como {{metadata_order_id}} e {{metadata_customer_tier}}.

Cuidado

As chaves de metadados precisam combinar com ^[a-zA-Z0-9_]+$ (letras, dígitos, underscores). Chaves com espaços ou outra pontuação não podem ser referenciadas como {{metadata_<key>}}. Elas continuarão aparecendo na visualização de metadados da conversa na Caixa de entrada, mas a substituição na Action vai ignorá-las. Use nomes em snake_case quando pretender usá-las em Actions.

A partir do Smart Data Gathering

Cada ponto de dados ativado no Smart Data Gathering vira uma chave de metadados com o nome dele em minúsculas e snake_case: espaços viram underscores, acentos e cedilhas são removidos e os demais sinais de pontuação são retirados.

Ponto de dados	Variável
Orçamento	{{metadata_orcamento}}
Tamanho da empresa	{{metadata_tamanho_da_empresa}}
Endereço de entrega	{{metadata_endereco_de_entrega}}

Os dados de contato são a exceção. Um ponto de dados chamado Email, Name ou Phone number (ou uma variante próxima em inglês, como Email address, Full name ou Mobile) preenche {{metadata_visitor_email}}, {{metadata_visitor_name}} ou {{metadata_visitor_phone_number}} no lugar. Só nomes em inglês são reconhecidos: um ponto de dados Telefone vira uma chave própria, telefone. Quando o agente de IA captura um dado de contato que a conversa ainda não tinha, ele também define lead_captured como true.

• Vazia até ser capturada. A chave é adicionada com valor vazio na primeira resposta do agente de IA com o Smart Data Gathering ativado e é preenchida assim que o visitante informa o dado. Uma correção posterior a atualiza; ela nunca volta a ficar vazia.
• Use is true para esperar um valor. Em Executar quando, a condição orcamento is true só é atendida quando há um valor capturado, enquanto orcamento exists é atendida assim que o Smart Data Gathering é executado. Respostas como no, false ou 0 contam como falsas.
• Seus próprios valores têm prioridade. Se a chave já tiver um valor definido pelo seu site, pela API ou por outra Action, o Smart Data Gathering não mexe nela. Ele também para de atualizar uma chave assim que outra coisa a altera.
• Alguns nomes são reservados, como language, locale e lead_captured. Um ponto de dados com um desses nomes não vira variável; renomeie-o se precisar de uma.
• Renomear um ponto de dados renomeia a variável. Atualize as Actions que a usam: uma Action não pode ser executada enquanto faltar na conversa uma variável de que ela precisa.

Assim que uma conversa tem a chave, ela também aparece no dropdown + Add AI Data.

A partir das integrações de canal

HubSpot, Intercom, Telegram, Slack, WhatsApp e integrações similares enviam seus próprios metadados para a conversa (nome do visitante, email, URL da página, propriedades de conta, etc.). Tudo que estiver visível na visualização de metadados da conversa na Caixa de entrada pode ser referenciado via {{metadata_<key>}}.

A partir da API do Quickchat

Use POST /v1/api_core/conversations/{conv_id}/metadata para anexar metadados programaticamente. Veja Conversation Metadata na referência da API.

System Tokens

Algumas integrações conectadas expõem um token do sistema: uma credencial que o Quickchat injeta na requisição do lado do servidor, na hora da chamada, quando a Action é executada. Um token do sistema não é adicionado ao contexto da IA nem aos metadados da conversa e é ocultado do log da requisição, do trace e do log de chamadas da Caixa de entrada. Os metadados comuns não têm as mesmas garantias de sigilo. O token aparece na seção Tokens do sistema do dropdown + Adicionar dados de IA apenas quando a integração correspondente está conectada, e é renderizado como uma pill laranja.

System token	Disponível quando	O que injeta
{{hubspot_access_token}}	HubSpot está conectado	Um token de acesso OAuth do HubSpot válido, atualizado automaticamente.
{{telegram_bot_token}}	O cenário tem atividade no Telegram	O token do seu bot do Telegram conectado, para chamar a Telegram Bot API.

Chamando a Telegram Bot API

A Telegram Bot API recebe o token do bot no caminho da URL, então você o referencia diretamente na URL do endpoint:

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

O Quickchat resolve o token na hora da chamada e o oculta em todos os lugares onde a requisição é exibida, de modo que o segredo nunca vaza. Para direcionar uma chamada da Bot API ao chat, à mensagem ou ao remetente atual, combine-o com as chaves de metadados do Telegram que o Quickchat define em cada mensagem recebida:

Chave de metadados	Valor
{{metadata_telegram_chat_id}}	O chat de onde a mensagem veio.
{{metadata_telegram_chat_type}}	private, group, supergroup ou channel.
{{metadata_telegram_user_id}}	O id de usuário do Telegram do remetente.
{{metadata_telegram_username}}	O @username do remetente, se houver.
{{metadata_telegram_message_id}}	O id da mensagem recebida.
{{metadata_telegram_sender_is_admin}}	true quando o remetente é um administrador do chat. Calculado do lado do servidor, então não pode ser forjado a partir do chat. Use-o em uma condição de execução para restringir ações de moderação a administradores.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	Definidas quando a mensagem recebida é uma resposta, para que a IA possa agir sobre a mensagem respondida (por exemplo, moderar seu autor).

Cores das pills no editor

Cada referência {{...}} é renderizada como uma pill colorida para que você saiba de relance se o Quickchat reconhece a variável.

As pills funcionam em qualquer campo de valor. Acima: uma pill laranja {{metadata_user_type}} na URL do endpoint e uma pill azul {{language}} no valor de um header.

As mesmas regras de cor se aplicam dentro de um body JSON de requisição. Variáveis nativas como {{country}} aparecem em azul, variáveis de metadados como {{metadata_fullPathURL}} aparecem em laranja.

• 🔵 Azul: uma variável nativa ou um parâmetro de IA que você definiu.
• 🟠 Laranja: uma variável de metadados ({{metadata_*}}) ou um System Token de uma integração conectada.
• 🔴 Vermelho: o Quickchat não reconhece este nome. Quase sempre um erro de digitação. Corrija a grafia, defina como parâmetro de IA ou (se for mesmo uma chave de metadados) garanta que comece com metadata_.

Dica

Digitar {{metadata_anything}} diretamente é sempre válido, mesmo se a chave nunca tiver aparecido em uma conversa. A pill ficará laranja, não vermelha. Esta é a forma correta de conectar chaves que você mesmo define a partir de um script de widget ou do Smart Data Gathering antes da primeira conversa acontecer.

Testando sua Action

O painel Test Response (ao lado de Done no editor de Action) permite que você envie uma requisição HTTP real sem passar por um chat. Para cada variável referenciada na Action, você verá uma linha de entrada para preencher o valor que o Quickchat irá substituir.

O painel preenche todas as variáveis nativas com o contexto ao vivo ou um valor de teste representativo. Os valores padrão de locale e horário incluem:

• {{language}} tem valor padrão en
• {{country}} tem valor padrão US
• {{current_timestamp}} tem como padrão a data e a hora atuais em UTC

Substitua qualquer campo para testar um valor diferente. Seus parâmetros de IA e as chaves {{metadata_*}} começam em branco. Digite qualquer valor para simular o que aconteceria em uma conversa ao vivo.

FAQ

Por que minha variável aparece em vermelho? O editor não reconhece o nome. Ou é um erro de digitação, ou não corresponde a nenhum parâmetro de IA que você definiu, ou não é uma variável nativa, ou é uma chave de metadados sem o prefixo metadata_.

Posso injetar {{language}} ou {{country}} mesmo se eu nunca defini-los? Sim. O Quickchat sempre deriva os dois do contexto da conversa (URL da página, locale do navegador ou idioma configurado do seu Agente de IA). Você sempre obterá um valor, mesmo que ele recaia em en / US.

Qual é a diferença entre {{language}} e {{metadata_locale}}?

• {{language}} é a variável nativa. Sempre disponível, sempre no formato en / nl / de … Use em 99% dos casos.
• {{metadata_locale}} só existe se uma integração de canal ou seu widget definir explicitamente uma chave locale nos metadados da conversa, frequentemente no formato xx_YY (ex.: en_GB). Use apenas quando precisar da string de locale exata, ao pé da letra.

Existe um limite no número de parâmetros de IA por Action? Sim, 30 por Action. Se você realmente precisar de mais, entre em contato com o suporte.

Os valores nativos e de metadados são enviados para a IA? O Quickchat substitui esses valores ao montar a requisição HTTP; a IA não precisa gerá-los nem defini-los como parâmetros de IA. Para uma Ação configurada como A AI decide, a substituição acontece depois que a IA escolhe a Ação. As Ações automáticas não pedem que a IA a escolha.

A substituição e o contexto do modelo são independentes. Os metadados elegíveis e o contexto nativo também podem estar disponíveis para a IA, e a resposta de uma Ação pode conter os mesmos valores. Outros metadados são filtrados do prompt. Não presuma que os metadados comuns sejam sempre visíveis ou sempre ocultos para o modelo. Veja Contexto do modelo e autorização.

Com que frequência a lista “Metadata (used in recent conversations)” é atualizada? Fica em cache por 5 minutos por Agente de IA. Uma chave de metadados definida em uma conversa recém-criada pode levar até 5 minutos para aparecer no dropdown, mas você pode sempre digitar {{metadata_<your_key>}} diretamente sem esperar.

Os nomes das chaves de metadados são case-sensitive? Sim. {{metadata_orderId}} e {{metadata_orderid}} são chaves diferentes. Use exatamente a mesma capitalização que você definiu no lado do widget, da integração ou da API.

O painel Test Response conhece essas variáveis? Sim. O painel Test Response preenche todas as sete variáveis nativas, incluindo {{language}} com en, {{country}} com US e {{current_timestamp}} com a hora atual em UTC. Os parâmetros de IA e as variáveis de metadados começam em branco. Digite qualquer valor para simular uma chamada ao vivo.

Relacionado

• Custom Actions: como criar e configurar uma API Action.
• Canal Website: Custom Parameters: como enviar metadados a partir do seu site.
• API: Conversation Metadata: como enviar metadados programaticamente.