Variables

How to use dynamic variables for personalized agent responses using the Syllable Console interface.

Variables enable dynamic content substitution throughout the Syllable platform. They allow you to create personalized, context-aware experiences by automatically replacing variable placeholders with actual values during runtime.

Syntax

The platform supports three variable substitution formats. Each behaves differently when a variable is missing and supports different features.

Syntax	When variable exists	When variable is missing	Default value
{variable}	Replaced with value	Left as literal {variable}	No
${variable}	Replaced with value	Replaced with empty string	Yes: ${var=fallback} or ${var=$other}
{{ variable }}	Replaced with value	Replaced with empty string	No

Variable names can include letters (A–Z, a–z), numbers (0–9), underscores (_), and periods (.). No spaces or other symbols are allowed inside the variable name.

For {{ variable }}, spaces around the variable name are ignored, so {{ x }} and {{x}} are equivalent.

${variable} and spaces: Unlike {{ variable }}, ${...} does not trim or ignore spaces inside the braces. ${ agent_name } will not resolve; use ${agent_name} with no spaces around the name.

Choosing the right syntax

• {{ variable }} — Default for most cases: greetings, tool descriptions, tool static parameters. When the variable is missing, it becomes an empty string. Use this when you want missing values to disappear from the output.

• {variable} — Use when you want the model to see the placeholder if the variable is missing. For example, Hello {name} keeps Hello {name} in the prompt when name is not set, so the model can adapt instead of seeing Hello with no indication a name was expected.

• ${variable=fallback} — Use when a missing value should resolve to a specific default value. You can use a static default (e.g. ${vars.provider_name=your provider}) or another variable (e.g. ${vars.provider_name=$vars.pcp}). Only ${...} supports resolving to a specific default value, {{ variable=default }} is invalid and will not provide a fallback.

Variable Types

System Variables

System variables provide access to platform-managed data and session context. Use the vars.session.* path for these values (for example {{ vars.session.agent.name }}). Shorter forms such as {{ vars.agent_name }} do not resolve session fields—even when a similarly named custom variable exists, they resolve to empty.

• {{ vars.session.id }} - Unique identifier for the current session
• {{ vars.session.agent.name }} - Name of the current agent
• {{ vars.session.datetime }} - Current timestamp, e.g., 2025-01-02 12:00
• {{ vars.session.date }} - Current date, e.g., 2025-01-02
• {{ vars.session.day_of_week}} - Current day of week, e.g., Tuesday
• {{ vars.session.timezone}} - Agent’s timezone, e.g., America/Los_Angeles
• {{ vars.session.language }} - Current language code for the session, e.g. en-US
• {{ vars.session.source }} - ANI, e.g., “[phone]”
• {{ vars.session.target }} - DNIS, e.g., “[phone]”

Custom Variables

Custom variables are the values you configure on the agent (for example company name, customer name, or other fields you define). Reference them by name with no vars. prefix in templates—for example {{ agent_name }} or {{ customer_name }}.

Using {{ vars.<name> }} for a custom agent variable does not work as a shorthand: for example {{ vars.agent_name }} resolves to empty even when agent_name is set. Use {{ agent_name }} instead.

• {{ custom_field }} — A user-defined variable configured on the agent (bare name, not vars.custom_field for substitution in prompts and messages)

Usage Examples

In Prompts

Variables can be used within prompt content to create dynamic, personalized instructions:

You are a helpful customer service agent for {{ company }}.
The current location is {{ location_info }}
The current date is {{ vars.session.date }}.

Greet the user: Hello {customer_name}

Substitution runs before the text is sent to the model. If customer_name is not set, {{ customer_name }} becomes Hello (empty string)—the model never sees the double-curly placeholder. With {customer_name}, the placeholder stays literal in the prompt when the value is missing, so the model can see Hello {customer_name} and adapt.

Messages

Create dynamic greeting messages that adapt to different contexts:

Hello! Thank you for calling {{ company }}. 
My name is {{ vars.session.agent.name }} and I'm here to help you today.

{{ business_hours_message }}

Tool Descriptions

Make tool descriptions more contextual and informative:

{
  "function": {
    "name": "schedule_appointment",
    "description": "Schedule an appointment for {{ customer_name }} at {{ location_name }}. Current time: {{ timestamp }}"
  }
}

Tool Static Parameters

Use variables to set dynamic default values for tool parameters:

{
  "staticParameters": [
    {
      "name": "customer_id",
      "default": "{{ account_id }}",
      "description": "Customer account identifier"
    },
    {
      "name": "session_context",
      "default": "{{ vars.session.id }} - {{ vars.session.language }}",
      "description": "Session tracking information"
    }
  ]
}

Best Practices

Choose the right syntax for the context

• Use {{ variable }} for greetings, tool descriptions, and static parameters when missing values should become empty.
• Use {variable} in prompts when you want the model to see the placeholder when the variable is missing.
• Use ${variable=fallback} when you need a default value. Common pitfall: {{foo=bar}} does not work as a default—only ${foo=bar} supports default values.

Variable Naming

• Use descriptive, lowercase names with underscores for readability
• Custom agent variables: use the bare name in templates ({{ customer_name }}), not {{ vars.customer_name }}
• System/session fields: always use vars.session.* (for example {{ vars.session.date }})
• Avoid spaces and special characters in variable names

Good examples:

• {{ customer_name }} (custom variable configured on the agent)
• {{ vars.session.agent.name }} (system variable)
• {{ order_number }} (custom variable)

Avoid:

• {{ Customer Name }} (spaces)
• {{ vars.customer-name }} (hyphens)
• {{ CUSTOMER_ID }} (all caps)

Error Handling

Variables that cannot be resolved will typically:

• Be replaced with blank values when using {{ variable }} or ${variable} (e.g., Welcome, {{ unknown_var }}! becomes Welcome, !)
• Be left as literal text when using {variable} (e.g., Hello {name} stays Hello {name} if name is missing)
• Not break the overall functionality

Always test your variable usage to ensure proper resolution.

Security Considerations

• Never expose sensitive information through variables
• Validate custom variable values before use
• Be cautious when using variables in tool parameters that make external API calls

Troubleshooting

Variable Not Resolving

If a variable is not replaced or replaced with a blank string instead of its expected value:

1. Check spelling - Variable names are case-sensitive
2. Verify scope - Ensure the variable is available in the current context, for example, a prompt can only reference variables that are available at the start of the session
3. Check syntax - Confirm you’re using the intended format: {{ }}, ${}, or {} depending on the behavior you want
4. Validate data source - For custom variables, ensure the data source is properly configured

Variable appears as literal {variable} in output

If you see the placeholder (e.g. {customer_name}) in the final text instead of a value, you are using the {variable} syntax and the variable is missing. That format intentionally leaves the placeholder in place. With {{ customer_name }}, a missing value becomes an empty string—you would not see {{ customer_name }} literally in the output. To get an empty string when the variable is missing, use {{ variable }} or ${variable} instead—or ensure the variable is set.

Syntax comparison and equivalents

• {{ variable }} and ${variable} both yield an empty string when the variable is missing. Use either when you want missing values to disappear.
• {variable} is the only format that leaves the placeholder in the text when the variable is missing—useful in prompts where the model should see the placeholder.
• Default values are only available with ${variable=default_value}; the {{ }} syntax does not support =default.

Related Documentation

• Prompts - Learn how to use variables in prompt content
• Tools - Discover variable usage in tool configuration
• Messages - Implement variables in greeting messages
• Agents - Configure agent-level variable settings