urvo - Documentation

Overview

A dynamic variable is a placeholder you write into an agent's prompt, greeting or tool configuration, and fill with a different value on every call. It is how one agent greets a thousand people by name instead of saying "Hi there" to everyone.

You reference one with double curly braces:

Hi {{customer_name}}, I'm calling about your order {{order_id}}.

There are two kinds:

Custom variables that you declare and supply.
System variables that urvo fills in automatically, covered below.

Declaring a custom variable

Open the agent, go to Configuration, and find Dynamic Variables. Add each variable with a name and a default value.

Naming rules:

Letters, numbers and underscores only.
Must start with a letter or an underscore — it cannot start with a number.
Cannot begin with system__, which is reserved for urvo's own variables.

Always set a default

The default is used whenever a call does not supply a value. This is the single most important thing to get right on this page:

If a prompt references a variable that was never declared, and no default exists, the call fails. It does not quietly substitute an empty string or leave the placeholder text in place. So a typo in a prompt placeholder, or a CSV column you forgot to include, becomes a failed call rather than a slightly odd greeting.

Give every variable a sensible default even when you expect it to always be supplied — for example there for a first name, so a missing value produces "Hi there" instead of a dropped call.

Supplying values per call

A value can reach a call from several places:

Outbound campaigns. Any column in your recipient CSV that is not a recognised override column is passed through as a dynamic variable. A customer_name column fills {{customer_name}}. See outbound calls.
Workflows. The call-initiating and call-scheduling actions accept call context that becomes available to the agent. See urvo pieces.
Tool responses. A webhook tool can extract fields from its JSON response into dynamic variables mid-conversation, so a value looked up on the call becomes usable later in the same call. See webhook tools.

System variables

urvo injects these automatically on every call. They are read-only — you reference them but never declare or set them. The dashboard lists them behind a System variables reference dialog in the same section.

Variable	Value
`system__caller_id`	The caller's phone number, on inbound calls
`system__called_number`	The number that was dialed
`system__call_duration_secs`	Call duration so far, in seconds
`system__time_utc`	Current time in UTC, ISO 8601
`system__timezone`	The agent's configured timezone
`system__conversation_id`	Unique id for this conversation
`system__agent_id`	The agent handling the call

A useful pattern: pass system__caller_id into a webhook tool to look the caller up in your own system before the agent says anything substantive.

Note that system__time_utc is UTC. If you want the agent to reason about the caller's local working hours, combine it with system__timezone rather than assuming the two match.

Troubleshooting

Symptom	Cause	Fix
Calls fail immediately	The prompt references a variable that is not declared and has no default	Declare it with a default, or fix the placeholder spelling.
Agent says the default instead of the real value	Nothing supplied a value for that call	Check the CSV column name or workflow mapping matches the variable name exactly.
Variable name rejected	Starts with a number, contains a hyphen or space, or uses the `system__` prefix	Rename using letters, numbers and underscores, starting with a letter.
Placeholder read aloud verbatim	Single braces, or a mismatched name	Use double braces and confirm the name matches the declared variable.

Next steps

Overrides — change the agent's language, greeting or voice per call rather than injecting values.
Agent instructions — writing prompts that use variables well.