> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/chat/ios/getting-started/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Getting started

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

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

It also supports actions and settings that you can use to customize the behavior of your bot. For example, you might want to set the bot language, or customize the greeting. The [iOS SDK reference](/ios-sdk-reference) covers these options and more.

> **Note**
>
> You'll need an active Ada bot handle and access to the Ada Dashboard to use the SDK. To gain access, please reach out to an Ada Account Manager.

> **Note**
>
> This guide covers the new Ada iOS SDK. If you are migrating from the existing SDK (`AdaEmbedFramework`), see [Upgrade from the Existing iOS SDK](#upgrade-from-the-existing-ios-sdk) below.

## Compatibility

| Requirement | Minimum Version                          |
| ----------- | ---------------------------------------- |
| iOS         | 16.0                                     |
| Swift       | 5.9                                      |
| Xcode       | Current toolchain with Swift 5.9 support |

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`:**

**`Swift`**

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

### Install using CocoaPods

1. Add `AdaMessaging` to your Podfile.

2. Install the pod using: `pod install`.

**`Swift`**

```swift Swift
# Podfile
platform :ios, '16.0'

target 'MyApp' do
  use_frameworks!

  # Pods for MyApp
  pod "AdaMessaging", :git => "https://github.com/ada-cx-public/messaging-ios", :tag => "1.0.2"

end
```

### Install using Carthage

Add the following to your Cartfile:

**`Swift`**

```swift Swift
github "ada-cx-public/messaging-ios" ~> 1.0.2
```

Then run:

```bash
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](https://github.com/ada-cx-public/messaging-ios/releases).
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.

**`Swift`**

```swift Swift
import AdaMessaging

// ...

lazy var adaWebHost = AdaWebHost(handle: "my-bot")
```

> **Note**
>
> The lazy property prevents AdaWebHost from initializing until the property is used. Use of this property may help to prevent unwanted end users from being created in the background.

You can also pass optional configuration at initialization:

**`Swift`**

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

> **Note**
>
> Most apps only need `handle`. Leave `cluster` and `domain` unset unless Ada tells you your AI agent is hosted on a non-default regional cluster or custom domain.

## Launch Ada

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

* [launchInjectingWebSupport](/ios-sdk-reference#launchinjectingwebsupport)
* [launchModalWebSupport](/ios-sdk-reference#launchmodalwebsupport)
* [launchNavWebSupport](/ios-sdk-reference#launchnavwebsupport)

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

**`Swift`**

```swift Swift
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)
```

> **Note**
>
> Dictionary overloads for `setMetaFields` and `setSensitiveMetaFields` still exist for backward compatibility but are deprecated. Use `MetaFields.Builder` for all new code.

### Set language

**`Swift`**

```swift Swift
adaWebHost.setLanguage(language: "fr")
```

### Set device token

**`Swift`**

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

### Trigger a specific answer

**`Swift`**

```swift Swift
adaWebHost.triggerAnswer(answerId: "response-id")
```

### Reset the chat

**`Swift`**

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

### Delete chat history

**`Swift`**

```swift Swift
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`:

| Key                              | When Required            |
| -------------------------------- | ------------------------ |
| `NSCameraUsageDescription`       | Camera capture uploads   |
| `NSPhotoLibraryUsageDescription` | Photo library uploads    |
| `NSMicrophoneUsageDescription`   | Video capture with audio |

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

| Existing                        | Messaging SDK              |
| ------------------------------- | -------------------------- |
| `AdaEmbedFramework`             | `AdaMessaging`             |
| `AdaEmbedFramework.xcframework` | `AdaMessaging.xcframework` |
| `pod "AdaEmbedFramework"`       | `pod "AdaMessaging"`       |
| `import AdaEmbedFramework`      | `import AdaMessaging`      |

### Before / after: imports

**`Swift`**

```swift Swift
// Before
import AdaEmbedFramework

// After
import AdaMessaging
```

### Before / after: CocoaPods

**`Swift`**

```swift Swift
# Before
pod "AdaEmbedFramework"

# After
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`:

**`Swift`**

```swift Swift
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 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