Variables
A variable is a piece of data YourCalls substitutes into a prompt, a webhook body or a workflow step. Every variable has one name, and that name is the same everywhere it appears, in an assistant's prompt, in a tool's request, and in a workflow.
Names are grouped by what they describe.
| Group | Examples | Where it works |
|---|---|---|
contact.* | contact.first_name, contact.email, contact.postcode, contact.custom.age | prompts, tools and workflows, on voice and chat |
form.* | form.email, form.enquiry_type | chat only. The answers a visitor gave before the chat started |
call.* | call.customer_phone, call.direction, call.started_at, call.summary | voice only. Transcript, summary, recording, duration, ended reason and outcome exist only after the call |
chat.* | chat.session_id, chat.origin, chat.transcript | chat only. Transcript, summary, duration and message count exist only after the chat |
assistant.* | assistant.name, assistant.phone | everywhere. assistant.phone is the number this conversation is on |
company.* | company.name, company.phone, company.email | everywhere. company.phone is your business's own number |
vars.* | vars.promo_code | everywhere. Values you send with an API call, or that a before-call tool returns |
extracted.* | extracted.callback_time, extracted.customer_email | tools and workflows, during and after a conversation. Not available in a prompt |
tool.* | tool.run_id, tool.call_id | tools and workflows |
| Date and time | {{now}}, {{currentDateTime}}, {{date}}, {{time}}, {{year}}, {{month}}, {{day}} | everywhere |
Writing a variable
Wrap the name in double braces.
Hi {{contact.first_name}}, thanks for calling {{company.name}}.
Names are lower case with underscores. {{contact.first_name}} works; {{contact.firstName}} and {{First Name}} do not. The date and time names above are the one exception and keep their spelling.
The same rule applies to the names you choose yourself. Values you send with an API call in variables, and values a before-call tool returns, arrive as vars.<name>, and the name must be lower case with underscores. {{vars.promo_code}} works. {{vars.promoCode}} is not a valid variable at all, so it renders as nothing wherever you put it. Name the value promo_code when you send it and the variable is there waiting.
The full list
Contact
Available in prompts, tools and workflows, on voice and chat.
| Name | Holds |
|---|---|
contact.id | The contact's ID in YourCalls |
contact.salutation | Title, such as Mr or Ms |
contact.first_name | First name |
contact.last_name | Last name |
contact.email | |
contact.phone | Phone |
contact.job_title | Job title |
contact.company_name | Company |
contact.address_line1 | Address line 1 |
contact.address_line2 | Address line 2 |
contact.city | Town or city |
contact.county | County |
contact.postcode | Postcode |
contact.country | Country |
contact.source | Where the contact came from |
contact.sms_opt_out | Do not text |
contact.call_opt_out | Do not call |
contact.email_opt_out | Do not email |
Your own fields are contact.custom.<key>, covered below.
A call placed through the API fills these in for a new contact from the variables you send, so {{contact.first_name}} works on the first call to a new lead. See Variables also fill the contact.
Call
Voice only.
| Name | Holds |
|---|---|
call.id | The call's ID in YourCalls |
call.direction | inbound, outbound or web |
call.customer_phone | The other party's number |
call.started_at | When the call started |
call.campaign_id | The campaign that placed the call, when there is one |
call.call_request_id | The request that placed the call, when there is one |
call.lead_id | The lead the call belongs to, when there is one |
These exist only once the call has ended, so only a tool or workflow that runs after the call can read them.
| Name | Holds |
|---|---|
call.ended_at | When the call ended |
call.duration_seconds | How long the call lasted |
call.ended_reason | Why the call ended |
call.transcript | Full transcript |
call.summary | Summary of the call |
call.recording_url | Link to the recording |
call.outcome | The outcome recorded against the call |
Chat
Chat only.
| Name | Holds |
|---|---|
chat.session_id | The chat's ID in YourCalls |
chat.started_at | When the chat started |
chat.origin | The site the chat was opened from |
chat.visitor_id | The visitor the chat belongs to |
These exist only once the chat has ended.
| Name | Holds |
|---|---|
chat.ended_at | When the chat ended |
chat.duration_seconds | How long the chat lasted |
chat.message_count | How many messages were exchanged |
chat.transcript | Full transcript |
chat.summary | Summary of the chat |
Assistant and company
Available everywhere.
| Name | Holds |
|---|---|
assistant.id | The assistant's ID in YourCalls |
assistant.name | The assistant's name |
assistant.phone | The number this conversation is on |
company.name | Your business name |
company.phone | Your business's own number |
company.email | Your business email |
company.industry | Your industry |
company.country | Your country |
company.timezone | Your time zone |
assistant.phone and company.phone are different things. assistant.phone is the number the caller dialled, or the number the assistant dialled from. company.phone is the number on your account.
Tool
Available in tools and workflows.
| Name | Holds |
|---|---|
tool.run_id | The ID of this tool run |
tool.call_id | The ID of the conversation the tool ran on |
tool.tool_call_id | The ID of this individual tool call |
Date and time
Available everywhere, and written without a group name.
{{now}}, {{currentDateTime}}, {{date}}, {{time}}, {{year}}, {{month}}, {{day}}
Groups you name yourself
These have no fixed list, because you decide what goes in them.
form.<key>is an answer from your chat form, using the key you gave the question.vars.<name>is a value you sent with an API call, or one a before-call tool returned.extracted.<name>is a value the assistant pulled out of the conversation, using the name you gave the extracted field.contact.custom.<key>is one of your own contact fields.
Custom contact fields
Fields you add on the Contact Fields page are available as contact.custom.<key>, for example contact.custom.age. The key is shown next to each field on that page.
Archiving a field takes its variable away with it. A tool that still uses the archived field's name cannot be saved until you remove the name, so change the tool before you archive the field.
Tools check their names when you save
Tools are saved through the platform, so their names are checked at that point and a save is refused when one cannot work. A save is refused when a tool uses a variable that does not exist at the moment it runs, such as {{call.transcript}} on a before-call tool, when it uses a contact field that no longer exists, and when a body field is named one the platform sets itself, such as toolRunId. Correct the name and save again.
Variables in a tool's web address
A variable can be used in the path or the query of a tool's request URL, and nowhere else in it. https://api.example.com/customers/{{contact.id}} and https://api.example.com/customers?id={{contact.id}} both work.
The address itself is fixed. https://{{vars.region}}.example.com/customers does not work, because the variable would decide where your data is sent. A tool with a variable in its address cannot be saved, and a tool already set up that way stops running until you correct it. The address must also be a full https:// address before it can carry a variable anywhere.
Values that go into the path and the query are escaped for you, so a value containing a / or a ? cannot re-point the request.
What happens when a value is missing
A variable with no value renders as nothing, and the assistant is told to carry on without it.
In a prompt, the Available Context list the builder writes for you leaves out any line whose value is blank, so the assistant never reads out an empty label. A name you type into your own instruction text simply renders as nothing, and the words around it stay.
In a webhook body, a missing value is sent as an empty string, "", and its name is recorded against that tool run. To see which mapping came up empty, run the tool's Test Now and read the body your endpoint receives.
Testing
The builder's test call and a tool's Test Now both run on the same variables as a real conversation, with the sample values you type substituted in. Nothing about a test uses a separate set of names, so a value that resolves in a test resolves live.
A test call always previews an outbound conversation, so {{call.direction}} reads outbound even when the assistant is an inbound one.
A tool's Test Now lists every name it had no value for under Not filled in, in red with the reason beside it. The test is still sent, which is the quickest way to see exactly what your endpoint receives when a value is absent.
The builder's test call does not list those names. It still places the call, and any name with no value renders as nothing.
contact.* versus extracted.*
contact.* is what YourCalls already knew before the conversation started. extracted.* is what the conversation produced.
A caller's name that came from your CSV is {{contact.first_name}}. A callback time the caller asked for is {{extracted.callback_time}}.