Variáveis ($) — Guia Completo

A plataforma Verboo usa três sintaxes distintas de variáveis, cada uma em um contexto específico. Entender essa diferença é fundamental para criar fluxos e agentes eficazes.

Usar a sintaxe errada é a causa mais comum de variáveis não substituídas. Leia com atenção.

Visão Geral: As Três Sintaxes

1. Variáveis de Contexto de Flow — `$variavel`

Usadas exclusivamente em fluxos do tipo FLOW (chatbots determinísticos). São definidas e lidas dentro do próprio fluxo.

Como definir

Em cada nó do fluxo, na aba Context Actions, você define variáveis com um tipo e um valor:

Exemplo de configuração de Context Action:

{
  "type": "set_text",
  "key": "nome_cliente",
  "value": "João"
}

{
  "type": "set_entity",
  "key": "cpf_usuario",
  "value": "@cpf"
}

Como usar

Em qualquer campo de texto de resposta do nó, use $ seguido do nome da chave:

Olá, $nome_cliente! Seu CPF $cpf_usuario foi verificado com sucesso.

Seu pedido #$numero_pedido está com status: $status_pedido

Escopo

Variáveis de contexto são persistidas durante toda a sessão do usuário com aquele chatbot. Uma vez definida em um nó, a variável fica disponível em todos os nós seguintes.

2. Variáveis de Prompt — `${{variavel}}`

Usadas em Assistentes Generativos. São substituídas antes de o prompt ser enviado ao modelo de IA.

Variáveis definidas pelo usuário (ClientData)

Qualquer dado enviado via client_data na API se torna uma variável acessível no prompt:

# Criando sessão com client_data
curl -X POST https://api.verbeux.com.br/v1/session/ \
  -H "api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": 123,
    "client_data": {
      "nome_cliente": "Maria Silva",
      "plano": "premium",
      "telefone": "+5511999999999"
    }
  }'

No campo Prompt do assistente:

Você é um assistente de suporte da Empresa X.
Você está conversando com ${{nome_cliente}}, cliente do plano ${{plano}}.
Seja sempre cordial e chame o cliente pelo nome.

O texto que o modelo recebe será:

Você é um assistente de suporte da Empresa X.
Você está conversando com Maria Silva, cliente do plano premium.
Seja sempre cordial e chame o cliente pelo nome.

Variáveis built-in do sistema

Estas variáveis são injetadas automaticamente pela plataforma — você não precisa definir nada:

`${{conhecimento}}`

Contém os trechos da base de conhecimento (RAG) recuperados para a mensagem atual do usuário. Use no campo CustomPrompt para controlar onde o contexto é inserido:

Use as informações abaixo para responder ao usuário.
Não invente informações além do que está documentado.

---
${{conhecimento}}
---

Se a informação não estiver disponível acima, diga que não sabe.

Importante: ${{conhecimento}} só funciona no campo CustomPrompt (não no Prompt principal). Ative a flag IsCustomPrompt para usar.

`${{horario}}`

Insere a data e hora atuais formatadas em português brasileiro. Útil para agentes que precisam calcular datas de agendamento ou verificar horários:

Contexto temporal: ${{horario}}

Use esta referência para calcular datas futuras quando o usuário mencionar
"amanhã", "semana que vem", "próxima sexta", etc.

Onde usar `${{variavel}}`

3. Variáveis de Webhook — `$paramNome`

Usadas no corpo, headers e URL de ações de webhook dentro de Gatilhos Generativos. Diferente das outras sintaxes, aqui é um único $ sem chaves.

Variáveis automáticas do sistema

Sempre disponíveis em qualquer webhook configurado:

Variáveis de imagens enviadas pelo usuário

Quando o usuário envia imagens na conversa:

Variáveis de ClientData

Qualquer chave enviada via client_data na criação/atualização da sessão:

# Atualizar sessão com novos dados
curl -X PUT https://api.verbeux.com.br/v1/session/{id} \
  -F "message=Qual o meu saldo?" \
  -F 'client_data={"user_id":"usr_123","conta":"corrente"}'

No webhook: $user_id, $conta

Variáveis de argumentos do trigger

O LLM extrai parâmetros da conversa com base nos parâmetros definidos no trigger. Esses parâmetros ficam disponíveis como variáveis:

Definição do trigger:

{
  "name": "consultar_pedido",
  "description": "Consulta o status de um pedido pelo número",
  "parameters": {
    "type": "object",
    "properties": {
      "numero_pedido": {
        "type": "string",
        "description": "Número do pedido informado pelo cliente"
      }
    },
    "required": ["numero_pedido"]
  }
}

No webhook: $numero_pedido

{
  "url": "https://api.meusite.com/pedidos/$numero_pedido",
  "method": "GET",
  "headers": [
    { "key": "Authorization", "value": "Bearer $api_token" },
    { "key": "X-Session-ID", "value": "$session.id" }
  ]
}

Exemplo completo de webhook com variáveis

{
  "url": "https://crm.empresa.com/api/clientes/$user_id/agenda",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer $token_acesso" },
    { "key": "X-Company", "value": "$company.id" },
    { "key": "X-Session", "value": "$session.id" }
  ],
  "body": {
    "cliente": "$nome_cliente",
    "data": "$data_agendamento",
    "servico": "$tipo_servico",
    "observacoes": "Agendado via assistente. Sessão: $session.id"
  }
}

Comportamento de substituição

1. Ordem de aplicação: parâmetros mais longos são substituídos primeiro (para evitar substituições parciais)
2. URL path: valores são URL-encoded automaticamente
3. Headers e body: substituição literal (sem encoding)
4. JSON body: strings são JSON-escaped automaticamente

4. Atualizando ClientData via Resposta de Webhook

Um webhook pode retornar novos dados que são automaticamente mesclados ao client_data da sessão:

// Resposta do seu webhook
{
  "session": {
    "client_data": {
      "saldo_conta": "R$ 1.250,00",
      "ultima_transacao": "2025-03-07"
    }
  }
}

Esses valores ficam imediatamente disponíveis como $saldo_conta e $ultima_transacao para webhooks subsequentes na mesma sessão.

5. Tabela Comparativa Completa