What are Custom Variables?
Custom variables are structured data records that you define for your team. Where a contact record carries a fixed set of fields — name, phone, email, company, timezone, address — a custom variable carries whatever structure your business needs: a property listing, a policy, a booking, a survey question. You decide the shape by creating a custom variable type, then create as many records of that type as you need.
Every field of a custom variable is available to your call scripts through the
custom namespace. If you create a type called Property Listing with an address field, your script can speak or reference {{custom.property_listing.address}} (string, e.g. 12 Wattle St, Brisbane QLD 4000). In any script field that supports variables, type / to open the variable picker — your installed custom variable types appear under the custom branch with each field’s data type shown.
When a custom variable is linked to a contact, calls with that contact read the linked record’s values; how linking works — and what the agent reads when nothing is linked — is covered on Linking Custom Variables to Contacts.
You’ll find the workspace in the sidebar under Voice Agent Settings > Custom Variables.
The Custom Variables workspace
The page follows the same table layout as Calls, Contacts and Scripts: a tab row, search, filter and sort controls, CSV download, refresh, and action buttons on the right.- Type tabs — the first tab is All, showing every custom variable regardless of type. Each installed custom variable type gets its own tab, named after the type. Switching to a type tab scopes the table to that type and unlocks its data columns.
- Table columns — every view shows a selection checkbox, Name, Type and Created, plus a row menu with a Delete action. On a type tab you can add a column for any field of that type.
- Filters and sorting — on the All tab you can filter by Name, Type, Created and Modified. On a type tab, the Type filter is replaced by filters for each visible data column, matched to the field’s type: text, number, date range, Yes/No, or a dropdown of the field’s allowed values.
- Search — searches custom variables by name.
- Action buttons — Custom Variable Types opens the type manager (see Custom Variable Types & Schema Validation); Add Custom Variable opens the new-record form.
Columns and saved views
On a type tab, the Columns button opens a picker listing every field of the type. Until a view has been saved, every field of the type shows as a column. Nested fields appear as an expandable tree, and All / None buttons toggle everything at once. Choose the columns you want, then select Save View — the selection is saved on the type itself, so the same columns load for your whole team whenever that tab is opened. The button reads View Saved when the current selection matches what’s stored. The saved selection also drives which fields the detail pane’s Data section shows for records of that type. The All tab has no schema to draw on, so its column picker only offers the raw field names found in your data, and views can’t be saved there.Adding a custom variable
Select Add Custom Variable to open the New Custom Variable form in the detail pane on the right.
The Data card adapts to your Type selection:
- With a type selected — one input per field of the type, rendered to match the field’s data type: text (with email and URL variants), a dropdown when the field has a fixed list of allowed values, a number input, a Yes/No checkbox, or a JSON box for list and object fields. Required fields are marked with
*and an alert reminds you that “Fields marked with * are required”. - Without a type — free-form name/value rows. Use Add Field to add more rows; values that parse as JSON are stored as numbers, lists or objects, anything else as text.
- Advanced — a switch in the card header swaps either form for a raw JSON editor, keeping whatever you’d already entered. Invalid JSON is flagged and can’t be saved.
The detail pane
Click any row to open Custom Variable Details — the record’s name, its type badge, and two tabs.Data tab
The Data section lists the record’s fields with their current values — the same field selection as the type’s saved view, or every field of the type when no view has been saved. Values are edited inline:- Click a text or number value to edit it in place; click away (or press Ctrl+Enter) to save, or press Escape to cancel.
- Yes/No values toggle with a single click.
- Fields with a fixed list of allowed values open a dropdown.
- List and object fields open a JSON editor and validate as you type.
{{custom.property_listing.address}} (string, e.g. 12 Wattle St, Brisbane QLD 4000) — ready to paste into a call script. A tooltip previews the token before you copy it.
The Metadata section below shows the record’s Name, Type, its Parent (when one is set — see Hierarchy below), Created and Modified timestamps, and the record’s unique ID.
Raw JSON tab
The Raw JSON tab shows the record’s full data payload. Use the copy button to copy it, or the pencil to edit the whole payload as JSON and Save — handy for pasting in a complete record or fixing structure that the field editors can’t reach.Adding fields to a type
Types aren’t frozen once created. Open Custom Variable Types, edit a type, and use Add Field in its schema editor to add a new field — or Import JSON to generate fields from a sample record. Because the table columns, detail pane and add form are all driven by the type’s field list, a newly added field is available immediately on every custom variable of that type: it appears in the column picker as a table column and filter, in the detail pane, and in the new-record form. If you’ve already saved a view for the type, tick the new field in the Columns picker and save the view again to show it — the table and detail pane follow the saved selection. Existing records keep their data untouched — the new field simply reads as empty (shown as —) until a value is entered. The new field is also immediately addressable from scripts, e.g. addinginspection_date to a Property Listing type makes {{custom.property_listing.inspection_date}} (string, e.g. 2026-07-21) available; on records where it hasn’t been filled in yet the field has no value, and if your script speaks the token without a fallback the caller hears the raw {{...}} text rather than silence — guard it with a fallback before speaking it.
The full type builder — field types, formats, allowed values, validation modes and the installable type catalogue — is documented on Custom Variable Types & Schema Validation.
Hierarchy
A custom variable can have a parent — another custom variable it belongs to, such as line items under an order, or rooms under a property. When a record has a parent, the detail pane’s Metadata section shows a Parent row with the parent’s name. There is currently no control in the workspace for setting a parent; parents are assigned when records are created or updated through the Voxworks API, which accepts a parent reference on both create and upsert.Deleting custom variables
- One record — open the row menu (⋯) and choose Delete. The Delete Custom Variable dialog warns that the action cannot be undone.
- Several records — tick their checkboxes, then use the Delete selected bin icon that appears in the toolbar. The Delete Selected Custom Variables dialog confirms the count before deleting.
Next Steps
- Custom Variable Types & Schema Validation — build type schemas, choose field types and formats, and set Off/Warn/Strict validation.
- Linking Custom Variables to Contacts — attach records to contacts so calls read the right data.
- Importing Custom Variables from CSV — create typed records in bulk from a spreadsheet.
- Variables — the full variable reference, including the
customnamespace and the/picker.