/ SDKs / iOS
SDKs
Chat SDKs iOS v4
Chat SDKs iOS
Chat SDKs
iOS
Version 4

Send your first message

Copy link

With Sendbird Chat SDK for iOS, you can efficiently integrate real-time chat into a client app. On the client-side implementation, you can initialize and configure the chat with minimal effort. On the server-side, Sendbird ensures reliable infra-management services for the chat service within your app.

This page demonstrates how to install the Chat SDK in your app so that you can send your first message in just a few simple steps.

Note: The fastest way to see Sendbird Chat SDK in action is to build your app on top of our sample app. Download the sample app to jumpstart your build.


Requirements

Copy link

The minimum requirements for Chat SDK for iOS are the following.

  • macOS
  • Xcode 14.1 and later
  • At least one device running iOS 11.0 and later
  • Swift 5.0 and later or Objective-C

Note: Starting on April 25, 2023, you must build and test your app with Xcode 14.1 or later to submit to the App Store. You can use the existing Sendbird SDK versions built with both Xcode 13.x and Xcode 14.1+ but Sendbird is repackaging Chat for iOS with Xcode 14.1 and minimum iOS version of 11.0 starting on April 25, 2023.

Note: The Sendbird server supports Transport Layer Security (TLS) from version 1.0 up to 1.3. For example, in the server regions where TLS 1.3 isn't available, lower versions, sequentially from 1.2 to 1.0, will be supported for secure data transmission.


Before you start

Copy link

In this quickstart guide, you will be installing Sendbird SDK, implementing codes to create a open channel with a user, and send a message within a few minutes. Before you start, you need to have the following:

Create a Sendbird application from dashboard

Copy link

A Sendbird application comprises everything required in a chat service including users, messages, and channels. You need the Application ID of your Sendbird application from the dashboard when initializing the Chat SDK.

  1. Go to Sendbird Dashboard and create an account for a free trial. If you already have a Sendbird account, sign into your account.

  2. Create a new application by clicking Create + at the bottom right of your screen.

  3. Enter a name for your application. Choose a Product Type and Region. Then, click Confirm.

  4. Click the application you just created under Applications. You will see the application's Application ID which you will need when initializing the Chat SDK.

Note: Each Sendbird application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web.

Create a user in the Sendbird application

Copy link

In order to send a message, you need a user in a channel. You can either create a user on the Sendbird dashboard first or you can use a new unique ID that hasn’t been taken by any of your Sendbird application users. In the latter case, a new user is automatically created in your Sendbird application before being connected.

In this guide, we will create a user on the Sendbird dashboard first.

  1. Go to the Users menu on the left-hand side of the dashboard and click Create user+.

  2. Enter the User ID and Nickname. It is recommended that you check the box next to Issue access token for user authentication. Then, click Create.

Note: Sendbird supports user authentication through access token for stronger security. However, on the dashboard, you can also configure the token permission in Settings > Application > Security > Access token permission to allow users without a token to access our functionalities. To learn more, see Authentication.

  1. Copy and store the user ID. You will use it to connect to the Sendbird server.

Sendbird UIKit

Copy link

UIKit is a Sendbird Chat SDK add-on with user interfaces that enable an easy and fast integration of standard chat features into new or existing client apps.

If you would like a sample app with embedded UI, see UIKit Overview for iOS.

Access control list

Copy link

Sendbird provides various access control options when using the Chat SDK. By default, the following attributes are turned on to avoid unexpected errors when creating sample apps and sending your first message:

  • Allow retrieving user list
  • Allow updating user metadata
  • Allow creating open channels
  • Allow creating group channels

However, this may grant access to unwanted data or operations, leading to potential security concerns. To manage your access control settings, you can turn on or off each option in Settings > Application > Security > Access control list on Sendbird Dashboard.


Get started

Copy link

To send a message in a client app, you should build and configure an in-app chat using Sendbird Chat SDK.

Some methods in the following steps are asynchronous. When using asynchronous methods, client apps must receive success callbacks from the Sendbird server through completion delegates in order to proceed to the next step. A good way to achieve this is by nesting the methods.

Note: For best performance, subclassing isn't recommended in Sendbird Chat SDK v4 for iOS. Using subclassing may result in errors that demand more time to be resolved.

Step 1 Create a project

Copy link

Create an Xcode project.

Step 2 Install the Chat SDK

Copy link

Installing the Chat SDK is simple if you're familiar with using external libraries or SDK's in your projects. Sendbird Chat SDK can be installed through either Swift Packages, CocoaPods, or Carthage.

If you don't want to use package managers, check out the manual installation guide.

Note: The name of the framework and the module is SendbirdChatSDK while the main class in the SDK is called SendbirdChat.

Swift Packages

Copy link

You can use an Xcode native package manager Swift packages for installation.

  1. Open Xcode, go to your project's General settings tab, and select your project under Project in the left column.

  2. Go to the Swift packages tab and click the + button.

  1. When a pop-up shows, enter our github repository address in the search bar. The address is https://github.com/sendbird/sendbird-chat-sdk-ios.

  1. Set Rules and click Next.

  1. Check SendbirdChatSDK in the Package product column and click Finish. This will establish a Swift Package Dependency menu in Xcode.

CocoaPods

Copy link
  1. Open a terminal window, move to your project directory, and then create a Podfile by running the following command.
$ pod init
  1. A Podfile will be created in your project folder. Open the Podfile and modify the file like the following.
platform :ios, '11.0'

target 'YOUR_PROJECT_NAME' do
    # Comment out the next line if you don't want to use dynamic frameworks.
    use_frameworks!

    # Pods for YOUR_PROJECT_NAME.
    pod 'SendbirdChatSDK', '~> 4.0.0'
end
  1. Then install the SendbirdChatSDK framework by running the following command in the same terminal window.
$ pod install
  1. In the folder, you will see a new project file in the .xcworkspace format. Now you can build your project with the SendbirdChatSDK framework in the file.

Carthage

Copy link
  1. Open a terminal window and add the following line to create a Cartfile in your project folder.
$ touch Cartfile
  1. Move to your project directory, open the Cartfile, and add the following line to your Cartfile.
github "sendbird/sendbird-chat-sdk-ios"
  1. Run the carthage update command to download Sendbird Chat SDK for iOS.
$ carthage update --use-xcframeworks
  1. Once the update is complete, go to your Xcode project's General settings tab. Then, open the <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS in the Finder window and drag and drop the SendbirdChatSDK.xcframework folder to the Frameworks, Libraries, and Embedded section in Xcode.

Step 3 Import the Chat SDK

Copy link

With one simple import statement, you can use all classes and methods in both Swift and Objective-C without a bridging header file.

import SendbirdChatSDK

Note: Interacting with Objective-C APIs in Swift can help you understand how to use the Chat SDK in Swift syntax.

Step 4 Initialize the Chat SDK

Copy link

Now, initialize the Chat SDK in the app to allow the Chat SDK to respond to changes according to the connection status in iOS client apps. Initialization requires your Sendbird application's APP_ID, which can be found on Sendbird Dashboard.

Before calling the initialize(params:migrationStartHandler:completionHandler:) method, create an InitParams object with your Sendbird application ID. In the params, you can also determine whether to enable local caching and synchronous initialization.

let initParams = InitParams(
    applicationId: APP_ID,
    isLocalCachingEnabled: true,
    logLevel: .info,
    needsSynchronous: false
)

SendbirdChat.initialize(
    params: params,
    migrationStartHandler: {
        // Migration starts.    
    },
    completionHandler: { error in
        // Migration completed.    
    }
)

The completionHandler method gets the initialization status through different event handlers. The migrationStartHandler method is called when there's an upgrade in the local database. Meanwhile, the completionHandler method informs the client app whether the initialization is complete.

Local caching

Copy link

If the initialization fails when you set isLocalCachingEnabled to true, the SDK will operate normally and change the value of isLocalCachingEnabled to false. If you still wish to use local caching, clear the database using clearCachedData(completionHandler:) and try the initialization again with isLocalCachingEnabled set to true.

Synchronous initialization

Copy link

Also, if you are using local caching, you can also set the needsSynchronous parameter of the InitParams object to true to ensure that the migration process is completed before the app is fully launched. By default, the needsSynchronous parameter is set to false so that migration proceeds asynchronously for reduced initialization time and thus expedited performance and runtime. However, if you don't need Sendbird's features upon launching your app, you can set the needsSynchronous parameter to true and have it run synchronously. If you aren't using local caching, this parameter doesn't affect the initialization process.

Note: The initialize(params:migrationStartHandler:completionHandler:) method of a SendbirdChat instance must be called across a client app at least once. We recommend that you initialize Sendbird Chat SDK through the application:didFinishLaunchingWithOptions: method of the AppDelegate instance.

Initialization dependency management

Copy link

When you call SendbirdChat.initialize(params:migrationStartHandler:completionHandler:), the method initializes the Sendbird Chat SDK asynchronously.

In the meantime, when you need to call SendbirdChat functions asynchronously from a different class or method, use the executeOrWaitForInitialization(executeHandler:) method of the SendbirdChat class. This function ensures either of the following two scenarios:

  • If the SendbirdChat initialization has been completed, the function executes the executeHandler block immediately.
  • If not, the function waits until the initialization is completed and then executes the executeHandler block.

This approach allows for seamless integration of Sendbird Chat functionalities, ensuring that initialization dependencies are properly managed.

Swift
SendbirdChat.executeOrWaitForInitialization {
    // Implement logic to perform once initialization is complete.
}

Step 5 Connect to the Sendbird server

Copy link

You need a user connected to the Sendbird server first before sending a message to a channel.

  • If you already have a user in your Sendbird application: In connect(), specify a user ID from the user list in your Sendbird application.

  • If you don't have an existing user: Specifying a unique userId in connect() will automatically generate a new user in your Sendbird application before being connected.

Note: Sendbird supports user authentication via access tokens, but defaults to allowing access without a token for ease of initial use. For enhanced security, we recommend adjusting access settings under Settings > Application > Security > Access token permission on the dashboard for new users. To learn about access token and authentication, see the Authentication guide.

// In USER_ID, use the ID of a user you've created on the dashboard.
// If there isn't one, specify a unique ID so that a new user can be created with the value.
SendbirdChat.connect(userId: USER_ID) { user, error in
    guard let user = user, error == nil else {
        // Handle error.
        return
    }

    // The user is connected to the Sendbird server.
}

Step 6 Create a new open channel

Copy link

Create an open channel using the following code blocks. Open channels are where all users in your Sendbird application can easily participate without an invitation.

let params = OpenChannelCreateParams()
params.name = CHANNEL_NAME

OpenChannel.createChannel(params: params) { channel, error in
    guard let channel = channel, error == nil else {
        // Handle error.
        return
    }

    // An open channel is successfully created.
    // Through the channel parameter of the callback method,
    // you can get the open channel's data from the Sendbird server.
}

Note: You can also create a group channel to send a message. To learn more, see the create a channel page.

Step 7 Enter the channel

Copy link

Enter the open channel to send and receive messages.

let params = OpenChannelCreateParams()
params.name = CHANNEL_NAME

// The following sample code continues from Step 6.
OpenChannel.createChannel(params: params) { channel, error in
    guard let channel = channel, error == nil else {
        // Handle error.
        return
    }

    channel.enter { error in
        guard error == nil else {
            // Handle error.
            return
        }

        // The current user has successfully entered the open channel
        // and can chat with other users in the channel using APIs.
    }
}

Step 8 Send a message to the channel

Copy link

Finally, send a message to the channel. To learn about the message types you can send, refer to Message overview in Chat Platform API.

You can check the message you've sent in Sendbird Dashboard. To learn about receiving a message, refer to the receive messages through a channel event handler page.

channel.sendUserMessage(MESSAGE) { message, error in
    guard let message = message, error == nil else {
        // Handle error.
        return
    }

    // The message object is successfully sent to the channel object.
    // The current user can receive messages from other users through
    // the channel(_:didReceiveMessage:) method of an event delegate.
}