> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# iOS SDK

> Embed a PolyAI messaging agent natively in your iOS app with a headless Swift library.

The iOS SDK is a native Swift library that embeds PolyAI's messaging agent directly inside your iOS app. It's **headless by design** — you own the UI, PolyAI provides the AI layer underneath. Your app connects to the same agent logic used across voice, webchat, and other channels.

> **Info**
>
> The iOS SDK wraps the [Messaging API](/api-reference/runtime-data/messaging-api/overview). All WebSocket events, streaming, and handoff behavior documented in the API reference apply.

#### [Source on GitHub](https://github.com/polyai/ios-sdk)

polyai/ios-sdk — Swift package, CocoaPods, and example apps.

## How it works

The SDK handles authentication, session management, WebSocket connections, and reconnection logic. Your app sends and receives messages through the SDK and renders them however you choose.

#### Install the SDK

Add the SDK to your project via **Swift Package Manager** or **CocoaPods**.

#### Configure authentication

Add your API key (from Agent Studio) and register your app's **bundle identifier** in Agent Studio. The backend rejects connections from unregistered bundle identifiers.

#### Start a session

Initialize the SDK and start a messaging session. The SDK handles access token exchange and WebSocket connection automatically.

#### Build your UI

Listen for incoming messages and events from the SDK, and send user messages through it. Render the conversation in your own UI components.

## Installation

The SDK is distributed as a native Swift package. Choose either method:

#### Swift Package Manager

In Xcode, go to **File > Add Package Dependencies** and enter the repository URL:

```
https://github.com/polyai/ios-sdk
```

Select the latest version and add the package to your target.

#### CocoaPods

Add the pod to your `Podfile`:

```ruby
pod 'PolyMessaging'
```

Then run:

```bash
pod install
```

## Authentication setup

The iOS SDK authenticates using a connector token and your app's bundle identifier.

#### Generate a connector token

In Agent Studio, go to **Messaging > API Configuration** and generate a new Messaging API key.

#### Register your bundle identifier

When generating the token, set the **host identifier** to your app's bundle identifier (e.g. `com.yourcompany.app`). This must match the `CFBundleIdentifier` in your app's `Info.plist`. The backend rejects connections from apps with a mismatched bundle identifier.

> **Warning**
>
> Never embed the connector token directly in your app binary. Use a backend service to mint short-lived access tokens and pass them to the SDK. See [security best practices](/api-reference/runtime-data/messaging-api/best-practices#security).

## Key features

### Session persistence

Sessions persist across app launches. If the user leaves and returns, the SDK reconnects to the existing session and replays the conversation history automatically. Network changes (Wi-Fi to cellular, brief drops) are handled with automatic reconnection and retry.

### Streaming responses

Enable streaming when creating a session to show agent responses as they're generated, word by word. The SDK surfaces streaming chunks as they arrive — your UI can render them incrementally.

### Handoff to live agents

The full [handoff flow](/api-reference/runtime-data/messaging-api/handoff-to-live-agent) is supported. When the PolyAI agent triggers a handoff, the SDK delivers the same handoff events (`HANDOFF_ACCEPTED`, `HANDOFF_QUEUE_STATUS`, `LIVE_AGENT_JOINED`, etc.) so your app can show queue status and live agent messages.

### Response suggestions

Agent messages can include `response_suggestions` — pre-written reply options. Render these as tappable buttons in your UI. When the user taps one, send its text as a message through the SDK.

### Attachments

Agent messages may include rich content like links and images via the `attachments` field. Render these inline in your chat UI.

## Platform values

When the SDK creates a session, it sets `platform` to `ios` automatically. This is visible in Agent Studio analytics and can be used in your agent logic to tailor behavior for mobile users.

| Platform value | Source                       |
| -------------- | ---------------------------- |
| `ios`          | iOS SDK (native)             |
| `android`      | Android SDK (native)         |
| `ios-web`      | Webchat widget on iOS Safari |
| `web`          | Webchat widget on desktop    |

## Limitations

> **Note**
>
> These limitations apply to the initial release. Check the [release notes](/release-notes/releases/overview) for updates.

| Limitation                | Details                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Text only**             | Voice input is not supported in V1. WebRTC voice support is planned for a future release and will require declaring microphone permissions (`NSMicrophoneUsageDescription`) in your `Info.plist`.                                                                                                                  |
| **No push notifications** | While the app is active, the SDK delivers messages in real time. When the app is backgrounded, the SDK cannot receive messages. You can listen for incoming messages and trigger your own local notifications while the app is in the foreground, but true remote push notifications (APNs) are not yet supported. |
| **iOS only**              | The SDK is native Swift. There is no React Native or Flutter wrapper. Cross-platform frameworks would require a separate SDK.                                                                                                                                                                                      |

## Multichannel

The iOS SDK connects to the same agent project as your voice and webchat channels. Agent behavior, knowledge, and flows are shared — only channel-specific settings (greetings, formatting) differ. See [multichannel agents](/agent-studio/messaging/multichannel-agents) for how to tailor behavior per channel.

In your agent's start function, detect the mobile channel using `conv.channel_type`:

```python
def start(conv):
    if conv.channel_type == "ios":
        conv.state.greet_message = "Hi! How can I help you today?"
    elif conv.channel_type.startswith("webchat"):
        conv.state.greet_message = "Hi there! 👋 How can I help?"
```

## Related pages

#### [Messaging API reference](/api-reference/runtime-data/messaging-api/overview)

Full WebSocket protocol, events, streaming, and handoff

#### [Sessions and authentication](/api-reference/runtime-data/messaging-api/sessions-and-authentication)

Access tokens, session creation, and platform values

#### [Multichannel agents](/agent-studio/messaging/multichannel-agents)

Build agents that work across voice, webchat, and mobile

#### [Best practices](/api-reference/runtime-data/messaging-api/best-practices)

Connection management, UX, and security recommendations