Overview
Embed Voiceflow’s text-chat widget in your Android app using a hosted HTTPS
page and the supplied WebView Activity. This guide covers public support;
your app owns navigation and the screen’s lifetime.
Building your own interface? Custom chat and voice walkthroughs are coming soon. Start with Chat agents or Voice agents for the APIs.
Before you begin
Prepare the agent, hosted widget page and Android project.
Start with an existing agent; see Build if you need to create one first.
The hosted page uses public widget identifiers. Keep private project API keys and app sign-in credentials on your backend.
Host the widget page
Load the widget from an HTTPS origin you control.
The downloadable page uses public widget access with verify.projectID. Voice
controls are disabled; microphone access and file pickers need additional app work.
Configure the hosted page
Save chat.html in your web application. Set
YOUR_PROJECT_ID to the supplied project ID and YOUR_ENVIRONMENT_ALIAS to the
Environment alias.
The page passes your alias as environmentID and selects the published release
with versionVariant: 'published'. Keep its embedded rendering and session-only
storage; see widget Environment routing
for options and compatibility.
Deploy and check the URL
Deploy to your HTTPS host, for example https://support.example.com/chat.html.
Have the project owner allow that origin if domain restrictions are enabled.
Your content security policy must allow the widget’s CDN, styles and runtime
connections. Keep TLS checks enabled.
Open the final URL. The chat should replace the loading status. Use this same
URL in Android, then complete the app conversation test.
Use a hosted HTTPS page; local file:// content has different origin/storage
behavior. See Android’s WebView guidance.
Add the Android widget screen
Configure the manifest and mount one WebView in the Help destination.
Register the Activity
Download the example bundle and add
SupportActivity.kt to your app module. Replace package com.example.app with
your app package and set the hosted HTTPS URL. In AndroidManifest.xml, add
internet permission before application and the Activity inside it, retaining
your existing attributes:
Keep cleartext traffic disabled. Open the Activity from your Help click handler:
Keep the view configuration
Retain the example’s settings for the trusted page:
- JavaScript and DOM storage enabled.
- File/content access disabled and mixed content blocked.
- HTTPS navigation restricted to the hosted origin, with no native bridge or SSL bypass.
Keep its padding for system bars, cutouts and keyboard insets, pause/resume forwarding, and teardown on removal or renderer failure. Check your app’s edge-to-edge layout. Android documents WebView setup and native bridge risks.
Use Jetpack Compose
Launch the Activity from Compose or adapt it to an inline WebView.
You can launch the same Activity from Help. For an inline view, use AndroidView and create the WebView in its factory rather than on each recomposition. Retain the same settings, lifecycle handling and cleanup, then test that adaptation in your app.
Handle identity and app lifecycle
Keep widget conversations separate and handle app interruptions.
The widget creates a guest identity. sessionStorage retains state within the
surviving page session; Android WebView can also share web data across the app.
A client-supplied userID, display name or launch value is not authenticated
identity. Revoke app/backend sessions separately on logout, and authorize
protected operations on every request. See Separate app conversations
for the widget’s account boundary. Keep account tokens out of the public page.
Android’s Activity lifecycle and WebView process handling explain recreation behavior. Use Recover interrupted conversations for safe recovery. WebView cleanup does not delete Voiceflow transcripts.
Test an app conversation
Verify replies on an emulator and a physical device.
Open Help
Install the test build and open a fresh widget conversation. Accept any configured notice. Check keyboard layout, Back navigation and readable replies.
Check a question and follow-up
Send the known support question, then a related follow-up. Confirm that the intended agent answers visibly in the widget and the conversation continues correctly.
Interrupt and resume
Background and resume the app, then test network loss. Check rotation, Activity recreation and renderer/process loss separately against the lifecycle behavior. Verify the expected retained or fresh conversation and check an uncertain action’s result before offering a retry.
Check account changes
Close and reopen Help to check retention. Sign out and switch accounts: the previous conversation must be absent. If you added protected operations, confirm stale backend requests are denied.
Check the released build
Repeat the question and follow-up in a fresh conversation on the distributed build after publishing. Confirm that it uses the intended agent release and hosted page.
Record Android version, app build and WebView provider/version with failures.
The widget does not load
Check JavaScript, DOM storage and the hosted origin first.
Confirm javaScriptEnabled and domStorageEnabled, resolved project/Environment
values and a non-empty embedded container. Inspect requests for public-access
rejection, approved-domain errors or blocked scripts/styles/runtime connections.
The origin must be your hosted HTTPS page, not file:// or the Android package.
The widget screen is blank or restarts
Distinguish navigation errors from Activity or renderer recreation.
Check HTTPS certificates, redirects and the allowed host/port. Do not bypass an SSL error. Check whether your app created a new Activity/WebView, reloaded on resume, or recreated the Activity after rotation. After renderer failure, remove and destroy that instance; Android says it cannot be reused. The sample offers an explicit reload that may start a fresh conversation.
The wrong conversation or release appears
Check identity cleanup and routing independently.
Verify the project ID, Environment alias and Published release with a fresh conversation. Check the hosted-page version. Review reused identities and retained state; clearing the visible messages alone is insufficient. Check an uncertain action’s result before retrying.
Release and maintain the app
Publish the agent, hosted widget page and Android build independently.
- Publish the intended agent and widget configuration.
- Deploy the hosted widget page with the verified configuration.
- Distribute the Android build through your normal testing and Google Play release process. Repeat the app conversation test in that build. Record the agent, page and app versions independently; remote changes can affect already installed apps.
Update or roll back
Retain a working page and app build, then verify both fresh and returning use.
Roll back the layer responsible for the regression. An agent or page rollback does not replace native code or reset existing conversations. Retest a fresh conversation and the intended return path. Record the observed widget bundle and WebView versions; both can change independently of your app.
Remove the integration
Retire the app entry and its supporting services.
Remove the entry or distribute an app update. Keep the hosted page available until older supported builds no longer need it. Revoke app-owned sessions and credentials according to your backend policy. Destroying the view does not delete retained transcripts or constitute server-side logout.
Custom interface guides
Planned Android guides for your own chat or voice UI.
Android walkthroughs for custom chat and voice interfaces are coming soon. These are separate from this widget guide.