Overview
Embed Voiceflow’s text-chat widget in your iOS app using a hosted HTTPS page
and the supplied SwiftUI WKWebView wrapper. This guide covers public support;
your app owns the Help screen and its 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 iOS 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 page
Deploy to your HTTPS host, for example https://support.example.com/chat.html.
If approved-domain restrictions are enabled, have the project owner allow that
origin. Your content security policy must allow the widget’s script, styles and
runtime connections.
Open the final URL. The chat should replace the loading status. Use this same URL in the iOS wrapper, then complete the app conversation test.
Add the iOS widget screen
Mount one WebView and keep it stable while the screen is open.
Add the wrapper to your app target
Download the example bundle and add
SupportChat.swift to your iOS target. Present its SupportScreen from Help:
Replace the example URL with your hosted URL. The wrapper allows HTTPS navigation on that host and port, and blocks new-window links and other origins. Resource requests still need the widget’s CDN/runtime hosts. Add an app-owned external-link flow if your help content links to other sites.
Keep the view stable
Keep the view’s identity stable while Help is open. The wrapper avoids reloads
in updateUIView, stops loading on removal and uses a nonpersistent website data
store. Retain that behavior in your app’s navigation. See WKWebView
for the underlying view contract.
Use UIKit
Present the same support screen from a UIKit app.
The download supplies a SwiftUI screen. Present SupportScreen through
UIHostingController(rootView:), with child-controller
containment and layout constraints. Alternatively, adapt the same WKWebView
configuration and navigation delegate to your view controller. Apple’s
UIViewRepresentable
reference explains the SwiftUI wrapper.
Handle identity and app lifecycle
Keep widget conversations separate and handle app interruptions.
The widget creates a guest identity. Conversation state lasts only while the page’s storage remains available.
A client-supplied userID 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.
Discarding website data does not delete Voiceflow transcripts. Use Recover interrupted conversations for ambiguous sends and explicit restarts.
Test an app conversation
Verify replies on a simulator and a physical iPhone.
Open Help
Install the test build and open a fresh widget conversation. Accept any configured notice. Check text input, keyboard and safe-area layout.
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 the app and return, then test network loss and process termination against the lifecycle behavior. 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.
The widget screen is blank
Check the hosted document, widget setup and WebView navigation policy.
Open the exact HTTPS URL in Safari, then inspect the app WebView with your developer tools. Check for unresolved placeholders, a missing container, blocked CDN/styles/runtime connections, invalid certificates, public-access rejection or an approved-domain mismatch. Check redirects against the wrapper’s host/port restriction. Keep certificate verification enabled.
The widget restarts when the app redraws
Find unintended WebView replacement before changing runtime settings.
Check SwiftUI identity and parent navigation. Do not call load from every
updateUIView or foreground notification. A newly created nonpersistent store
has no promise of restoring the previous conversation. Use the platform’s
navigation delegate to distinguish a page error from web-content termination.
The wrong answer or conversation appears
Separate release routing from stored conversation state.
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 iOS build independently.
- Publish the intended agent and widget configuration.
- Deploy the hosted widget page with the verified configuration.
- Distribute the iOS build through your normal TestFlight and app release process. Repeat the app conversation test on the distributed build. Record the agent, page and app versions; remote changes can affect already installed apps.
Update or roll back
Change the layer responsible for the problem and test a fresh conversation.
Keep the last working page configuration and app build in your release system. Rolling back these services does not roll back native code or reset existing conversations. Recheck the selected Environment after a rollback and test both a fresh conversation and your intended return path. Include the observed widget bundle version in a regression report.
Remove the integration
Retire the app entry and its supporting services.
Remove the entry or ship an app update. Retire the hosted page when older
supported builds no longer need it, and remove app-owned
sessions and credentials according to your backend policy. Removing the view
or calling widget destroy() does not delete retained transcripts.
Custom interface guides
Planned iOS guides for your own chat or voice UI.
iOS walkthroughs for custom chat and voice interfaces are coming soon. These are separate from this widget guide.