> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Integration

> Integrate CometChat iOS UI Kit with project setup, package installation, initialization, login, rendering, permissions, and optional calling.

<Accordion title="AI Integration Quick Reference">
  | Field        | Value                                                                                 |
  | ------------ | ------------------------------------------------------------------------------------- |
  | Package      | `CometChatUIKitSwift`                                                                 |
  | Version      | `5.1.9`                                                                               |
  | Requirements | Xcode 16+, iOS 13.0+, Swift 5.0+                                                      |
  | Init         | `CometChatUIKit.init(uiKitSettings:)` — must complete before `login()`                |
  | Login        | `CometChatUIKit.login(uid:)` — must complete before rendering components              |
  | Order        | `init()` → `login()` → render. Breaking this order = blank screen                     |
  | Auth Key     | Dev/testing only. Use Auth Token in production                                        |
  | Calling      | Optional. Install `CometChatCallsSDK 4.2.2` to enable                                 |
  | Dependencies | `CometChatSDK 4.1.0` (installed automatically)                                        |
  | AI Skills    | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) |
</Accordion>

This guide walks you through adding CometChat to an iOS app. By the end you'll have a working chat UI.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/21UBnagXOw-XG0Sv/images/b09905f9-instant-messaging-3479b572fd280c5fcb87e7b858d762bc.png?fit=max&auto=format&n=21UBnagXOw-XG0Sv&q=85&s=19738f9f976526ebb62189f31aaa8050" width="1440" height="833" data-path="images/b09905f9-instant-messaging-3479b572fd280c5fcb87e7b858d762bc.png" />
</Frame>

***

## Integrate with AI Coding Agents

Skip the manual steps — use [CometChat Skills](https://github.com/cometchat/cometchat-skills) to integrate via your AI coding agent. Your agent has a short conversation with you to understand your project and chat requirements, then writes production-grade integration code tailored to the files you already have.

```bash theme={null}
npx @cometchat/skills add
```

Use `--ide <name>` to target a specific IDE (e.g. `--ide cursor`), or `--ide all` for all supported IDEs.

Then in your IDE:

```
/cometchat add chat to my app
```

The skill detects your iOS project structure, navigation pattern (UIKit or SwiftUI), and existing auth system. It onboards you to CometChat directly in the terminal — signup, login, and app creation all via the CLI. It reads your view controllers, navigation, and components before proposing a placement, shows the plan, and waits for your approval before writing code. Credentials are saved via `Secrets.swift` or `.xcconfig`.

After the first integration, re-run `/cometchat` to access the iteration menu: theme presets, 40+ features, component customization, production auth, user management, and diagnostics.

Works with Claude Code, Cursor, Codex, VS Code Copilot, Windsurf, Cline, Kiro, and [30+ more agents](https://github.com/cometchat/cometchat-skills).

***

## Prerequisites

You need three things from the [CometChat Dashboard](https://app.cometchat.com/):

| Credential | Where to find it                                           |
| ---------- | ---------------------------------------------------------- |
| App ID     | Dashboard → Your App → Credentials                         |
| Auth Key   | Dashboard → Your App → Credentials                         |
| Region     | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) |

You also need:

* Xcode 16 or later
* iOS device or simulator running iOS 13.0+
* Swift 5.0+
* macOS

<Warning>
  Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](/rest-api/chat-apis) and use [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-auth-token). Never ship Auth Keys in client code.
</Warning>

***

## Step 1 — Create an iOS Project

Open Xcode and create a new project:

1. Select **iOS App** in the template picker and click Next
2. Enter your project name and bundle identifier
3. Select **Storyboard** for Interface
4. Select **Swift** for Language

***

## Step 2 — Install the UI Kit

<Tabs>
  <Tab title="CocoaPods">
    1. Create a Podfile in your project root:

    ```bash theme={null}
    pod init
    ```

    2. Add CometChat to your Podfile:

    ```ruby title="Podfile" theme={null}
    platform :ios, '13.0'
    use_frameworks!

    target 'YourApp' do
      pod 'CometChatUIKitSwift', '5.1.9'
      
      # Optional: Voice/Video Calling
      pod 'CometChatCallsSDK', '4.2.2'
    end
    ```

    3. Install dependencies:

    ```bash theme={null}
    pod install --repo-update
    ```

    4. Close the `.xcodeproj` file and open the `.xcworkspace` file instead. CocoaPods creates a workspace that includes your project and the installed pods.

    <Tip>
      Always open the `.xcworkspace` file after installing pods — opening the `.xcodeproj` will cause build errors. Having issues? See [CocoaPods Troubleshooting](/ui-kit/ios/troubleshooting#cocoapods-issues).
    </Tip>
  </Tab>

  <Tab title="Swift Package Manager">
    1. Go to **File → Add Package Dependencies**

    2. Enter the repository URL:

    ```
    https://github.com/cometchat/cometchat-uikit-ios
    ```

    3. Select **Up to Exact Version** and enter:

    ```
    5.1.9
    ```

    4. Add the Chat SDK separately using:

    ```
    https://github.com/cometchat/chat-sdk-ios
    ```

    Exact Version: `4.1.0`
  </Tab>
</Tabs>

***

## Step 3 — Configure Permissions

Add these keys to your `Info.plist` for media messaging:

```xml title="Info.plist" lines theme={null}
<key>NSCameraUsageDescription</key>
<string>Allow access to the camera to capture photos and videos.</string>

<key>NSMicrophoneUsageDescription</key>
<string>Enable microphone access for voice and video communication.</string>

<key>NSPhotoLibraryAddUsageDescription</key>
<string>Allow saving photos and videos to your device's photo library.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>Grant access to select and upload photos from your library.</string>
```

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/ugckbRl5Q-H7t8X2/images/e736dfc8-app_permissions-6c9e93e30fb31f4e1427f6b72f94a58b.png?fit=max&auto=format&n=ugckbRl5Q-H7t8X2&q=85&s=0a27a939a4ab5413686dfee0dc7a0667" width="1639" height="150" data-path="images/e736dfc8-app_permissions-6c9e93e30fb31f4e1427f6b72f94a58b.png" />
</Frame>

Also disable **User Script Sandboxing** in Build Settings to ensure WebView can load scripts for collaborative tools:

1. Select your project in the Navigator
2. Select your app target
3. Go to **Build Settings** tab
4. Search for "User Script Sandboxing"
5. Set it to **No**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/fxK75AS6FzDL1Oqo/images/b5713f38-user_script_sandboxing-4b1ea0c72461fcf25c8bdc0b42497ff9.png?fit=max&auto=format&n=fxK75AS6FzDL1Oqo&q=85&s=e83e3aec38e80a4eba32cdb27235cec8" width="1842" height="302" data-path="images/b5713f38-user_script_sandboxing-4b1ea0c72461fcf25c8bdc0b42497ff9.png" />
</Frame>

***

## Step 4 — Initialize & Login

Add this to your `SceneDelegate.swift`. Init must complete before login, and login must complete before rendering any UI.

```swift title="SceneDelegate.swift" lines theme={null}
import UIKit
import CometChatUIKitSwift
import CometChatSDK

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }

        let uikitSettings = UIKitSettings()
            .set(appID: "APP_ID")        // Replace with your App ID
            .set(region: "REGION")       // Replace with your Region
            .set(authKey: "AUTH_KEY")    // Replace with your Auth Key (dev only)
            .subscribePresenceForAllUsers()
            .build()

        CometChatUIKit.init(uiKitSettings: uikitSettings) { result in
            switch result {
            case .success:
                debugPrint("CometChat initialized")
                
                let uid = "cometchat-uid-1"  // Test user
                
                CometChatUIKit.login(uid: uid) { loginResult in
                    switch loginResult {
                    case .success:
                        debugPrint("Login successful")
                        
                        // ✅ Option 1: Launch One-to-One or Group Chat Screen
                        // DispatchQueue.main.async { 
                        //     self.setUpOneOneOrGroupConversation(windowScene: windowScene, uid: "cometchat-uid-2")
                        // }

                        // ✅ Option 2: Launch Conversation List + Message View
                        // DispatchQueue.main.async {
                        //     self.setupConversationsView(windowScene: windowScene)
                        // }

                        // ✅ Option 3: Launch Tab-Based Chat Experience
                        // DispatchQueue.main.async {
                        //     self.setupTabbedView(windowScene: windowScene)
                        // }
                        
                    case .onError(let error):
                        debugPrint("Login failed: \(error.description)")
                    @unknown default:
                        break
                    }
                }
                
            case .failure(let error):
                debugPrint("Init failed: \(error.localizedDescription)")
            }
        }
    }
}
```

For development, use one of the pre-created test UIDs:

`cometchat-uid-1` · `cometchat-uid-2` · `cometchat-uid-3` · `cometchat-uid-4` · `cometchat-uid-5`

Or create new users via the [CometChat Dashboard](https://app.cometchat.com), [SDK method](/ui-kit/ios/methods#create-user), or [REST API](/rest-api/chat-apis).

After running the app, you should see:

```sh theme={null}
"CometChat initialized"
"Login successful"
```

<Warning>
  `init()` must complete before you call `login()`. If you call `login()` before init completes, it will fail silently.
</Warning>

<Note>
  For production, use [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-auth-token) instead of Auth Key. Generate tokens server-side via the REST API.
</Note>

<Tip>
  Having issues? Check the [Troubleshooting Guide](/ui-kit/ios/troubleshooting) for common problems and solutions.
</Tip>

***

## Step 5 — Choose a Chat Experience

Integrate a conversation view that suits your app's UX. Each option below includes a step-by-step guide.

### Conversation List + Message View

Two-panel layout — conversation list with push navigation to messages. Think iMessage or WhatsApp.

* Push-based navigation between conversations and messages
* Supports one-to-one and group chats
* Real-time sync with CometChat event listeners
* Session-aware — message states persist across app sessions

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/PaxBG9I1yMoeQmt2/images/39abbd91-chat_experience_sidebar_message-6476f0d5e48fdff63caa68809e60486b.png?fit=max&auto=format&n=PaxBG9I1yMoeQmt2&q=85&s=9cd6163214680273b9c0f64f8ed9d0f3" width="1440" height="833" data-path="images/39abbd91-chat_experience_sidebar_message-6476f0d5e48fdff63caa68809e60486b.png" />
</Frame>

<Card title="Build Conversation List + Message View" href="/ui-kit/ios/ios-conversation" icon="comments">
  Step-by-step guide to build this layout
</Card>

***

### One-to-One / Group Chat

Single chat window — no sidebar. Good for support chat, contextual messaging, or focused conversations.

* Dedicated chat window for one-on-one or group messaging
* No conversation list — users go directly into the chat
* Full-screen experience optimized for mobile
* Ideal for support workflows, community replies, or invitations

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/mkn0UqPQ5BXljCV1/images/92ec645e-chat_experience_one_on_one-6f97cccc721ff1a9b7d485586484b46c.png?fit=max&auto=format&n=mkn0UqPQ5BXljCV1&q=85&s=5764fc3d463553f3e506a7d026e2d83a" width="1440" height="833" data-path="images/92ec645e-chat_experience_one_on_one-6f97cccc721ff1a9b7d485586484b46c.png" />
</Frame>

<Card title="Build One-to-One / Group Chat" href="/ui-kit/ios/ios-one-to-one-chat" icon="message">
  Step-by-step guide to build this layout
</Card>

***

### Tab-Based Chat

Tabbed navigation — Chats, Calls, Users, Groups in separate tabs. Good for full-featured apps.

* UITabBarController or SwiftUI TabView navigation
* Full-screen messaging within each tab
* Modular UI — isolated controllers for each tab
* Scales well for adding future features like notifications or settings

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-rn-guide-message-privately/XgQ9DxAoWn0btB5m/images/5b38497c-chat_experience_full_tab_based-a7070249301dc3e08dd68c3d466e1aa4.png?fit=max&auto=format&n=XgQ9DxAoWn0btB5m&q=85&s=0a50880f8cfdbafcb46c4139bd27000f" width="1440" height="833" data-path="images/5b38497c-chat_experience_full_tab_based-a7070249301dc3e08dd68c3d466e1aa4.png" />
</Frame>

<Card title="Build Tab-Based Chat" href="/ui-kit/ios/ios-tab-based-chat" icon="table-columns">
  Step-by-step guide to build this layout
</Card>

***

## Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.

* [Sample App](https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp) — Working reference app to compare against
* [Components](/ui-kit/ios/components-overview) — All prebuilt UI elements with customization options
* [Core Features](/ui-kit/ios/core-features) — Messaging, real-time updates, and other capabilities
* [Theming](/ui-kit/ios/theme-introduction) — Colors, fonts, dark mode, and custom styling
* [Build Your Own UI](/sdk/ios/overview) — Skip the UI Kit entirely and build on the raw SDK

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Components Overview" icon="grid-2" href="/ui-kit/ios/components-overview">
    Browse all prebuilt UI components
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/ios/theme-introduction">
    Customize colors, fonts, and styles
  </Card>

  <Card title="Core Features" icon="comments" href="/ui-kit/ios/core-features">
    Chat features included out of the box
  </Card>

  <Card title="Methods" icon="code" href="/ui-kit/ios/methods">
    SDK methods and API reference
  </Card>
</CardGroup>