Getting started

The Ada iOS SDK is a framework that you can use to embed your Ada AI agent into your native iOS application.

It also supports actions and settings that you can use to customize the behavior of your AI Agent. For example, you might want to set the language, or pass metadata. The iOS SDK reference covers these options and more.

Compatibility

Ada supports iOS 15.4 or later. Ada tests new iOS versions when they become generally available and continues testing the two versions behind the current version.

Install the iOS SDK

You can install the Ada iOS SDK using Swift Package Manager, CocoaPods, Carthage, or manually. Swift Package Manager is the recommended installation path.

Install using Swift Package Manager (Recommended)

Via Xcode:

1. Open File > Add Package Dependencies…
2. Enter the repository URL: https://github.com/ada-cx-public/messaging-ios.git
3. Choose the release version you want to ship.
4. Add the AdaMessaging product to your app target.

Via Package.swift:

dependencies: [
    .package(url: "https://github.com/ada-cx-public/messaging-ios.git", from: "<version>"),
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: ["AdaMessaging"]
    ),
]

Replace <version> with the latest release tag from the releases page.

Install using CocoaPods

1. Add AdaMessaging to your Podfile.

2. Install the pod using: pod install.

# Podfile
platform :ios, '15.4'
target 'MyApp' do
  use_frameworks!
  # Pods for MyApp
  pod "AdaMessaging", :git => "https://github.com/ada-cx-public/messaging-ios", :tag => "<version>"
end

Replace <version> with the latest release tag from the releases page. The :tag pin is exact, so update it when you upgrade.

Install using Carthage

Add the following to your Cartfile:

github "ada-cx-public/messaging-ios" ~> <version>

Replace <version> with the latest release tag from the releases page.

Then run:

carthage update --use-xcframeworks

Add AdaMessaging.xcframework to your app target in Xcode.

Install iOS SDK manually

1. Download AdaMessaging.xcframework.zip from the latest release here.
2. Right-click on the project file in Xcode, then click Add Files to MyProjectName. Ensure that the groups option is selected.
3. Set your Deployment Target to 15.4 or later.
4. In your target’s General settings, add AdaMessaging.xcframework under Frameworks, Libraries, and Embedded Content with Embed & Sign selected.

Import the framework

Once you’ve installed the Ada iOS SDK, you’re ready to use it in your app!

1. Import AdaMessaging into your controller.
2. Create an instance of the AdaWebHost, as in the example below, replacing my-bot with the actual name of your bot.

import AdaMessaging
// ...
lazy var adaWebHost = AdaWebHost(handle: "my-bot")

You can also pass optional configuration at initialization:

let adaWebHost = AdaWebHost(
    handle: "my-bot",
    language: "en",
    metafields: [
        "plan": "pro",
        "signedIn": true,
    ]
)

Choose the web runtime

AdaWebHost can mount one of two web runtimes inside its WebView:

• .legacy (the default) — the same runtime the existing Chat SDK loads. Apps migrating from AdaEmbedFramework keep this default and see no behavior change.
• .messaging — the Messaging runtime. Identity tokens, headless mode, and sendMessage require it.

To mount the Messaging runtime, set both environment and webSdk:

let adaWebHost = AdaWebHost(
    handle: "my-bot",
    environment: .production,
    webSdk: .messaging
)

Launch Ada

Finally, launch Ada using one of the four opening methods:

• launchModalWebSupport — Presents the chat as a modal overlay.
• launchNavWebSupport — Pushes the chat onto the navigation stack.
• launchInjectingWebSupport — Injects the chat view into an existing view.
• launchHeadlessWebSupport — Runs the chat offscreen, with no Ada UI. See Run headless and build your own UI.

adaWebHost.launchModalWebSupport(from: self)

Authenticate end users with an identity token

If your app has signed-in users, you can authenticate them to Ada with a short-lived identity token. This requires the Messaging runtime.

1. Your backend mints a token for the signed-in user’s end user ID with the Ada Platform API (POST /v2/auth/tokens/), authenticated with your Ada API key. Tokens are single use and expire after 15 minutes.
2. Your backend returns the token to your app over your own authenticated channel.
3. Your app passes the token to AdaWebHost at initialization.

let adaWebHost = AdaWebHost(
    handle: "my-bot",
    environment: .production,
    webSdk: .messaging,
    identityToken: token
)

The SDK exchanges the token once, when the session starts. Because tokens are single use, mint a fresh token for each new AdaWebHost you create.

The SDK keeps the token out of every URL and never persists it. If the exchange fails, the runtime emits the ada:identity_token:error or ada:identity_token:expired event to your eventCallbacks. See identityToken in the reference.

Run headless and build your own UI

Headless mode runs the conversation in a hidden WebView while your app renders its own UI with native components. Use it for an unread badge, a custom chat screen, a search bar, or a command palette.

Create the host with headless: true and enableProgrammaticControl: true, then launch it without presenting UI. For example, to drive a native unread badge:

var badgeCount = 0
let adaWebHost = AdaWebHost(
    handle: "my-bot",
    eventCallbacks: [
        "ada:message:received": { _ in
            badgeCount += 1
            // Show the unread badge (red dot) in your native UI.
        },
        "ada:message:sent": { _ in
            // Clear the badge, update your native transcript.
        }
    ],
    environment: .production,
    webSdk: .messaging,
    enableProgrammaticControl: true,
    headless: true
)
// Run offscreen. The SDK creates and retains a hidden, zero-sized container.
adaWebHost.launchHeadlessWebSupport()
// Drive the conversation from your native UI.
adaWebHost.sendMessage("Where is my order?")

The ada:message:received event fires for each message from the AI Agent or a human agent. The ada:message:sent event fires for each message the end user sends. Both events require enableProgrammaticControl: true.

Runtime commands

You can interact with the Ada chat instance at runtime using the following methods.

Set metadata

Use MetaFields.Builder to pass public or sensitive metadata to Ada:

let publicFields = MetaFields.Builder()
    .setField(key: "plan", value: "pro")
    .setField(key: "signedIn", value: true)
let sensitiveFields = MetaFields.Builder()
    .setField(key: "authToken", value: "secure-session-token")
adaWebHost.setMetaFields(builder: publicFields)
adaWebHost.setSensitiveMetaFields(builder: sensitiveFields)

Set language

adaWebHost.setLanguage(language: "fr")

Set device token

adaWebHost.setDeviceToken(deviceToken: "apns-device-token")

Send a message

adaWebHost.sendMessage("Where is my order?")

Reset the chat

adaWebHost.reset(
    language: "en",
    metaFields: publicFields,
    sensitiveMetaFields: sensitiveFields,
    resetChatHistory: true
)

Delete chat history

adaWebHost.deleteHistory()

Info.plist permissions

If your AI Agent flow allows users to upload images, videos, or use the camera, add the corresponding usage descriptions to your app’s Info.plist:

Upgrade from the existing iOS SDK

If you are migrating from the existing AdaEmbedFramework, the new Messaging SDK is designed as a drop-in replacement. AdaWebHost remains the main public class — most apps only need a dependency swap and an import rename.

Migration steps

1. Replace the old dependency with AdaMessaging.
2. Rename the framework import from AdaEmbedFramework to AdaMessaging.
3. Keep your existing AdaWebHost usage as-is.

Side-by-side mapping

Before / after: imports

// Before
import AdaEmbedFramework
// After
import AdaMessaging

Before / after: CocoaPods

# Before
pod "AdaEmbedFramework"
# After
pod "AdaMessaging", :git => "https://github.com/ada-cx-public/messaging-ios", :tag => "<version>"

Use MetaFields.Builder for new code

Dictionary overloads for setMetaFields, setSensitiveMetaFields, and some reset shapes still exist for backward compatibility but are deprecated. For all new code, prefer MetaFields.Builder:

let publicFields = MetaFields.Builder()
    .setField(key: "plan", value: "pro")
    .setField(key: "signedIn", value: true)
let sensitiveFields = MetaFields.Builder()
    .setField(key: "authToken", value: "secure-session-token")
adaWebHost.setMetaFields(builder: publicFields)
adaWebHost.setSensitiveMetaFields(builder: sensitiveFields)
adaWebHost.reset(
    language: "en",
    metaFields: publicFields,
    sensitiveMetaFields: sensitiveFields,
    resetChatHistory: true
)

Release checklist

Before shipping your integration or migration to production:

• Verify your real production AI Agent handle launches successfully
• Test the exact presentation mode you ship (modal, navigation push, inline, or headless)
• Confirm any event logging still receives SDK events
• Test push token registration if your app depends on it
• Test reset() and deleteHistory() if your app exposes those actions
• If you use identity tokens, verify the happy path and confirm your code handles ada:identity_token:error and ada:identity_token:expired
• If you use headless mode, verify your native UI updates from eventCallbacks and that sendMessage delivers