> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # iOS SDK reference > **Warning** > > Ada has deprecated Chat. Messaging fully replaces Chat on December 15, 2026. Read [Introducing Messaging](https://docs.ada.cx/2026-09-30-introducing-messaging) to learn how to migrate. This page covers the legacy Chat iOS SDK. Follow the [Messaging iOS upgrade guide](/messaging/ios/getting-started#upgrade-from-the-existing-ios-sdk) to migrate. Use the iOS SDK [settings](#settings) and [actions](#actions) to customize the behavior of your bot. ## Settings With the iOS SDK, you can customize the behavior of your chatbot with `AdaWebHost` input parameters. ### appScheme `appScheme: String = ""` Use this setting to pass the scheme name of the host app. This allows for more robust handling of universal links. ### cluster `cluster: String = ""` Specifies the Kubernetes cluster your AI Agent runs on. **Set this only if your Agent is hosted on a non-default cluster** (e.g., `us2`, `maple`, `eu`). If the Agent is on the default `us` cluster, leave this unset. > **Info** > > Do not change this value unless instructed by your Ada team. ### greeting `greeting: String = ""` Use this setting to customize the greeting messages that new chatters see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use, which you can find in the URL of the corresponding Answer in the dashboard. **Example** ![](/_fern-img/a7fea47cff8a7e0931f1f7b88be30130fc81ec7c6be9d662433b766b8e037e0b.webp) > **Note** > > This setting is only applicable if you're using a **scripted bot**. ### handle `handle: String` The handle for your bot. This is a required field. ### language `language: String = ""` Takes in a language code to programmatically set the bot language. You must first turn languages on in your Ada dashboard. * If you're using a **generative AI Agent**, go to **Customization** > **Languages**. See [Support multiple languages in the same AI Agent](/docs/setup/languages/about-multilingual-support) for more information. > **Note** > > Language codes use the [ISO 639-1 language format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). ### metaFields `metafields: [String: String]? = [:]` Use metaFields to pass information about a user to Ada. This can be useful for tracking information about your customers, as well as personalizing their experience. For example, you may wish to track the `phone_number` and `name` for conversation attribution. (See [Variables](https://docs.ada.cx/docs/generative/set-up-your-ai-agent-s-knowledge-and-behavior/manage-your-ai-agent-s-behavior/create-workflows-with-processes/#variables) for more information.) To change these values after bot setup, use the [setMetaFields](/ios-sdk-reference#setmetafields) action. **`Swift`** ```swift Swift lazy var adaFramework = AdaWebHost(handle: "ada-example", metafields: ["tier": "pro"]) ``` ### sensitiveMetafields `sensitiveMetafields: [String: String]? = [:]` Use this parameter to pass sensitive meta information about a chatter. This works like [metafields](/ios-sdk-reference#metafields) but provides an added layer of security. To change these values after bot setup, use the [setSensitiveMetafields](/ios-sdk-reference#setsensitivemetafields) action. ### openWebLinksInSafari `openWebLinksInSafari: Bool = false` External web links open by default in-app, via the SFSafariViewController. To open external links in the Safari browser, pass `openWebLinksInSafari: true` to `AdaWebHost`. ### zdChatterAuthCallback `zdChatterAuthCallback: ((((_ token: String) -> Void)) -> Void)? = nil` Use the `zdChatterAuthCallback` to request a JWT token from your API, then pass it to Ada. This creates shared trust between Ada and Zendesk, and in turn allows for verifiable chatter identity. **`Swift`** ```swift Swift lazy var adaFramework = AdaWebHost(handle: "nic", zendeskAuthCallback: { callback in // Request JWT from your API // Then... callback("your.JWT") }) ``` > **Note** > > `zdChatterAuthCallback` is available only for [Zendesk Chat](https://docs.ada.cx/docs/generative/integrate-ada-with-other-tools/use-ada-with-zendesk/configure-zendesk-chat). It is not available for [Zendesk Messaging](https://docs.ada.cx/docs/generative/integrate-ada-with-other-tools/use-ada-with-zendesk/configure-and-use-zendesk-messaging/). ## Session Persistence The iOS SDK stores session state — including the chatter token and any active Zendesk Messaging handoff context — in the WebView's `localStorage`. > **Warning** > > **On iOS, WebView `localStorage` persistence across app restarts is not guaranteed.** Session state may or may not survive depending on OS memory management, and should not be relied upon for maintaining live agent handoff state. > > If your app requires guaranteed session continuity across app restarts, you will need to implement your own native storage management. The current SDK does not persist session state using platform-native storage such as `Keychain` or `UserDefaults`. > > To implement this yourself, see the Apple developer documentation on [Keychain Services](https://developer.apple.com/documentation/security/keychain_services) or [UserDefaults](https://developer.apple.com/documentation/foundation/userdefaults). ## Actions Use the actions below in conjunction with settings to customize the behavior of your bot in an iOS app. ### deleteHistory `deleteHistory()` Deletes the record used to fetch conversation logs for a user from local storage. When a user opens a new chat window, a new user record will be created. ### launchInjectingWebSupport `launchInjectingWebSupport(into view: UIView)` Launches Ada chat into a specified subview. **`Swift`** ```swift Swift adaFramework.launchInjectingWebSupport(into: injectingView) ``` ### launchModalWebSupport `launchModalWebSupport(from viewController: UIViewController)` Launches Ada chat in a modal view over top of your current view. **`Swift`** ```swift Swift adaFramework.launchModalWebSupport(from: self) ``` ### launchNavWebSupport `launchNavWebSupport(from navController: UINavigationController)` Pushes a view containing Ada chat to the top of your navigational stack. **`Swift`** ```swift Swift adaFramework.launchNavWebSupport(from: navigationController) ``` ### reset `reset()` Use this action to create a new user and refresh the chat window. ### setLanguage `setLanguage(language: string)` Changes the language in chat programmatically. Use this action, rather than the language setting, to change the chat language without clearing the chat history. Language codes must use a lowercase, two-letter code, in [ISO 639-1 language format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). ``` adaFramework.setLanguage(language: "fr") ``` Before using `setLanguage`: * You must turn languages on in your Ada dashboard. * If you're using a **generative AI Agent**, go to **Customization** > **Languages**. See [Support multiple languages in the same AI Agent](/docs/setup/languages/about-multilingual-support) for more information. * The chat window must be opened at least once. ### setMetaFields `setMetaFields(_ fields: [String: Any])` Used to set metadata for a user after instantiation. This is useful if you need to update user data after Ada Chat has already launched. See also [metaFields](#metafields). **`Swift`** ```swift Swift adaFramework.setMetaFields([ "firstName": "Jane", "lastName": "Doe", "tier": "pro" ]) ``` ### setSensitiveMetaFields `setSensitiveMetaFields(_ fields: [String: Any])` Used to set sensitive metadata for a chatter after instantiation. This works like setMetaFields and is useful for storing more private and sensitive information. See also [sensitiveMetaFields](#sensitivemetafields). **`Swift`** ```swift Swift adaFramework.setSensitiveMetaFields([ "token": "your_jwt_token" ]) ``` ### triggerAnswer `triggerAnswer()` Triggers an answer in chat. Include the Answer ID, which you can find in the URL of the corresponding Answer in the dashboard. **Example** ![](/_fern-img/a7fea47cff8a7e0931f1f7b88be30130fc81ec7c6be9d662433b766b8e037e0b.webp) ``` adaFramework.triggerAnswer("627d28a9bd9ca9e5337b9763") ``` > **Note** > > The chat window must be opened at least once before this method can be used. > **Note** > > This action is only applicable if you're using a **scripted bot**.