iOS
Quick Start

Quick Start

Integrate real-time chat in your iOS client apps with speed and efficiency. Our iOS SDK helps you to focus on the client side implementation of initializing, configuring and building the chat. On the server side, SendBird ensures reliable infra management services with the SDK. This quick start shows a brief overview of the SDK’s structure and features, then goes through the preliminary steps of implementing the SDK in your own project.


Try the sample app

Our sample app has the core features of the SDK. Download the app from our GitHub repository to get an idea of what you can build with the actual SDK and start building in your project.

Download Sample App

Note: The fastest way to see our SDK in action is to build your messaging app on top of our sample app. Make sure to change the application ID of the sample app to your own. Go to the Create a new SendBird application from your dashboard section to learn more.


How SendBird works with your app

It is simple to implement messaging in your client app with the iOS SDK: a user logs in, sees a list of channels, selects or creates a channel, and sends a message to the channel while receiving messages from other users within the channel.

We provide two types of channels: open and group. An open channel is a public channel anyone can participate in and chat with others. A group channel is a private channel that users can join as new members through invitation only, and has numerous distinctive properties and features compared to an open channel. There are a variety of group channel subtypes such as a public group channel working like an open channel.

All sent messages within channels are automatically delivered to channel delegates registered to your app. While the SendBird instance in your user's client app is connected to SendBird server, the delegates receive callbacks from the server through didReceiveMessage:, userDidJoin:, and other methods. These callbacks contain message or channel objects with the latest information of an incoming message or other events related to the objects.


Install and configure the SDK

If you are ready to integrate chat to your app, follow the step-by-step instructions below.

Step 1: Create a SendBird application from your dashboard

First, create your SendBird application which comprises everything required in a chat service such as users, messages, and channels.

  1. In the SendBird Dashboard, type your email and password to create a new account. You can also sign in with or sign up for a Google or GitHub account.
  2. When prompted by the setup wizard, enter your organization information to manage SendBird applications.
  3. Lastly, when your dashboard home appears after completing setup, click Create App at the top-right corner for a new application. You can also create via the Platform API.

You can only integrate one SendBird application per app for your service regardless of the platforms. All users within your SendBird application can communicate with each other across all platforms. This means that your iOS, Android, web, .NET, and Unity client app users can all chat with one another without any further setup. Note that all data are limited to the scope of a single application, and users in different SendBird applications can't talk to each other.

Step 2: Install the SDK

Installing the SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. You can install the iOS SDK using CocoaPods or Carthage like the following.

With CocoaPods

If you've never used CocoaPods for a Xcode project, open a terminal window, move to your project directory, and then create a Podfile by running the following command.

Light Color Skin
Copy
$ pod init

Add the following lines to the Podfile.

Light Color Skin
Copy
platform :ios, '8.0'

target 'YourProject' do
  use_frameworks!

  pod 'SendBirdSDK'
end

And then install the SendBird framework through CocoaPods.

Light Color Skin
Copy
$ pod install

Now you can run your project with the SendBird Framework by opening *YOUR_PROJECT*.xcworkspace. If you don't want to use CocoaPods, check out the manual installation guide.

With Carthage

  1. Add github "sendbird/sendbird-ios-framework" to your Cartfile.
  2. Run carthage update.
  3. Go to your Xcode project's General settings. Open the <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS in the finder and drag SendBirdSDK.framework to the Embedded Binaries section in Xcode. Make sure the Copy items if needed option is selected and click Finish.

Turn on ARC

To use the SendBird framework, you should turn on the ARC (Automatic Reference Counting). To do that, go to your project's Build Settings, and then set the value of Objective-C Automatic Reference Counting to Yes (in Swift, Yes by default).

If you don't want to turn on ARC in a project-wide scope, then navigate to the Build Phases - Compile Sources and add -fobjc-arc to the Compiler Flags in the source file that the SendBird framework uses. This means that ARC is turned on only that file.

Step 3: Use the SDK in Objective-C and Swift

You can use all classes and methods just with the following one import statement, without a bridging header file, in both Objective-C and Swift.

Objective-C
Swift
Light Color Skin
Copy
#import <SendBirdSDK/SendBirdSDK.h>
Light Color Skin
Copy
import SendBirdSDK

The Interacting with Objective-C APIs in Swift helps you with understanding how to use the iOS SDK in Swift syntax.


Send your first message

The iOS SDK simplifies messaging into an effortless and straightforward process. To send your first message, do the following steps:

Note: The methods in the following steps are all asynchronous, excluding the initWithApplicationId:. This means that when using asynchronous methods, your client app must receive success callbacks from SendBird server through completion handlers in order to proceed to the next step. A good way to do this is the nesting of methods: Go to Step 4: Enter the channel to learn more about how to nest the enterChannelWithCompletionHandler: in the getChannelWithUrl:completionHandler: method.

Step 1: Initialize the SDK

To allow the iOS SDK to respond to the connection and state changes in your iOS client app, you first initialzize the SDK in the app. Pass in the App ID of the SendBird application you created earlier in the dashboard for the initialization.

Note: The initWithApplicationId: method of a SBDMain instance must be called once across your iOS client app. We recommend that you initialize the iOS SDK in the application:didFinishLaunchingWithOptions: method of the AppDelegate instance.

Objective-C
Swift
Light Color Skin
Copy
[SBDMain initWithApplicationId:APP_ID];
Light Color Skin
Copy
SBDMain.initWithApplicationId(APP_ID)

Step 2: Connect to SendBird server

Connect a user to SendBird server using their unique user ID. Any untaken user ID is automatically registered as a new user to the SendBird system before being connected, while an existing ID is allowed to log in directly.

Note: Go to the Authentication page to learn more about authenticating with an access token.

Objective-C
Swift
Light Color Skin
Copy
[SBDMain connectWithUserId:USER_ID completionHandler:^(SBDUser * _Nullable user, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }
}];
Light Color Skin
Copy
SBDMain.connect(withUserId: USER_ID) { (user, error) in
    guard error == nil else {   // Error. 
        return
    }
}

Step 3: Create a new open channel

Create an open channel. Once created, all users in your SendBird application can easily participate the channel.

Note: In a similar fashion, you can create a group channel by inviting users as new members to the channel.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel createChannelWithCompletionHandler:^(SBDOpenChannel * _Nullable openChannel, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }
}];
Light Color Skin
Copy
SBDOpenChannel.createChannel { (openChannel, error) in
    guard error == nil else {   // Error. 
        return
    }
}

Step 4: Enter the channel

Enter the channel to send and receive messages.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nullable openChannel, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }

    [openChannel enterChannelWithCompletionHandler:^(SBDError * _Nullable error) {
        if (error != nil) { // Error.
            return;
        }
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl("CHANNEL_URL") { (openChannel, error) in
    guard error == nil else {   // Error. 
        return
    }

    openChannel?.enter(completionHandler: { (error) in
        guard error == nil else {   // Error.
            return
        }
    })
}

Step 5: Send a message to the channel

Finally, send a message to the channel. There are three types: a user message is a plain text, a file message is a binary file, such as an image or PDF, and an admin message is a plain text sent through the dashboard or Platform API.

Objective-C
Swift
Light Color Skin
Copy
[openChannel sendUserMessage:MESSAGE data:DATA customType:CUSTOM_TYPE completionHandler:^(SBDUserMessage * _Nullable userMessage, SBDError * _Nullable error) {
    if (error != nil) { // Error. 
        return;
    }
}];
Light Color Skin
Copy
openChannel?.sendUserMessage(MESSAGE, data: DATA, customType: CUSTOM_TYPE, completionHandler: { (message, error) in
    guard error == nil else {   // Error. 
        return
    }
})