Quick start

This doc will guide you to integrate the In-app Chat Kit and start a chat quickly.

Prerequisites

Go to ZEGOCLOUD Admin Console and do the following:
1. Create a project, and get the AppID and AppSign of your project.
2. Activate the In-app Chat service.

Environment-specific requirements:
- Xcode 13.0 or later
- An iOS device that is running on iOS 12.0 or later
- The device is connected to the internet.

Integrate the SDK

Note

The CocoaPods version needs to be 1.10.0 or later.

Add ZIMKit as a dependency to your project using CocoaPods

Open Podfile and add pod 'ZIMKit'

Podfile

target 'MyProject' do
  use_frameworks!
# !mark
  pod 'ZIMKit'
end

Podfile

target 'MyProject' do
  use_frameworks!
# !mark
  pod 'ZIMKit'
end

Execute the command pod repo update to update the local index and ensure that you can install the latest version of the SDK.

pod repo update

pod repo update

Execute pod install to install the SDK.

pod install

pod install

Set up relevant permissions

Open the Info.plist file and add the following:

<key>NSMicrophoneUsageDescription</key>
<string>We require microphone access to use zimkit.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We require photo access to use zimkit.</string>

<key>NSMicrophoneUsageDescription</key>
<string>We require microphone access to use zimkit.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We require photo access to use zimkit.</string>

Call the init method to initialize the In-app Chat Kit

AppDelegate.swift

import UIKit
import ZIMKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let appID: UInt32 = <#your appID#> // The AppID you get from ZEGOCLOUD Admin Console.
        let appSign: String = <#your appSign#> // The AppSign you get from ZEGOCLOUD Admin Console.
// !mark
        ZIMKit.initWith(appID: appID, appSign: appSign)
    }
}

AppDelegate.swift

import UIKit
import ZIMKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let appID: UInt32 = <#your appID#> // The AppID you get from ZEGOCLOUD Admin Console.
        let appSign: String = <#your appSign#> // The AppSign you get from ZEGOCLOUD Admin Console.
// !mark
        ZIMKit.initWith(appID: appID, appSign: appSign)
    }
}

Call the connectUser method on the login page to log in to the In-app Chat Kit

Warning

You can customize rules to generate the user ID and user name. We recommend that you set a meaningful user ID. You can associate the user ID with your business account system.

viewController.swift

import UIKit
import ZIMKit

/// your viewController.swift
class ViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let connectUserButton = UIButton(type: .custom)
        connectUserButton.setTitle("Connect User And Show", for: .normal)
        connectUserButton.frame = .init(x: 100, y: 100, width: 250, height: 50)
        connectUserButton.addTarget(self, action: #selector(connectUserAction), for: .touchUpInside)
        connectUserButton.backgroundColor = .orange
        view.addSubview(connectUserButton)

    }

    @objc func connectUserAction(_ sender: Any) {
        // Your ID as a user.
        let userID: String = "<#your userID#>" 
        // Your name as a user.
        let userName: String = "<#your userName#>" 
        // The image you set as the user avatar must be network image. e.g., https://doc-media.zego.im/IMKit/avatar/avatar-0.png
        let userAvatarUrl: String = "<#your userAvatarUrl#>" 

// !mark(1:6)
        ZIMKit.connectUser(userID: userID, userName: userName, avatarUrl: userAvatarUrl) { error in
            //  Display the UI views after connecting the user successfully. 
            if error.code == .success {
                self?.showConversationListVC()
            }  
        }
    }
}

viewController.swift

import UIKit
import ZIMKit

/// your viewController.swift
class ViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let connectUserButton = UIButton(type: .custom)
        connectUserButton.setTitle("Connect User And Show", for: .normal)
        connectUserButton.frame = .init(x: 100, y: 100, width: 250, height: 50)
        connectUserButton.addTarget(self, action: #selector(connectUserAction), for: .touchUpInside)
        connectUserButton.backgroundColor = .orange
        view.addSubview(connectUserButton)

    }

    @objc func connectUserAction(_ sender: Any) {
        // Your ID as a user.
        let userID: String = "<#your userID#>" 
        // Your name as a user.
        let userName: String = "<#your userName#>" 
        // The image you set as the user avatar must be network image. e.g., https://doc-media.zego.im/IMKit/avatar/avatar-0.png
        let userAvatarUrl: String = "<#your userAvatarUrl#>" 

// !mark(1:6)
        ZIMKit.connectUser(userID: userID, userName: userName, avatarUrl: userAvatarUrl) { error in
            //  Display the UI views after connecting the user successfully. 
            if error.code == .success {
                self?.showConversationListVC()
            }  
        }
    }
}

Display the conversation component of the In-app Chat Kit

viewController.swift

/// your viewController.swift
func showConversationListVC() {
    let conversationVC = ZIMKitConversationListVC()
    let nav = UINavigationController(rootViewController: conversationVC)
    nav.modalPresentationStyle = .fullScreen
    self.present(nav, animated: true)
}

viewController.swift

/// your viewController.swift
func showConversationListVC() {
    let conversationVC = ZIMKitConversationListVC()
    let nav = UINavigationController(rootViewController: conversationVC)
    nav.modalPresentationStyle = .fullScreen
    self.present(nav, animated: true)
}

Ideally, by this point, your app will look like this:

Start a chat

The In-app Chat Kit supports the following features:

Start a one-on-one chat

Warning

Whether starting a one-on-one chat or a group chat, the peer user you want to chat with/the users you want to invite to a chat group must have logged in to the In-app Chat UIKit at least once. Otherwise, an error will occur.

Get the userID that is generated using your own business logic. (the userID here refers to the peer user you want to chat with.)
Fill in the userID parameter and run the following code:

ViewController.swift

import UIKit
import ZIMKit

/// your ViewController.swift
class ViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
    }
    
    // Call this method anywhere you need it after a successful login.
    func startOneOnOneChat(userID: String) {
        let messageVC = ZIMKitMessagesListVC(conversationID: userID, type: .peer)
        messageVC.modalPresentationStyle = .fullScreen
        present(messageVC, animated: true)

        // Replace the [present] method with the following code if you already use the Navigation Controller.
        // navigationController?.pushViewController(messageVC, animated: true)
    }
}

ViewController.swift

import UIKit
import ZIMKit

/// your ViewController.swift
class ViewController: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
    }
    
    // Call this method anywhere you need it after a successful login.
    func startOneOnOneChat(userID: String) {
        let messageVC = ZIMKitMessagesListVC(conversationID: userID, type: .peer)
        messageVC.modalPresentationStyle = .fullScreen
        present(messageVC, animated: true)

        // Replace the [present] method with the following code if you already use the Navigation Controller.
        // navigationController?.pushViewController(messageVC, animated: true)
    }
}

Start a group chat

Get the userIDs and groupName that are generated using your own business logic. (the userIDs here refers to the ID list of the users that you want to invite to the group chat.)
Fill in the userIDs and groupName parameters and run the following code:

ViewController.swift

import UIKit
import ZIMKit

/// your ViewController.swift
class ViewController1: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
    }
    
    // Call this method anywhere you need it after a successful login.
    func createGroupChat(userIDs: [String], groupName: String) {
        ZIMKit.createGroup(with: groupName, inviteUserIDs: userIDs) { [weak self] groupInfo, inviteUserErrors, error in
            if error.code == .success {
                if inviteUserErrors.count > 0 {
                    // Implement the logic for the prompt window based on your business logic when there is a non-existing user ID in the group.

                } else {
                    // Directly enter the chat page when the group chat is created successfully.
                    self?.showGroupMessageListVC(groupID: groupInfo.id)
                }
            } else {
                // Implement the logic for the prompt window based on the returned error info when failing to create a group chat. 

            }
        }
    }
    
    func showGroupMessageListVC(groupID: String) {
        let messageVC = ZIMKitMessagesListVC(conversationID: groupID, type: .group)
        messageVC.modalPresentationStyle = .fullScreen
        present(messageVC, animated: true)

        // Replace the [present] method with the following code if you already use the Navigation Controller.
        // navigationController?.pushViewController(messageVC, animated: true)
    }
}

ViewController.swift

import UIKit
import ZIMKit

/// your ViewController.swift
class ViewController1: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
    }
    
    // Call this method anywhere you need it after a successful login.
    func createGroupChat(userIDs: [String], groupName: String) {
        ZIMKit.createGroup(with: groupName, inviteUserIDs: userIDs) { [weak self] groupInfo, inviteUserErrors, error in
            if error.code == .success {
                if inviteUserErrors.count > 0 {
                    // Implement the logic for the prompt window based on your business logic when there is a non-existing user ID in the group.

                } else {
                    // Directly enter the chat page when the group chat is created successfully.
                    self?.showGroupMessageListVC(groupID: groupInfo.id)
                }
            } else {
                // Implement the logic for the prompt window based on the returned error info when failing to create a group chat. 

            }
        }
    }
    
    func showGroupMessageListVC(groupID: String) {
        let messageVC = ZIMKitMessagesListVC(conversationID: groupID, type: .group)
        messageVC.modalPresentationStyle = .fullScreen
        present(messageVC, animated: true)

        // Replace the [present] method with the following code if you already use the Navigation Controller.
        // navigationController?.pushViewController(messageVC, animated: true)
    }
}

Join a group chat

Get the groupID that is generated using your own business logic. (the groupID here refers to the group chat you want to join.)
Fill in the groupID parameter and run the following code:

ViewController.swift

import UIKit
import ZIMKit

/// your ViewController.swift
class ViewController1: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
    }

    // Call this method anywhere you need it after a successful login.
    func joinGroupChat(_ groupID: String) {
        ZIMKit.joinGroup(by: groupID) { [weak self] groupInfo, error in
            if error.code == .success {
                // Display the group chat page after joining a group chat successfully.
                self?.showGroupMessageListVC(groupID: groupInfo.id)
            }
        }
    }
    
    func showGroupMessageListVC(groupID: String) {
        let messageVC = ZIMKitMessagesListVC(conversationID: groupID, type: .group)
        messageVC.modalPresentationStyle = .fullScreen
        present(messageVC, animated: true)

        // Replace the [present] method with the following code if you already use the Navigation Controller.
        // navigationController?.pushViewController(messageVC, animated: true)
    }
}

ViewController.swift

import UIKit
import ZIMKit

/// your ViewController.swift
class ViewController1: UIViewController {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
    }

    // Call this method anywhere you need it after a successful login.
    func joinGroupChat(_ groupID: String) {
        ZIMKit.joinGroup(by: groupID) { [weak self] groupInfo, error in
            if error.code == .success {
                // Display the group chat page after joining a group chat successfully.
                self?.showGroupMessageListVC(groupID: groupInfo.id)
            }
        }
    }
    
    func showGroupMessageListVC(groupID: String) {
        let messageVC = ZIMKitMessagesListVC(conversationID: groupID, type: .group)
        messageVC.modalPresentationStyle = .fullScreen
        present(messageVC, animated: true)

        // Replace the [present] method with the following code if you already use the Navigation Controller.
        // navigationController?.pushViewController(messageVC, animated: true)
    }
}

Component overview

Click here to explore more UI components.

Run the sample code

A quick guide to help you run the sample code.

Get support

Need help or want to raise your questions? Click the button below to join our Discord community to get quick responses.

Join Discord community

Quick start

Prerequisites

Integrate the SDK

Start a chat

Related guides

Get support