Custom Code gambit

A Custom Code gambit runs a short piece of JavaScript in a sandbox, in the middle of a conversation. It reads the flow’s variables, and writes new ones back.

When to use it

Use it for the small transformations no other gambit does. Reformat a date, derive a total, normalize a phone number, pick a field out of an earlier API response. For fetching data, use API Call. For anything reusable across agents, write it as a CodeKit action instead.

The gambit and its editor

Every page in this section shows the same demo flow: Start, a Welcome message, the gambit this page covers, then End. The gambit sits third, selected, with its editor open on the right. The rest of the screen is dimmed. The editor holds Configuration and the Conditions switch. It has no Messages section.

Configuration

Field	What it does
JavaScript Code	A full code editor with syntax highlighting and line numbers. Ctrl+S, or Cmd+S on a Mac, saves, as the hint above it says.
Timeout (seconds)	A number field that accepts 1 to 120, with the hint max 120 beside it.

What the code can reach

The editor seeds a new gambit with a comment naming what is in scope:

// Write your code here
// Available: variables, setVariable(name, value), crypto, Buffer, stored keys
// Use a fresh IV per message: crypto.randomBytes(16) for CBC, crypto.randomBytes(12) for GCM. Never reuse a GCM IV.
return null;

variables is a read-only snapshot of the conversation, grouped into namespaces: response, api, post, flow, agent, system, utm, url, enduser, and trigger. An input gambit’s capture lives at variables.response.<name>, keyed by the name in its VARIABLE field.
variables.system.transcript holds the conversation so far. Tars loads it only when the code contains the word transcript. See Insert the conversation transcript.
setVariable(name, value) writes into the flow namespace. Read it back as variables.flow[name] in code, or as {{flow.name}} in messages and conditions.
The returned value is stored in this gambit’s own variable. Return null when the code only writes through setVariable.
crypto, Buffer, and secrets encrypt, decrypt, hash, and sign data. See Crypto and stored keys.

const eta = new Date(variables.response.order_eta)
setVariable("eta_pretty", eta.toDateString())
return null;

A Button gambit capture is an object, not a string. variables.response.<name>.value holds the value of the choice, and variables.response.<name>.label holds its button text.

Code that compares a Button capture to a string never matches. Read .value instead, as in the example below.

const plan = variables.response.plan_choice
if (plan?.value === "annual") setVariable("discount", 20)
return plan?.label ?? null;

An error does not stop the conversation. The flow moves on, and this gambit’s variable holds an object with an error field instead of a result. Guard against missing variables, and branch on that error field where a failure matters.

Crypto and stored keys

Custom Code has three more globals. The crypto and Buffer globals follow the standard server-side JavaScript API for the members below. The secrets global reaches the keys that your organization stores in Tars.

Global	Members
`crypto`	`createCipheriv`, `createDecipheriv`, `createHash`, `createHmac`, `randomBytes`, `getRandomValues`, `randomUUID`, `timingSafeEqual`, and `pbkdf2Sync`
`Buffer`	`Buffer.from`, `Buffer.concat`, `Buffer.alloc`, `toString`, `length`, indexing, and `slice`
`secrets`	`secrets.get(name)`, which returns a handle to the stored key with that name

The ciphers are aes-128-cbc and aes-256-cbc, with a 16-byte IV, and aes-128-gcm and aes-256-gcm, with a 12-byte IV. GCM adds setAAD, getAuthTag, and setAuthTag.
The digests for createHash, createHmac, and pbkdf2Sync are sha256, sha384, sha512, sha1, and md5.
The encodings are utf8, hex, base64, base64url, and latin1.

Admins add keys in Settings → Integrations → Encryption keys, under Custom code keys. A flow can use a stored key, but no code can read it, and Tars never shows a saved key again.

const key = secrets.get("partner_key")
const iv = crypto.randomBytes(12)
const cipher = crypto.createCipheriv("aes-256-gcm", key, iv)
const sealed = Buffer.concat([
  cipher.update(String(variables.response.order_id)),
  cipher.final(),
  cipher.getAuthTag()
])
setVariable("order_iv", iv)
return sealed;

A handle works only as a key: the key of a cipher, a decipher, or an HMAC, or the password of pbkdf2Sync. As data, an IV, or output, it throws secret handles can only be used as keys.
secrets.get with a name that matches no stored key exactly throws Unknown secret "<name>".
A Buffer in a setVariable value or in the returned value is stored as a base64 string.
update() can return an empty result, with all of the output coming from final(). Joined together, the two outputs are byte for byte what the standard crypto module produces.
pbkdf2Sync with a handle as the password returns a handle, which keeps the derived key out of output. It does not hide the derived key from flow editors, because code can recompute it with createHmac and the password handle.

Use a fresh IV for every message: crypto.randomBytes(16) for CBC and crypto.randomBytes(12) for GCM. Keep a fixed IV only for a partner that requires one.

Never reuse a GCM IV with the same key. A repeated IV leaks the difference between the two messages and lets an attacker forge new ones.

These limits apply to every run. Code that goes past one gets an error.

Limit	Value
Input to one crypto call	1 MB (1,048,576 bytes)
Crypto input in one run	8 MB (8,388,608 bytes)
One `randomBytes` or `getRandomValues` call	65,536 bytes
`pbkdf2Sync` work in one run	600,000 iterations across all calls. Iterations count once for each digest length the key needs, and double for `sha384` and `sha512`.
`pbkdf2Sync` key length	64 bytes
Derived-key handles in one run	64

Branching

The gambit has one Default branch, and a Conditions section that can route on anything the code wrote. See Flow control and branching.

Welcome

Core concepts

Guides

Developer

Custom Code gambit

When to use it

The gambit and its editor

Configuration

What the code can reach

Crypto and stored keys

Branching

​When to use it

​The gambit and its editor

​Configuration

​What the code can reach

​Crypto and stored keys

​Branching

​Related pages

When to use it

The gambit and its editor

Configuration

What the code can reach

Crypto and stored keys

Branching

Related pages