Dynamic Variables¶

Dynamic variables let you personalize each conversation with runtime data. Use them to inject caller names, order IDs, account details, or any other information into your agent's system prompt, first messages, and tool configurations.

Syntax¶

Variables use double curly braces:

{{ variable_name }}

For example:

Hello {{ customer_name }}, how can I help you with order {{ order_id }} today?

Where to Use Variables¶

Variables can be used in the following places:

Location	Example
System Prompt	`You are assisting {{ customer_name }} who is a {{ customer_tier }} customer.`
First Messages	`Hello {{ customer_name }}, welcome to our support line.`
Tool URLs	`https://api.example.com/orders/{{ order_id }}`
Tool Request Bodies	`{ "customer_id": "{{ customer_id }}" }`

How Variables Are Defined¶

Variables are auto-detected from your system prompt. When you type {{ variable_name }} in the system prompt, SpeakNode automatically recognizes it and adds it to the agent's variable list.

You can also manually manage variables in the Variables section of the agent configuration.

Variable Properties¶

Each variable has the following properties:

Property	Description
Name	The variable name as used in `{{ name }}` syntax.
Type	The data type: `string`, `number`, `boolean`, or `integer`.
Description	A human-readable explanation of what this variable represents.
Default Value	The value used if the variable is not provided at runtime.
Nullable	Whether the variable can be `null` (omitted).

Tip

Always set a sensible default value or mark variables as nullable. If a required variable is missing at runtime and has no default, the raw {{ variable_name }} text may appear in the agent's speech.

Passing Variables at Runtime¶

There are three ways to supply variable values when starting a conversation:

1. API Dispatch¶

When starting a conversation via the API, include variables in the request body:

curl -X POST https://api.speaknode.com/api/v1/conversations/dispatch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "phoneNumber": "+1234567890",
    "variables": {
      "customer_name": "Alice",
      "order_id": "ORD-12345"
    }
  }'

When using the embedded widget, pass variables as URL query parameters:

https://your-site.com/support?customer_name=Alice&order_id=ORD-12345

The widget reads these parameters and passes them to the agent session.

3. Campaign Items¶

When running an outbound campaign, variables are mapped from Excel columns. Each row in the contact list provides variable values for that specific call.

Note

Variable names are case-sensitive. {{ customer_name }} and {{ Customer_Name }} are treated as different variables.

Example: Personalized Support Agent¶

System Prompt:

# Personality
You are a friendly customer support agent for Acme Corp.

# Context
You are speaking with {{ customer_name }}, a {{ customer_tier }} tier customer.
Their account ID is {{ account_id }}.

# Goal
Help the customer with their inquiry. If they ask about an order,
use the check_order tool with their account ID.

# Guardrails
- Never share information about other customers.
- If you cannot help, offer to transfer to a human agent.

First Message:

Hello {{ customer_name }}, thank you for calling Acme Corp. How can I assist you today?

When a call comes in with customer_name=Alice, customer_tier=Gold, and account_id=AC-789, the agent will greet Alice by name and have full context about her account.