Variables ($): Complete Guide

The Verboo platform uses three distinct variable syntaxes, each in a specific context. Understanding this difference is essential to building effective flows and agents.

Using the wrong syntax is the most common cause of variables not being substituted. Read carefully.

Overview: The Three Syntaxes

1. Flow Context Variables: `$variable`

Used exclusively in FLOW-type chatbots (deterministic chatbots). They are defined and read within the flow itself.

How to define

In each flow node, in the Context Actions tab, you define variables with a type and a value:

Example Context Action configuration:

{
  "type": "set_text",
  "key": "customer_name",
  "value": "John"
}

{
  "type": "set_entity",
  "key": "user_ssn",
  "value": "@ssn"
}

How to use

In any text response field of the node, use $ followed by the key name:

Hello, $customer_name! Your ID $user_ssn was verified successfully.

Your order #$order_number has status: $order_status

Scope

Context variables are persisted throughout the user's session with that chatbot. Once defined in a node, the variable is available in all subsequent nodes.

2. Prompt Variables: `${{variable}}`

Used in Generative Assistants. They are substituted before the prompt is sent to the AI model.

User-defined variables (ClientData)

Any data sent via client_data in the API becomes a variable accessible in the prompt:

# Creating a session with 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": {
      "customer_name": "Mary Smith",
      "plan": "premium",
      "phone": "+15551234567"
    }
  }'

In the assistant's Prompt field:

You are a support assistant for Company X.
You are talking with ${{customer_name}}, a customer on the ${{plan}} plan.
Always be polite and address the customer by name.

The text the model receives will be:

You are a support assistant for Company X.
You are talking with Mary Smith, a customer on the premium plan.
Always be polite and address the customer by name.

System built-in variables

These variables are automatically injected by the platform: you don't need to define anything:

`${{conhecimento}}`

Contains the knowledge base (RAG) snippets retrieved for the user's current message. Use in the CustomPrompt field to control where the context is inserted:

Use the information below to answer the user.
Do not invent information beyond what is documented.

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

If the information is not available above, say that you don't know.

Important: ${{conhecimento}} only works in the CustomPrompt field (not in the main Prompt). Enable the IsCustomPrompt flag to use it.

`${{horario}}`

Inserts the current date and time. Useful for agents that need to calculate scheduling dates or check times:

Current time reference: ${{horario}}

Use this reference to calculate future dates when the user mentions
"tomorrow", "next week", "next Friday", etc.

Where to use `${{variable}}`

3. Webhook Variables: `$paramName`

Used in the body, headers, and URL of webhook actions inside Generative Triggers. Unlike the other syntaxes, here it's a single $ without braces.

Automatic system variables

Always available in any configured webhook:

Variables from images sent by the user

When the user sends images in the conversation:

ClientData variables

Any key sent via client_data when creating/updating the session:

# Update session with new data
curl -X PUT https://api.verbeux.com.br/v1/session/{id} \
  -F "message=What is my balance?" \
  -F 'client_data={"user_id":"usr_123","account":"checking"}'

In the webhook: $user_id, $account

Trigger argument variables

The LLM extracts parameters from the conversation based on the parameters defined in the trigger. Those parameters become available as variables:

Trigger definition:

{
  "name": "check_order",
  "description": "Checks the status of an order by number",
  "parameters": {
    "type": "object",
    "properties": {
      "order_number": {
        "type": "string",
        "description": "Order number provided by the customer"
      }
    },
    "required": ["order_number"]
  }
}

In the webhook: $order_number

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

Full webhook example with variables

{
  "url": "https://crm.company.com/api/customers/$user_id/schedule",
  "method": "POST",
  "headers": [
    { "key": "Authorization", "value": "Bearer $access_token" },
    { "key": "X-Company", "value": "$company.id" },
    { "key": "X-Session", "value": "$session.id" }
  ],
  "body": {
    "customer": "$customer_name",
    "date": "$appointment_date",
    "service": "$service_type",
    "notes": "Scheduled via assistant. Session: $session.id"
  }
}

Substitution behavior

1. Order of application: longer parameters are substituted first (to avoid partial substitutions)
2. URL path: values are automatically URL-encoded
3. Headers and body: literal substitution (no encoding)
4. JSON body: strings are automatically JSON-escaped

4. Updating ClientData via Webhook Response

A webhook can return new data that is automatically merged into the session's client_data:

// Response from your webhook
{
  "session": {
    "client_data": {
      "account_balance": "$1,250.00",
      "last_transaction": "2025-03-07"
    }
  }
}

These values are immediately available as $account_balance and $last_transaction for subsequent webhooks in the same session.

5. Full Comparison Table