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.

1

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.

2

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.

1

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.

2

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.

1

Open Help

Install the test build and open a fresh widget conversation. Accept any configured notice. Check text input, keyboard and safe-area layout.

2

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.

3

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.

4

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.

5

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.

  1. Publish the intended agent and widget configuration.
  2. Deploy the hosted widget page with the verified configuration.
  3. 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.

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