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
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.
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.
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
- Start a fresh app conversation with
topic=delivery&lang=en. Check the initial message says Help topic: delivery, then ask a delivery question. - Start another fresh conversation with
topic=returns. Confirm it says Help topic: returns. Test a missing/unsupported topic and confirm general. - Send a follow-up and verify the captured variables remain usable after
last_eventchanges. Reopen an existing conversation separately; do not expect the URL alone to overwrite its initial context. - 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.