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

# Context Variables

> Tell Typewise which customer data your app sends, and use it to fill action and lookup inputs

Context Variables tell Typewise which pieces of customer data from your app it can see and use. Examples: `user_email`, `order_id`, `account_id`.

Without declaring them here, the AI Agent doesn't see those values, and your actions can't enforce who a request is for.

> [!NOTE]
>
> Typewise forwards only what you declare on this page. If your app sends a variable that isn't on the list, Typewise filters it out: the value never reaches the ticket, the AI Agent, webhooks, or the API.

For the trust model, see [Security and verification](https://docs.typewise.app/documentation/actions/security.md).

***

## Declare a variable

**1. Open Context Variables**

Go to **Settings > Workspace > *your workspace* > Context variables**. Each workspace declares its own set.

**2. Add a variable**

Click **Add item** and fill in the fields below.

**3. Save**

Save the page. The variable becomes available when you customize inputs on actions and integration lookups.

| Field | Description |
| :- | :- |
| **Name** | Key used in the payload (for example, `user_email`, `vip_customer`). |
| **Description** | What this variable represents. The AI Agent reads this when deciding how to use the value. |
| **Type** | Text, Number, or Yes/No. Action and lookup inputs must match this type. |

![Context Variables settings with built-in and custom declared variables](https://mintcdn.com/typewise/9HSB0yVnnqLQYt5T/images/documentation/settings/context-variables/declared-variables.webp?fit=max\&auto=format\&n=9HSB0yVnnqLQYt5T\&q=85\&s=e416b6ecd6aeca98ea0e04f911a2ff2c)

## Built-in variables

Every workspace ships with variables Typewise pre-declares and populates automatically. You can't edit or delete them, and they coexist with your own declared variables. The workspace's **Context variables** page shows the current set alongside your custom ones, and you can map any of them to an action or lookup input.

| Variable | Type | What Typewise puts in it |
| :- | :- | :- |
| `user_email` | Text | The customer's email address. |
| `user_phone` | Text | The customer's phone number. Set on every inbound WhatsApp message; no other channel populates it. |
| `originUrl` | Text | The page the chat widget was loaded on. Set by the SDK on every new conversation. |
| `subject` | Text | The subject line of a webform submission. Set by the [Form API](https://docs.typewise.app/guides/channels/form-api.md) when the payload has one. |
| `typewiseTicketId` | Text | The Typewise ticket ID of this conversation. Set by the platform on every request. |

### Pass the Typewise ticket ID to your systems

Map `typewiseTicketId` to an input when the system you call should record which conversation a request came from, so an order or case it creates can be traced back to the ticket it started in.

Typewise supplies the value per request rather than storing it on the ticket, and its own value always wins over one your app sends under the same name. Because it is never stored, it does not appear in the ticket sidebar or the variables timeline.

> [!NOTE]
>
> `typewiseTicketId` always counts as verified, so an input mapped to it passes a **Trusted only** check without asking the customer to confirm anything. Typewise sets the value, so your backend doesn't sign it on chat — the install snippet lists only the variables you need to sign.

## Where declared variables appear

After Typewise drops undeclared variables, every declared variable surfaces in four places:

| Surface | What appears |
| :- | :- |
| **Ticket sidebar** | Admins see the variable name and value on each ticket. |
| **AI Agent context** | The AI Agent reads the variable name, value, and description when generating replies and choosing actions. |
| **Webhooks** | Outbound webhook payloads include declared variables. Undeclared values are stripped before send. |
| **API** | The ticket-detail endpoint returns the same declared set. |

The sidebar shows exactly what the AI Agent sees. If a variable does not appear in the sidebar, it has not been declared, and the AI Agent does not see it either.

***

## Use variables in actions and lookups

**Actions** are tasks the AI Agent performs in your connected systems (refund an order, update a CRM contact). **Lookups** read data from those systems. Both can take inputs that you fill from declared context variables.

Open any integration action or integration lookup and turn on **Customize inputs**.

### Pick a source for each input

For every input the action or lookup accepts, the picker offers:

| Source | Behavior |
| :- | :- |
| **Auto** (default) | The AI Agent fills the input from the conversation. |
| **Static** | A fixed value you set. The AI Agent can't override it. |
| **A context variable** | The value of a declared variable, taken from this conversation. The picker lists every declared variable whose type matches the input. |

When you map an input to a variable, an optional **Trusted only** checkbox appears next to the picker.

### The Trusted-only check

**Trusted only** is a per-input check that runs at the moment Typewise is about to call the tool. With it on, the AI Agent runs the tool only when the mapped variable's value arrived through a verified path on the current conversation. When the value can't be trusted, the tool doesn't run: for `user_email` the AI Agent asks the customer to prove the address (a one-time code on chat, or a reply on email). For any other variable, the conversation hands off to a Human Agent.

Use **Trusted only** on every input that decides *who* the action runs for: `user_email`, `user_phone`, `tenant_id`, `account_id`. Leaving it off lets the AI Agent run the tool with any value the variable has, including one that arrived unsigned over the chat widget.

| Trusted only | The tool runs when... |
| :- | :- |
| **Off** (default) | The variable has any value, verified or not. |
| **On** | The variable's value is verified. Otherwise the tool doesn't run. |

![Customize inputs on an action: source picker plus the Trusted only check](https://mintcdn.com/typewise/9HSB0yVnnqLQYt5T/images/documentation/settings/context-variables/actions-secure-input.webp?fit=max\&auto=format\&n=9HSB0yVnnqLQYt5T\&q=85\&s=a499936e27ec61ee25117cecab2da5ec)

> [!NOTE]
>
> Manual actions and manual lookups don't expose Customize inputs. Their inputs are filled by the AI Agent from the conversation.

### How a value becomes verified

A value is *verified* on a given conversation only when it arrived through a trusted path. The path depends on the channel.

#### Chat widget

On chat, a value your app sends counts as verified only when your backend signs it. Unsigned values from the browser (locale, theme) stay untrusted, so any input mapped to them fails the **Trusted only** check. Sign every variable you use as a Trusted-only input on a chat action or lookup. For the signing secret, the code, and where the token goes, see [Chat identity verification](https://docs.typewise.app/guides/channels/chat-widget/identity-verification.md).

`user_email` has a second path: the customer verifies it in the chat itself with a one-time code. The code prompt appears when a **Trusted only** check fails or when the AI Agent runs the [Verify email address](https://docs.typewise.app/documentation/actions/system-actions.md#verify-email-address) system action, and it replaces the message box until the customer verifies.

#### Email

For email, only the sender's address can be verified, and only after they reply to a Typewise message. Email headers like `From:` can be spoofed, so Typewise doesn't trust them on their own. A reply proves the sender controls the inbox.

1. A sender becomes verified the first time they reply to a Typewise message on this conversation.
2. If a **Trusted only** input mapped to `user_email` runs before the sender is verified, the AI Agent asks the customer to reply.
3. On the next inbound message, Typewise marks the sender verified and the action proceeds.

#### WhatsApp

On WhatsApp, the customer's phone number arrives on the built-in `user_phone` variable. WhatsApp carries the number as part of the message itself rather than in a header the sender can set, so Typewise counts it as verified: an input mapped to `user_phone` passes the **Trusted only** check without asking the customer to confirm anything.

Map `user_phone` to the input that decides *who* a tool runs for when you enable that tool on WhatsApp, the same way you map `user_email` on email.

Every other variable still hands the conversation to a Human Agent when it is mapped **Trusted only**, because WhatsApp has no flow for proving any other value. The exception is `typewiseTicketId`, which Typewise sets itself and always counts as verified.

> [!NOTE]
>
> Typewise writes `user_phone` on each inbound WhatsApp message, so it has no value until the customer sends one. On a channel that carries no phone number, a **Trusted only** input mapped to `user_phone` hands the conversation to a Human Agent rather than skipping the tool.

### When a Trusted-only input is not satisfied

| Situation | Behavior |
| :- | :- |
| `user_email` mapped Trusted only, email sender not yet verified | AI Agent asks the customer to reply, then verifies on receipt. |
| `user_email` mapped Trusted only, chat session without verified `user_email` | AI Agent asks the customer to confirm via a one-time code ([what the customer sees](https://docs.typewise.app/documentation/actions/system-actions.md#verify-email-address)). |
| `user_phone` mapped Trusted only, WhatsApp conversation after an inbound message | The tool runs: the number WhatsApp delivered is already verified. |
| `user_phone` mapped Trusted only, WhatsApp conversation with no inbound message yet | Conversation hands off to a Human Agent: the variable has no value until the customer writes. |
| Any other Trusted-only input on WhatsApp, except one mapped to `typewiseTicketId` | Conversation hands off to a Human Agent. |
| Any other variable mapped Trusted only, value missing or unverified | Conversation hands off to a Human Agent. |

## Checklist

1. Declare every variable your app sends, including identity and authorization variables. Typewise drops anything you don't declare.
2. On every integration action and integration lookup that depends on identity, enable **Customize inputs**, map the identity inputs to context variables, and turn on **Trusted only**.
3. On chat, sign identity variables so they arrive trusted (see [Chat identity verification](https://docs.typewise.app/guides/channels/chat-widget/identity-verification.md)). On email, the sender's address becomes verified after their first reply.
4. Declaring a variable doesn't enforce trust. The Trusted-only check on the input applies it at runtime.

## See also

* [Security and verification](https://docs.typewise.app/documentation/actions/security.md): the trust model behind input customization
* [Verify email address](https://docs.typewise.app/documentation/actions/system-actions.md#verify-email-address): trigger email verification from instructions, without a gated input
* [AI actions](https://docs.typewise.app/documentation/actions/ai-actions.md): configure actions
* [Lookups](https://docs.typewise.app/documentation/knowledge/integrations/lookups.md): configure integration lookups
* [Knowledge](https://docs.typewise.app/documentation/knowledge/overview.md): add knowledge sources


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.