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 seis 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). Só aparece se a integração estiver conectada.

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 seis 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.
{{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 nome de campo que você configurar em uma campanha do Smart Data Gathering vira uma chave de metadados com o mesmo nome. Se sua campanha coleta delivery_address, você pode usar {{metadata_delivery_address}} imediatamente em qualquer API Action subsequente.

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.

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.

Dois preenchimentos automáticos convenientes:

• {{language}} tem valor padrão en
• {{country}} tem valor padrão US

Substitua qualquer um dos campos para testar uma locale diferente. Todas as outras variáveis (seus parâmetros de IA, chaves {{metadata_*}} e as demais nativas) 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? Não. Eles são injetados na requisição HTTP depois que a IA decide chamar a Action. A IA não os vê e não é solicitada a preenchê-los. Por isso eles não precisam ser definidos como parâmetros de IA.

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. Quando sua Action referencia {{language}} ou {{country}}, o painel Test Response as preenche com en e US respectivamente. Todas as outras variáveis 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.