> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

> Variables store and pass values throughout a call. Use them whenever a script, tool, condition, response map, or code step needs to read or write data captured during the conversation.

## Variable Notation

The user-facing notation is:

```text theme={null}
{{namespace.path}}
```

Examples:

* `{{contact.first_name}}`
* `{{contact.email}}`
* `{{calendar.booking_time_raw}}`
* `{{insurance.claim.response_status}}`
* `{{custom.claim.contact.name}}`

The first part is the **namespace**. Everything after it is the **field path**.

***

## Reading Variables

Use a variable reference inside text where you want the value inserted.

```text theme={null}
Thanks {{contact.first_name}}, I have your email as {{contact.email}}.
```

If the values exist, the caller may hear:

```text theme={null}
Thanks Jane, I have your email as jane@example.com.
```

In exact tool inputs, a missing variable usually becomes an empty value. In normal script text, unresolved variables can remain visible internally and produce a system note for debugging.

***

## Writing Variables

Tools that write values usually have a field such as `Destination`, `Response Map`, or `Output Map`. Use the same notation as the destination:

```text theme={null}
{{contact.email}}
{{custom.claim_number}}
{{custom.appointment.datetime}}
```

When a tool writes to a destination, the runtime stores the value for later steps and end-of-call data.

***

## Custom Variables

Use the `custom` namespace for script-specific values that do not belong to a configured system namespace.

* `{{custom.claim_number}}`
* `{{custom.customer_sentiment}}`
* `{{custom.appointment.datetime}}`
* `{{custom.claim.contact.name}}`

Custom variables can be nested. Use clear path names and keep them consistent across the flow.

***

## Nested Reads

Some variables hold a whole object, such as a webhook response or API result. Read a nested field by adding a path after the variable.

```text theme={null}
{{insurance.claim.response_full}}.claim_number
{{insurance.policy.contact_full}}.full_name
{{webhook.response}}.data.customer.id
```

This means: read the stored object first, then extract the field after the closing braces.

***

## Response Maps

Response maps use variables on the left and source paths on the right.

```text theme={null}
{{custom.customer_id}} -> data.customer.id
{{contact.email}}      -> data.customer.email
{{custom.status}}      -> status
```

The left side is where the value is stored. The right side is where to find the value in the tool response.

***

## Code Step Examples

Read a value:

```python theme={null}
def run():
    email = {{contact.email}}
    return bool(email)
```

Write a value:

```python theme={null}
def run():
    email = {{contact.email}}
    {{contact.email_verified}} = bool(email and "@" in email)
    return {{contact.email_verified}}
```

Write a custom value:

```python theme={null}
def run():
    {{custom.customer_status}} = "verified"
    return True
```

See the [Code Step](/tools/code-step/overview) docs for the full `run()` contract.

***

## Available Globals

These are the configured global namespaces and fields available for `{{namespace.path}}` references.

### `contact`

Contact identity and contact-record fields.

| Field            | Reference                    | Type   | Source Table | Source Field  |
| ---------------- | ---------------------------- | ------ | ------------ | ------------- |
| Full Name        | `{{contact.full_name}}`      | string | contacts     | full\_name    |
| First Name       | `{{contact.first_name}}`     | string | contacts     | first\_name   |
| Last Name        | `{{contact.last_name}}`      | string | contacts     | last\_name    |
| Email            | `{{contact.email}}`          | string | contacts     | email         |
| Phone            | `{{contact.phone}}`          | string | contacts     | phone\_number |
| Company          | `{{contact.company}}`        | string | contacts     | company       |
| Location         | `{{contact.location}}`       | string | contacts     | location      |
| Address          | `{{contact.address}}`        | string | contacts     | address       |
| Timezone         | `{{contact.timezone}}`       | string | contacts     | timezone      |
| Date of Birth    | `{{contact.date_of_birth}}`  | string | -            | -             |
| Email (Verified) | `{{contact.email_verified}}` | string | -            | -             |

### `call`

Call-level values.

| Field             | Reference                  | Type   | Source Table | Source Field |
| ----------------- | -------------------------- | ------ | ------------ | ------------ |
| Room ID           | `{{call.room_id}}`         | string | -            | -            |
| Transcript        | `{{call.transcript}}`      | object | -            | -            |
| Transcript - Full | `{{call.transcript.full}}` | string | -            | -            |

### `calendar`

Calendar availability and booking values.

| Field                       | Reference                                | Type   | Source Table | Source Field |
| --------------------------- | ---------------------------------------- | ------ | ------------ | ------------ |
| Event ID                    | `{{calendar.event_id}}`                  | string | -            | -            |
| Booking ID                  | `{{calendar.booking_id}}`                | string | -            | -            |
| Booking Link                | `{{calendar.booking_link}}`              | string | -            | -            |
| Availability - Raw          | `{{calendar.availability_raw}}`          | string | -            | -            |
| Availability - Spoken       | `{{calendar.availability_spoken}}`       | string | -            | -            |
| Availability Error - Spoken | `{{calendar.availability_error_spoken}}` | string | -            | -            |
| Booking Time - Raw          | `{{calendar.booking_time_raw}}`          | string | -            | -            |
| Booking Time - Spoken       | `{{calendar.booking_time_spoken}}`       | string | -            | -            |
| Booking Time - Written      | `{{calendar.booking_time_written}}`      | string | -            | -            |
| Booking Error - Spoken      | `{{calendar.booking_error_spoken}}`      | string | -            | -            |

### `timezone`

Timezone check and resolution values.

| Field                | Reference                           | Type    | Source Table | Source Field |
| -------------------- | ----------------------------------- | ------- | ------------ | ------------ |
| Check Contact Result | `{{timezone.check_contact_result}}` | boolean | -            | -            |
| Resolved State       | `{{timezone.resolved_state}}`       | string  | -            | -            |
| Resolved IANA        | `{{timezone.resolved_iana}}`        | string  | -            | -            |
| Check Flag           | `{{timezone.check_flag}}`           | boolean | -            | -            |
| Flag Result          | `{{timezone.flag_result}}`          | boolean | -            | -            |

### `auth`

Values captured from or representing the user for authentication workflows.

| Field                     | Reference                            | Type   | Source Table | Source Field |
| ------------------------- | ------------------------------------ | ------ | ------------ | ------------ |
| User                      | `{{auth.user}}`                      | object | -            | -            |
| User Full Name            | `{{auth.user.full_name}}`            | string | -            | -            |
| User First Name           | `{{auth.user.first_name}}`           | string | -            | -            |
| User Last Name            | `{{auth.user.last_name}}`            | string | -            | -            |
| User Date of Birth        | `{{auth.user.date_of_birth}}`        | string | -            | -            |
| User Vehicle Registration | `{{auth.user.vehicle_registration}}` | string | -            | -            |

### `auth_check`

Authentication check outcomes.

| Field          | Reference                       | Type    | Source Table | Source Field |
| -------------- | ------------------------------- | ------- | ------------ | ------------ |
| Verified       | `{{auth_check.verified}}`       | boolean | -            | -            |
| Status         | `{{auth_check.status}}`         | string  | -            | -            |
| Matched Count  | `{{auth_check.matched_count}}`  | integer | -            | -            |
| Required Count | `{{auth_check.required_count}}` | integer | -            | -            |
| Matched Checks | `{{auth_check.matched_checks}}` | json    | -            | -            |
| Failed Checks  | `{{auth_check.failed_checks}}`  | json    | -            | -            |
| Exact Match    | `{{auth_check.exact_match}}`    | boolean | -            | -            |
| Semantic Match | `{{auth_check.semantic_match}}` | boolean | -            | -            |
| Method         | `{{auth_check.method}}`         | string  | -            | -            |
| Notes          | `{{auth_check.notes}}`          | string  | -            | -            |
| Verified Data  | `{{auth_check.verified_data}}`  | string  | -            | -            |

### `sms`

SMS tool result values.

| Field               | Reference                   | Type   | Source Table | Source Field |
| ------------------- | --------------------------- | ------ | ------------ | ------------ |
| Send Error - Spoken | `{{sms.send_error_spoken}}` | string | -            | -            |

### `webhook`

Webhook response values.

| Field    | Reference              | Type   | Source Table | Source Field |
| -------- | ---------------------- | ------ | ------------ | ------------ |
| Response | `{{webhook.response}}` | string | -            | -            |

### `insurance`

Insurance, policy, claim, FNOL, incident, vehicle, and complaint values.

#### Policy

| Field                 | Reference                           | Type   | Source Table | Source Field |
| --------------------- | ----------------------------------- | ------ | ------------ | ------------ |
| Policy                | `{{insurance.policy}}`              | object | -            | -            |
| Policy ID             | `{{insurance.policy.id}}`           | string | -            | -            |
| Policy Contact - Full | `{{insurance.policy.contact_full}}` | string | -            | -            |

#### Claim

| Field                   | Reference                             | Type   | Source Table | Source Field |
| ----------------------- | ------------------------------------- | ------ | ------------ | ------------ |
| Claim                   | `{{insurance.claim}}`                 | object | -            | -            |
| Claim ID                | `{{insurance.claim.id}}`              | string | -            | -            |
| Claim Response - Full   | `{{insurance.claim.response_full}}`   | string | -            | -            |
| Claim Response - Status | `{{insurance.claim.response_status}}` | string | -            | -            |

#### FNOL

| Field                  | Reference                            | Type   | Source Table | Source Field |
| ---------------------- | ------------------------------------ | ------ | ------------ | ------------ |
| FNOL                   | `{{insurance.fnol}}`                 | object | -            | -            |
| FNOL ID                | `{{insurance.fnol.id}}`              | string | -            | -            |
| FNOL Draft ID          | `{{insurance.fnol.draft_id}}`        | string | -            | -            |
| FNOL Draft ID - Spoken | `{{insurance.fnol.draft_id_spoken}}` | string | -            | -            |

#### Incident

| Field                | Reference                            | Type   | Source Table | Source Field |
| -------------------- | ------------------------------------ | ------ | ------------ | ------------ |
| Incident             | `{{insurance.incident}}`             | object | -            | -            |
| Incident Date & Time | `{{insurance.incident.date_time}}`   | string | -            | -            |
| Incident Location    | `{{insurance.incident.location}}`    | string | -            | -            |
| Incident Description | `{{insurance.incident.description}}` | string | -            | -            |

#### Vehicle

| Field                | Reference                            | Type   | Source Table | Source Field |
| -------------------- | ------------------------------------ | ------ | ------------ | ------------ |
| Vehicle              | `{{insurance.vehicle}}`              | object | -            | -            |
| Vehicle Registration | `{{insurance.vehicle.registration}}` | string | -            | -            |
| Vehicle Condition    | `{{insurance.vehicle.condition}}`    | string | -            | -            |

#### Complaint

| Field             | Reference                         | Type   | Source Table | Source Field |
| ----------------- | --------------------------------- | ------ | ------------ | ------------ |
| Complaint         | `{{insurance.complaint}}`         | object | -            | -            |
| Complaint Summary | `{{insurance.complaint.summary}}` | string | -            | -            |

***

## Where Variables Work

Variables are substituted in:

* Voice step scripts
* Condition next scripts
* Tool input mappings and response maps
* Function and code step logic
* SMS message content

***

## Variable Lifecycle

```text theme={null}
Call Starts
   → Configured namespace values (e.g. contact) populated from records
   → Live values written by tools are still empty

During Conversation
   → Tools, functions, and code steps write values
   → All variables remain available to every step and sub-flow

Call Ends
   → Variables are stored as end-of-call data
```

Live values have no value until a tool, function, or code step writes to them. Always run the step that populates a value before referencing it.

***

## Common Issues

* **A variable does not resolve** — check spelling, namespace, and path.
* **A write is skipped** — the destination may not be a valid variable reference.
* **A configured namespace rejects a path** — the field may not exist in that namespace's schema.
* **A nested field does not resolve** — confirm the stored value is actually an object and the path matches the response shape.
* **`{{custom.some.path}}` works but `{{contact.some.path}}` does not** — this is expected. Custom paths are flexible, while configured system namespaces are schema-controlled.

***

## Best Practices

1. **Use `{{...}}` in all new work**
2. **Use descriptive custom paths** — `{{custom.claim_number}}` rather than `{{custom.value}}`
3. **Keep response maps small** — write only values the flow needs later
4. **Store full API responses only when needed** — when later steps read multiple fields from them
5. **Document shared custom variables** — note any used across multiple steps so the flow stays maintainable

***

## Next Steps

* [Voice Steps](/flows/steps-voice) — Use variables in your scripts
* [Tool Steps](/flows/steps-tool) — Pass variables to external services
* [Code Step](/tools/code-step/overview) — Read and write variables in Python
* [Tools Overview](/tools/overview) — See all available tools