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

# Pass app context

> Give a Voiceflow mobile chat a help topic and language at launch, then verify that the agent uses those hints without treating them as trusted identity.

A customer opening Help from a delivery screen should not have to name that
screen again. Pass a small, non-sensitive launch payload from your hosted chat
page and capture it when the agent starts. This guide assumes the
[iOS](/docs/guides/channels/mobile/ios) or [Android](/docs/guides/channels/mobile/android)
WebView installation already works.

The app/web developer owns the hosted page. The agent builder owns the variables
and initial behavior. These values are hints a client can alter; use
[Separate app conversations](/docs/guides/channels/mobile/separate-app-conversations)
for account authorization.

## Send and capture the hints

### 1. Choose a small context contract

Agree on allowed values, for example `help_topic` of `delivery` or `returns` and
`app_language` of `en` or `fr`. Give unknown/missing values a safe default.
Do not send access tokens, account credentials or protected order details.

For a simple app-to-page handoff, the developer can select a topic/language in
the hosted URL query. Query values can appear in logs and copied links; use
only these non-sensitive values. The native wrapper must still restrict the
HTTPS origin. No JavaScript-to-native bridge is required.

### 2. Add the payload before the single load call

In the installed [chat.html example](/docs/examples/mobile/chat.html), have the
web developer insert this code immediately before `window.voiceflow.chat.load`:

```javascript
const query = new URLSearchParams(window.location.search);
const helpTopic = ['delivery', 'returns'].includes(query.get('topic'))
  ? query.get('topic') : 'general';
const appLanguage = ['en', 'fr'].includes(query.get('lang'))
  ? query.get('lang') : 'en';
```

Add this property inside that existing load configuration, keeping its project,
Environment, rendering and text-only options:

```javascript
launch: {
  event: {
    type: 'launch',
    payload: { help_topic: helpTopic, app_language: appLanguage }
  }
},
```

For example, the app can open
`https://support.example.com/chat.html?topic=delivery&lang=en`.
Do not add a second widget load or inject query values as HTML/JavaScript.
The [widget API](/docs/documentation/deploy/widget/web-chat-api#passing-custom-variables)
owns the exact launch-payload contract.

### 3. Capture the values when the agent starts

In the agent, create `help_topic` and `app_language`
[variables](/docs/documentation/build/data/variables). Put a
[Code step](/docs/documentation/build/steps/code) on the initial path, before the
agent uses these values. The Code step cannot create the variables for you.

```javascript
const hints = last_event && last_event.payload ? last_event.payload : {};
help_topic = ['delivery', 'returns'].includes(hints.help_topic)
  ? hints.help_topic : 'general';
app_language = ['en', 'fr'].includes(hints.app_language)
  ? hints.app_language : 'en';
```

Use `help_topic` in your initial routing or agent instructions and
`app_language` as the preferred response language. For a deterministic check,
add an initial Message step that says `Help topic: {help_topic}` in your test
release. Publish the change to the Environment used by the page.

Capture at launch: `last_event` changes on later interactions. Opening an
already restored conversation does not guarantee a new launch; this example
sets starting hints, not live updates as the customer changes screens.

## Test the context

1. Start a fresh app conversation with `topic=delivery&lang=en`. Check the initial message says **Help topic: delivery**, then ask a delivery question.
2. Start another fresh conversation with `topic=returns`. Confirm it says **Help topic: returns**. Test a missing/unsupported topic and confirm **general**.
3. Send a follow-up and verify the captured variables remain usable after `last_event` changes. Reopen an existing conversation separately; do not expect the URL alone to overwrite its initial context.
4. Remove the temporary diagnostic message, publish the intended release and repeat the customer question in the app. Check that no sensitive values entered the URL or transcript.

### The agent uses the default topic

Check the page payload, initial Code step and selected release.

Confirm the URL parameter is allowlisted, the payload is inside the single
load call, and the Code step runs before the first dependent message. Check
that both project variables exist. Test a fresh conversation against the
Published release containing the new path; a restored session can skip launch.

### The topic changes or disappears later

Use captured variables instead of rereading a later event.

Read `help_topic` and `app_language` after the initial capture. A later text,
choice or event replaces `last_event`. For live screen updates, design a
separate event workflow using the canonical widget/runtime contracts and test
it in the app; this launch recipe does not provide it automatically.
