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 or 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 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, have the web developer insert this code immediately before window.voiceflow.chat.load:

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

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 owns the exact launch-payload contract.

3

Capture the values when the agent starts

In the agent, create help_topic and app_language variables. Put a Code step on the initial path, before the agent uses these values. The Code step cannot create the variables for you.

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.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.