> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the Voiceflow widget to iOS

> Embed Voiceflow’s text-chat widget in your iOS app using a hosted HTTPS page and the supplied WebView example. Test identity, recovery and release.

## 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.

**Note:** 

**Building your own interface?** Custom chat and voice walkthroughs are [coming soon](#custom-interface). Start with [Chat agents](/docs/api-reference/agent-runtime/chat) or [Voice agents](/docs/api-reference/agent-runtime/voice) for the APIs.

<a id="prepare"></a>

## Before you begin

Prepare the agent, hosted widget page and iOS project.

Start with an existing agent; see [Build](/docs/documentation/build/overview) if you need to create one first.

| Requirement | What you need |
| --- | --- |
| Agent | Public widget access and an intended [Published release](/docs/documentation/deploy/environments/publishing). |
| Widget configuration | The [project ID](/docs/cookbook/find-your-project) and Environment alias from the project owner. |
| Website | An HTTPS host you control for the widget page. |
| iOS project | An Xcode project. The downloadable Swift example targets iOS 15 or later. |
| Test and conversation policy | A known question and expected answer, any customer notice, and an agreed [retention/account-change policy](/docs/guides/channels/mobile/separate-app-conversations). |

The hosted page uses public widget identifiers. Keep private project API keys and app sign-in credentials on your backend.

<a id="host-page"></a>

## 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](/docs/examples/mobile/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](/docs/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads)
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](#test-conversation).

<a id="install-view"></a>

## 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](/docs/examples/mobile/mobile-examples.zip) and add
`SupportChat.swift` to your iOS target. Present its `SupportScreen` from Help:

```swift
SupportScreen(url: URL(string: "https://support.example.com/chat.html")!)
```

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](https://developer.apple.com/documentation/webkit/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](https://developer.apple.com/documentation/swiftui/uiviewrepresentable)
reference explains the SwiftUI wrapper.

<a id="identity-lifecycle"></a>

## 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.

| App event | Required behavior |
| --- | --- |
| Background and resume | Keep a surviving view. Avoid reloading or sending another `launch` automatically. |
| Logout or account change | Remove the old view and discard its data store before showing Help for another account. |
| App or web-content termination | Handle lost state explicitly; a new view or store can start a fresh conversation. |
| Explicit restart | **Reload support** creates a new view instance. |

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](/docs/guides/channels/mobile/separate-app-conversations)
for the widget's account boundary.

Discarding [website data](https://developer.apple.com/documentation/webkit/wkwebsitedatastore)
does not delete Voiceflow transcripts. Use [Recover interrupted conversations](/docs/guides/channels/mobile/recover-interrupted-conversations)
for ambiguous sends and explicit restarts.

<a id="test-conversation"></a>

## 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](#identity-lifecycle). 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.

<a id="release"></a>

## Release and maintain the app

Publish the agent, hosted widget page and iOS build independently.

1. Publish the intended [agent and widget configuration](/docs/documentation/deploy/environments/publishing).
2. Deploy the hosted widget page with the verified configuration.
3. Distribute the iOS build through your normal
[TestFlight](https://developer.apple.com/testflight/) and app release process.
Repeat the [app conversation test](#test-conversation) 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.

<a id="custom-interface"></a>

## 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.

| Planned guide | API reference |
| --- | --- |
| Add custom chat | [Chat agents](/docs/api-reference/agent-runtime/chat) |
| Add custom voice | [Voice agents](/docs/api-reference/agent-runtime/voice) |
