Skip to main content
At the end of this page, you can insert any captured value into messages, prompts, conditions, API calls, and tool settings.

​
Before you start

Before you start, sign in to the dashboard and select the organization you want to work in.
  • Open an agent in the builder and select a gambit, so the gambit editor panel is open.

​
Where variables come from

References use the form {{namespace.name}}, except for the local current list item, {{item}}. An optional path after the name selects nested values, as in {{enduser.social.linkedin}}. The variable panel groups references by the source that produced them. The panel shows a group only when the flow has variables for it. A Button gambit’s answer also has a label. {{response.<variable>}} and {{response.<variable>.value}} read the selected value, and {{response.<variable>.label}} reads the button text the end user saw. See Read the selected value and label. The enduser values are filled from the end user’s profile when the conversation starts, on Web and on WhatsApp. A conversation that an end user starts on WhatsApp fills the trigger group. The opening message is in trigger.userMessage and trigger.text. For a tapped option, both hold its label. With personal data protection on, both hold the protected text. trigger.channel, trigger.channelUserId, trigger.channelMessageId, and trigger.timestamp describe the message itself. trigger.senderPhone and trigger.senderName come from WhatsApp, while enduser values come from the end user’s profile. Tars never overwrites a trigger value that is already set, so campaign data and an inbound trigger’s payload stay as they arrived. For a web conversation, the system group also holds the end user’s location. The country code is system.country, and the region or state code is system.region. The city is system.city, and the IANA time zone, such as Europe/London, is system.timezone. Tars reads these values when the widget page loads and stores them when the conversation is created.

​
Name the variable a gambit captures

Every gambit names its captured value in the VARIABLE field, next to LABEL at the top of the gambit editor. The name follows the label until you edit it by hand, and it must be unique within the agent. Gambit mastery describes the full editor anatomy. When you rename a variable, Tars rewrites its {{...}} references across messages, conditions, and gambit settings.
Custom code reads variables by bare name, and a rename does not touch those reads. Check every code gambit after you rename a variable.

​
Insert a variable

The same panel works in every field that accepts variables. In the Messages section, the message toolbar shows the hint @ for variables.
1

Place the cursor where the value should appear

For an agent message, open the gambit’s Messages section and click into a message.
2

Type @ to open the variable panel

The panel opens at the cursor, with a Search variables… box on top. Below it, each group header shows a colored dot, its name, and a count.
The variable picker with its search box, User Responses expanded to show response.welcome, System, Marketing, End User, and Trigger / Inbound group headers
3

Find the variable

User Responses starts expanded, and the other groups start collapsed. Select a group header to expand it. Keep typing after the @, or use the search box, to filter and expand every group.
4

Select the variable

Move with the arrow keys and insert with Enter, or click the entry. Press Escape to close the panel without inserting. The panel only offers variables from gambits that lead into the one you are editing.

​
The current list item

Four settings build one entry for each item in a list variable:
  • An auto-populated Button option
  • An auto-populated Card
  • Auto Suggestion with From Variable
  • A Component gambit list input in Workflow Mode, bound to a list variable
In those settings, the variable panel adds a Current List Item group at the top. Pick it to insert {{item}}, the list entry that Tars is building at that moment. For a list of objects, select the pill and add a field, such as {{item.name}}. {{item}} exists only inside those settings. Elsewhere in the flow, the panel does not offer it. See Button gambit, Card gambit, Auto Suggestion gambit, and Component gambit.

​
Insert the conversation transcript

{{system.transcript}} holds the conversation so far as plain text. Find it in the System group of the variable panel. Use it in messages, Live Chat gambit messages, AI Agent instructions, API request bodies, custom code, and channel messages. Each message starts with its sender, and a blank line separates messages. An attachment shows as its kind and file name in square brackets.
Tars loads the transcript only when a field uses it, and it does not store the transcript with the other variables. A long transcript keeps the newest messages and starts with [Transcript truncated]. The limit is 60,000 characters, or 20,000 in AI Agent instructions. In a message, Tars also shortens the transcript to fit the channel’s message limit. In custom code, read it as variables.system.transcript. Tars loads it for a code gambit only when the code contains the word transcript.
system.transcript cannot go in a URL, a header, a channel message recipient, or the Visitor Identity fields of a Live Chat gambit. Saving the gambit fails until you move the reference into a message or a request body.
If Tars cannot load the transcript, an API call, tool, or channel message that uses it fails with the error code TRANSCRIPT_UNAVAILABLE. The Test button of an API Call gambit sends a request without a conversation. To check the transcript, run the flow in Test Mode and select Inspect transcript in the Variables section.

​
Read hidden data from a webhook campaign

A webhook campaign call can send a data object with the recipient. The recipient never sees it. When the end user replies, the reply conversation holds the object in trigger.data. Read a key as {{trigger.data.<key>}}. Read a nested value with a longer path, as in {{trigger.data.cart.total}}. The caller of the API chooses the keys. The variable panel lists data in the Trigger / Inbound group. Pick it, then select the pill and add the key, such as {{trigger.data.cart}}.
  • A top-level key starts with a letter or digit, and holds only letters, digits, and underscores. It has up to 40 characters.
  • An object prints as JSON. So does an array, except that an array of text values prints one item per line in a message.
  • Tars does not evaluate {{...}} text inside a value. It drops the opening {{ when it prints the value.
  • The data is available only when the end user replies within 72 hours of the send.
  • If one number has several open sends in those 72 hours, a reply uses the data and url values of the newest send. This holds even when the end user tapped a button on an older message. A send is open while its status is sent, delivered, or read. See The reply window.
  • If the newest send to that number already has a reply, a later reply does not use the data of an older send.
Treat every value as untrusted input from the API caller. Check a value before you use it in custom code, an API call, or a condition.

​
How an inserted variable renders

The inserted variable becomes a pill that shows the full reference, such as {{enduser.name}}. Each panel group has its own color, and the pill keeps the color of its group. When the conversation runs, the pill resolves to the captured value.
  • Drag a pill by the grip icon on its left edge to move it.
  • Select the pill text to edit the path part in place. Press Enter to apply or Escape to cancel.
  • A path that no test response has confirmed gets a dashed amber outline. Hover it to see the unverified marker.

​
Fill the API Responses group with real fields

An API Call gambit exposes its captured response under {{api.<variable>...}}, plus .status, .ok, .error, and .raw. To make the panel suggest the real response fields, send a test request first.
1

Open the API Call gambit's Configuration section

Set up the request as usual.
2

Select Test

The Test button sends a real request. The fields of the response become suggestions in the variable panel and in pill path editing.
3

Pick the sampled fields where you need them

The section’s hint counts the fields learned from your last test. Select Clear in the hint to forget the sample.
You can still type any path by hand without a sample. The pill marks it unverified until a test response confirms it.

​
Verify

Select Test in the builder toolbar to open the Test Mode panel, and run the conversation. The Variables section fills as each step captures a value, and every pill resolves to the value shown there. To force a value mid-run, select the pencil icon next to it, which works for User Responses and Flow Variables. See Test your agent for the full panel.