Skip to main content

Deny by default

The Code Step validator rejects any function or method call that is not on the allow-list below. Validation runs before execution, so disallowed calls never run. This page covers the Code Step inside a call script. The Code step in an automation pipeline is a separate sandbox with its own list of functions — see Steps.

Built-in Functions

print(...) writes a user-facing system note for Code Step diagnostics. It supports multiple values plus sep and end; multi-line output is split into separate system notes. range accepts range(stop), range(start, stop), and range(start, stop, step). sleep(seconds) pauses the Code Step for that many seconds before it carries on. The call waits with it, so keep pauses short (a second or two), for example to give an SMS reply time to arrive before reading it.

Allowed Methods

Most allowed methods are string methods. get is allow-listed for dictionary-style values, and append is allow-listed for list-building.

Flow Helpers

  • coalesce(value, default) — returns default when value is None or ""
  • is_empty(value) — true for None, "", [], or {}
  • is_not_empty(value) — the inverse of is_empty
  • map_value(key, mapping, default) — lowercases and strips string keys before lookup

Type Helpers

is_number returns true for int or float, but false for bool.

Object and Path Helpers

Prefer {{...}} placeholder syntax for normal variable access. Use these helpers when working with dynamic dictionaries inside the code.
  • commit_contact_timezone(iana, state, city) — validates an Australian IANA timezone, updates the current contact’s timezone and location, refreshes runtime calendar timezone state, and writes the canonical {{contact.*}} and {{timezone.*}} result variables. With no arguments it reads {{timezone.resolved_iana}}, {{timezone.resolved_state}}, and {{timezone.resolved_city}}.
  • commit_composite_outputs() — inside a sub-flow, commits declared parent composite output variables before the sub-flow returns, and returns the sorted output ids it mapped. Outside a composite context it returns an empty list.

Date Helpers

parse_datetime uses Python ISO parsing:
timezone_offset(iana, at) returns the UTC offset for an IANA timezone at a specific datetime. If at is omitted it uses the current datetime; if at has no offset it is treated as local wall time in the supplied timezone. Invalid input returns "".

Random Helpers

  • random_int(min_value, max_value) — an integer between the bounds, inclusive
  • random_choice(values) — one item from a non-empty list, or None when empty
  • random_shuffle(values) — a shuffled copy of the list; the original is not mutated

Voice Helper

Switches the voice the assistant speaks with, part-way through the call. Everything said after the Code Step uses the new voice. There is no pause and no reconnection — the change happens between one line and the next. voice_id is the identifier of a voice in the Voice Library. It is not the voice’s name.
  • Returns True when the voice was accepted, so you can branch on it.
  • Returns False when the value is not a valid voice identifier. The call keeps the voice it already had, and a note is recorded on the call so you can see it happened. It never stops the Code Step.
  • The switch is applied as soon as run() finishes, before the flow moves to the next step.
To get the identifier for a voice, speak to the Voxworks team for further custom configuration.

Speech Recognition Helper

Replaces the call’s speech-recognition keyword list from inside a Code Step. It does the same thing as the Keywords | Set tool, and reads its value the same way.
  • values is a comma-separated string ("fascia, soffit, guttering") or a list of strings. Each term is trimmed, and empty terms and {{...}}-shaped terms are dropped. set_keyterms() with no value, or an empty value, clears the list.
  • It replaces the list; it never adds to it.
  • The new list takes effect at the next speaking step, exactly as the tool does.
  • Returns True when the list was set or cleared, with a note on the call naming the keywords. Returns False (with a note on the call) for a value that is not a string or a list. It never stops the Code Step.

Language Helper

Switches the language the call is held in, part-way through the call. From the next step on, the assistant listens and speaks in the new language. Your script, conditions, knowledge base and tools keep working in English: what the caller says is translated into English before the assistant reads it, and every line is translated out of English just before it is spoken.
  • code is a language code such as "es" (Spanish), "vi" (Vietnamese) or "ar" (Arabic). set_language("en") switches back to English. Regional English codes such as "en-AU" are accepted and mean English.
  • voice_id is optional. Pass a voice identifier to switch to a voice that speaks the language natively at the same moment. It takes priority over a separate set_voice(...) in the same Code Step.
  • Returns True when the request was accepted and False for an unknown language code or voice identifier, so you can branch on it. On False the call keeps its current language and a note is recorded on the call. It never stops the Code Step.
  • The switch is applied as soon as run() finishes, before the flow moves to the next step.
The call’s transcript shows each translated turn as it was heard or spoken, with the English underneath. For the list of supported language codes and the matching native voices, speak to the Voxworks team for further custom configuration.

Schedule Helper

Returns True when a routing endpoint’s schedule is open right now, and False when it is closed. endpoint_id is the identifier of a routing endpoint (see Routing Endpoints). The check uses the same schedule the Handoff tool would use: the endpoint’s own schedule, or the default from its department, location or team. It is evaluated at the moment the Code Step runs, so a call that crosses closing time gets the right answer.
Route the true result to the transfer and the otherwise result to your out-of-hours wording. An identifier that doesn’t match an endpoint is checked against the team’s default schedule, and the helper returns True when no schedule applies, so make sure the identifier is correct.

Turn-Timing Helpers

These adjust the assistant’s timing for the rest of the call, on top of each step’s own settings.
  • idle_offset(seconds) adds seconds to how long the assistant waits in silence: both the wait before it re-prompts a quiet caller and the wait before it ends a silent call. See Silence Tolerance. The quick move-on after a statement (Fast Response) is not affected.
  • endpoint_offset(seconds) adds seconds to how long the assistant waits after the caller stops speaking before it replies. See Response Eagerness. The wait never drops below the built-in minimum.
For both:
  • The last call wins; the offsets don’t add up. idle_offset(0) or endpoint_offset(0) clears the offset.
  • Negative values shorten the waits.
  • They return True when accepted and False (with a note on the call) for a value that isn’t a number. They never stop the Code Step.

Routing Helpers

These are the location lookups behind the Routing | Service Location - v0.2 tool. service_location_propose takes the caller’s own words for a state and suburb and returns the best-matching locality. service_location_resolve takes a four-digit postcode. Both return a dictionary with a status and the routing endpoints that cover the area, and never raise an error: a failed or slow lookup returns {"status": "error", ...}. Most scripts should use the tool rather than calling these directly.

List Lookup

Matches what the caller said against one of your match lists and returns the best entries. Pass the list’s name and the words to match, by position or as list= and text=.
lookup reads only your own team’s lists and the shared lists. It always returns a dictionary, and every key below is always present, so you can read them without .get guards: Each entry (top, runner_up and each item of candidates) is a dictionary with: When status is "none", reason is one of:
  • bad_args — the call was wrong: no list name, an empty one or one that is not a string, a third argument, or any keyword other than list and text. Nothing is looked up, and a note is recorded on the call.
  • no_team — the call has no team, so there are no lists to read.
  • timeout — no answer within 0.3 seconds.
  • lane_unavailable — the matcher could not answer.
  • not_loaded — the list is not available right now. A note is recorded on the call.
  • no_input, unknown_list, empty_text, too_long, no_candidate, schema_mismatch, stage_error — the matcher’s own answers: for example, no list by that name (unknown_list), no words to match (empty_text), or nothing close enough (no_candidate).
lookup never raises an error into your code. A failure is always status "none" with a reason, so the step still routes. Some rules for using it well:
  • Route on status and top["match_id"], never on label. The answer follows the list’s current entries and aliases, so it can change when the list changes, without a script change.
  • Call it once per turn, on the list you need. Each call waits up to 0.3 seconds.

Matching Helpers

Matches spelled or read-out characters, such as a claim number or a reference code, in the caller’s words. It is a word-list matcher, not an AI model: it finds a match or nothing. Before returning, it writes three variables under the prefix:
  • {{<prefix>.temp_match_tokens_json}} — the matched tokens, as a JSON array
  • {{<prefix>.temp_match_residue}} — the words that matched nothing
  • {{<prefix>.temp_match_coverage}} — the share of the words that matched, from 0 to 1
It returns True when anything matched. On any failure (a bad prefix, no answer in time) it writes the empty values ("[]", "", 0) and returns False. It never stops the Code Step. Variables under survey.* must be declared in the script’s variables, or the writes are skipped.

Booking Helpers

These book an appointment from a Code Step, using the call’s calendar connection. datetime_match(...) reads a day and time from the caller’s words. It is a word-list matcher, not an AI model: it finds a match or nothing. Before returning, it writes four variables under the prefix:
  • {{<prefix>.temp_match_entries_json}} — the days and times the caller named
  • {{<prefix>.temp_match_candidates_json}} — up to two matching available times, when slots_json was given
  • {{<prefix>.temp_match_labels_json}} — how to say each of those times
  • {{<prefix>.temp_match_residue}} — the words that were not used
It returns True when the caller named a usable day, time or nudge, and False when they did not. On any failure (a bad prefix, no answer in time) it writes the empty values and returns False. It never stops the Code Step.
  • calendar_book() books {{calendar.booking_time_raw}} on the call’s booking calendar and writes the {{calendar.booking_*}} results, the same as a calendar booking step.
  • calendar_cancel_booking() cancels the booking in {{calendar.booking_id}}.
Both return True on success and False on any failure, with a note on the call; they wait up to 5 seconds. Neither stops the Code Step. Availability is not checked again when booking, so on False offer another time.

Survey Helpers

Checks whether the respondent’s answers so far put them in a quota cell that is already full, so a survey can end the interview early. answers is a dictionary of question key to the recorded answer. It returns a dictionary: Only "full" should end the interview. Every other status, "error" included, should continue it: the check fails open. Once a respondent is held or found over quota, the answer stays the same for the rest of the call. Test calls are checked but never hold a place. It never stops the Code Step; an "error" adds a note on the call.

Reading the Transcript

Read what has been said so far through variables:
  • {{call.transcript.last_user}} — the caller’s latest turn, as a string
  • {{call.transcript.last_ai}} — the assistant’s latest line, as a string
  • {{call.transcript.items}} — the whole conversation as a list of turns, each a dictionary with role, content, step_name and more
Or filter the conversation with a function:
All four arguments are optional, and it returns a new list of the same turn dictionaries:
  • role — "user", "assistant" or "tool"; leave it out for every role
  • step — with flow, a step number; without flow, a step counted back from this one in the current flow (0 is this step, -1 the one before)
  • flow — a flow number
  • n — a positive number keeps the first n turns, a negative one the last n
A bad argument gives an empty list rather than an error.
See the call variables for the full shape.

Regex Helper

JSON Helpers

Parse a JSON string into Python data:
Serialize Python data into a JSON string:

Not Allowed

  • import or from ... import ...
  • Filesystem, network, shell, or subprocess access
  • Reflection and dynamic execution — eval, exec, compile, open, __import__
  • Dunder names or dunder attributes
  • Lambdas, nested functions, classes
  • Any unlisted function or method

Next Steps