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 will add support for new iOS versions as they become generally available, and will continue to support and test for 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:

1
dependencies: [
2
    .package(url: "https://github.com/ada-cx-public/messaging-ios.git", from: "1.0.2"),
3
],
4
targets: [
5
    .target(
6
        name: "YourTarget",
7
        dependencies: ["AdaMessaging"]
8
    ),
9
]

Install using CocoaPods

The AdaMessaging CocoaPod is public, however, use of the chat interface is gated. To gain access please reach out to an Ada Account Manager.

1. Add AdaMessaging to your Podfile.

2. Install the pod using: pod install.

1
# Podfile
2
platform :ios, '16.0'
3
4
target 'MyApp' do
5
  use_frameworks!
6
7
  # Pods for MyApp
8
  pod "AdaMessaging", :git => "https://github.com/ada-cx-public/messaging-ios", :tag => "1.0.2"
9
10
end

Install using Carthage

Add the following to your Cartfile:

1
github "ada-cx-public/messaging-ios" ~> 1.0.2

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. Ensure your Deployment Target is set to 16.0 or higher.
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.

1
import AdaMessaging
2
3
// ...
4
5
lazy var adaWebHost = AdaWebHost(handle: "my-bot")

You can also pass optional configuration at initialization:

1
let adaWebHost = AdaWebHost(
2
    handle: "my-bot",
3
    language: "en",
4
    metafields: [
5
        "plan": "pro",
6
        "signedIn": true,
7
    ]
8
)

Launch Ada

Finally, launch Ada using one of the three 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.

1
adaWebHost.launchModalWebSupport(from: self)

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:

1
let publicFields = MetaFields.Builder()
2
    .setField(key: "plan", value: "pro")
3
    .setField(key: "signedIn", value: true)
4
5
let sensitiveFields = MetaFields.Builder()
6
    .setField(key: "authToken", value: "secure-session-token")
7
8
adaWebHost.setMetaFields(builder: publicFields)
9
adaWebHost.setSensitiveMetaFields(builder: sensitiveFields)

Set language

1
adaWebHost.setLanguage(language: "fr")

Set device token

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

Trigger a specific answer

1
adaWebHost.triggerAnswer(answerId: "response-id")

Reset the chat

1
adaWebHost.reset(
2
    language: "en",
3
    metaFields: publicFields,
4
    sensitiveMetaFields: sensitiveFields,
5
    resetChatHistory: true
6
)

Delete chat history

1
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 Legacy iOS SDK

If you are migrating from the legacy 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

1
// Before
2
import AdaEmbedFramework
3
4
// After
5
import AdaMessaging

Before / after: CocoaPods

1
# Before
2
pod "AdaEmbedFramework"
3
4
# After
5
pod "AdaMessaging", :git => "https://github.com/ada-cx-public/messaging-ios", :tag => "1.0.2"

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:

1
let publicFields = MetaFields.Builder()
2
    .setField(key: "plan", value: "pro")
3
    .setField(key: "signedIn", value: true)
4
5
let sensitiveFields = MetaFields.Builder()
6
    .setField(key: "authToken", value: "secure-session-token")
7
8
adaWebHost.setMetaFields(builder: publicFields)
9
adaWebHost.setSensitiveMetaFields(builder: sensitiveFields)
10
adaWebHost.reset(
11
    language: "en",
12
    metaFields: publicFields,
13
    sensitiveMetaFields: sensitiveFields,
14
    resetChatHistory: true
15
)

Release checklist

Before shipping your integration or migration to production:

• Verify your real production bot handle launches successfully
• Test the exact presentation mode you ship (modal, navigation push, or inline)
• 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