Variables

Dynamic Variables and Variable Extraction

Overview

Sulus provides two complementary systems for working with variables: dynamic variables for injecting values into prompts, and variable extraction (aliases) for pulling structured data out of tool responses and making it available to subsequent tools.

Dynamic Variables in Prompts

Dynamic variables let you personalize assistant messages by embedding placeholders using double curly braces (e.g., {{name}}) in your system prompt or any message.

Setting custom variable values is done via assistantOverrides.variableValues when initiating a call through the API — you cannot set them directly in the dashboard.

{
  "assistantId": "your-assistant-id",
  "assistantOverrides": {
    "variableValues": {
      "name": "John"
    }
  },
  "customer": {
    "number": "+1xxxxxxxxxx"
  },
  "phoneNumberId": "your-phone-id"
}

Default (built-in) variables are automatically populated and don't need to be set manually:

Variable	Description	Example
`{{now}}`	Current date and time (UTC)	Jan 1, 2024 12:00 PM
`{{date}}`	Current date (UTC)	Jan 1, 2024
`{{time}}`	Current time (UTC)	12:00 PM
`{{customer.number}}`	The customer's phone number	+1xxxxxxxxxx
`{{phoneNumber.number}}`	The Sulus phone number used	+1xxxxxxxxxx
`{{call.id}}`	Unique Sulus call ID	`5fe26c8e-...`
`{{call.type}}`	Type of call	`inboundPhoneCall` / `outboundPhoneCall` / `webCall`
`{{transport.conversationType}}`	Channel type	`chat` / `voice`

Advanced date/time formatting is supported via LiquidJS filters:

{{"now" | date: "%A, %B %d, %Y, %I:%M %p", "America/Los_Angeles"}}

→ Monday, January 01, 2024, 03:45 PM

You can also use LiquidJS conditionals to branch prompt behavior based on variables:

{% if transport.conversationType == "chat" -%}
- Use Markdown formatting for lists
{%- elsif transport.conversationType == "voice" -%}
- Never use Markdown format; write everything as if it is being said aloud
{%- endif -%}

Variable Extraction (Aliases)

Variable extraction lets you pull specific fields out of a tool's JSON response and store them in the call's variable bag for use in subsequent tool calls — enabling deterministic tool chaining.

The parameters (top-level, not function.parameters) field on a tool accepts { key, value } pairs where value supports Liquid templates that resolve against the variable bag at execution time.

{
  "type": "function",
  "function": {
    "name": "lookup_user",
    "parameters": {
      "type": "object",
      "properties": {
        "phone": { "type": "string" }
      }
    }
  },
  "server": { "url": "https://my-server.com/webhook" },
  "parameters": [
    { "key": "api_version", "value": "v2" },
    { "key": "caller_number", "value": "{{ customer.number }}" }
  ]
}

Variable Trust Tiers

Not all variables are equally trustworthy as a security boundary.

Tier	Variables	Safe as security boundary?
Tier 1 – Server-trusted	`{{customer.number}}`, `{{call.id}}`, `{{phoneNumber.number}}`, `{{transport.callSid}}`, custom keys set via `variableValues` at call start	Yes
Tier 2 – Conversation-derived	`{{messages}}`, `{{transcript}}`, `{{prompt}}`	No
Tier 3 – LLM-derived	Variables from `variableExtractionPlan` aliases, handoff-extracted variables, handoff LLM arguments	Never

Key distinction between the two parameters fields:

Field	Filled by	Visible to LLM?	Use for
`function.parameters` (JSON Schema)	The LLM at runtime	Yes	Values the caller speaks (intent, name, item)
`parameters` (top-level array)	You at config time	No	Server-known values (caller-ID, account ID, timestamps)

Passing Variables Across Handoffs

For handoff tools, variable extraction uses variableExtractionPlan on the destination. Variables extracted during a handoff are available to all subsequent assistants in the chain, and a new value replaces any existing variable with the same name.

{
  "type": "handoff",
  "destinations": [
    {
      "type": "assistant",
      "assistantName": "order-processing-assistant",
      "variableExtractionPlan": {
        "schema": {
          "type": "object",
          "properties": {
            "customerName": {
              "type": "string",
              "description": "Full name of the customer"
            }
          }
        }
      }
    }
  ]
}

Note: Handoff-extracted variables are LLM-derived (run against the conversation transcript) and should not be used as a security boundary.