Skip to main content

​
What are Variables?

Variables allow your agent to access dynamic, contextual data during conversations. They can inject user information, custom values, or external data into instructions and API tool configurations—making your agent responses personalized and context-aware.

​
Variable Types

​
Auth Variables

Auth variables are automatically provided based on the message sender’s context. They include:
  • sender.uid – unique identifier of the message sender
  • sender.name – display name of the message sender
  • sender.role – role of the message sender
Syntax: @var-auth:variableName (e.g., @var-auth:sender.uid)

​
Custom Variables

Custom variables are user-defined values that you create and manage. They support different source types:
  • Constant – static text that never changes (e.g., API keys, company name)
  • Message Metadata – extracts data from message.data.metadata (e.g., orderId, sessionType)
  • User Metadata – extracts data from the sender’s user metadata (e.g., subscription, department)
Syntax: @var-custom:variableName (e.g., @var-custom:apiKey)

​
Adding Variables

​
Create a Custom Variable

  1. In Agent Builder, open the Variables section.
  2. Switch to the Custom Variables tab.
  3. Click + Add Custom Variable.
  4. Configure the variable:
    • Name* – identifier used in syntax (e.g., companyName)
    • Description – optional note for your reference
    • Source Type* – where the value comes from (Constant, Message Metadata, or User Metadata)
    • Value/Path – the actual value or path to extract from
  5. Save to make the variable available.

​
Using Variables

​
In Instructions

  1. Type @ in the Instructions Editor.
  2. Navigate to Auth Variables or Custom Variables category.
  3. Select a variable to insert it.
You can also copy the syntax from the Variables list and paste it directly into the Instructions Editor.

​
In API Tools

​
Variable Display

Variables appear as styled chips in editors, showing the full syntax (e.g., @var-auth:sender.name). This makes it easy to identify where dynamic data will be inserted.

​
Orphaned Variables

If a variable is deleted or renamed after being used, it will display with a warning indicator. Update your instructions or API tools to use the correct variable name.

​
Best Practices

  • Use descriptive names that indicate the variable’s purpose.
  • Document sensitive variables appropriately for team awareness.
  • Test variable substitution in the Test console before deploying.
  • Review the “In Use” status to track where variables are referenced across agents.