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

Integrate with AI Coding Agents

Skip the manual steps — use 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.
Use --ide <name> to target a specific IDE (e.g. --ide cursor), or --ide all for all supported IDEs. Then in your IDE:
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.

Prerequisites

You need three things from the CometChat Dashboard: You also need:
  • Xcode 16 or later
  • iOS device or simulator running iOS 13.0+
  • Swift 5.0+
  • macOS
Auth Key is for development only. In production, generate Auth Tokens server-side via the REST API and use loginWithAuthToken(). Never ship Auth Keys in client code.

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

  1. Create a Podfile in your project root:
  1. Add CometChat to your Podfile:
Podfile
  1. Install dependencies:
  1. Close the .xcodeproj file and open the .xcworkspace file instead. CocoaPods creates a workspace that includes your project and the installed pods.
Always open the .xcworkspace file after installing pods — opening the .xcodeproj will cause build errors. Having issues? See CocoaPods Troubleshooting.

Step 3 — Configure Permissions

Add these keys to your Info.plist for media messaging:
Info.plist
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

Step 4 — Initialize & Login

Add this to your SceneDelegate.swift. Init must complete before login, and login must complete before rendering any UI.
SceneDelegate.swift
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, SDK method, or REST API. After running the app, you should see:
init() must complete before you call login(). If you call login() before init completes, it will fail silently.
For production, use loginWithAuthToken() instead of Auth Key. Generate tokens server-side via the REST API.
Having issues? Check the Troubleshooting Guide for common problems and solutions.

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

Build Conversation List + Message View

Step-by-step guide to build this layout

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

Build One-to-One / Group Chat

Step-by-step guide to build this layout

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

Build Tab-Based Chat

Step-by-step guide to build this layout

Build Your Own Chat Experience

Need full control over the UI? Use individual components, customize themes, and wire up your own layouts.
  • Sample App — Working reference app to compare against
  • Components — All prebuilt UI elements with customization options
  • Core Features — Messaging, real-time updates, and other capabilities
  • Theming — Colors, fonts, dark mode, and custom styling
  • Build Your Own UI — Skip the UI Kit entirely and build on the raw SDK

Next Steps

Components Overview

Browse all prebuilt UI components

Theming

Customize colors, fonts, and styles

Core Features

Chat features included out of the box

Methods

SDK methods and API reference