Quick Start

SendBird helps you to implement real-time chat to any application with speed and efficiency. Our iOS SDK provides you with various methods to initialize, configure and build the chat from the client side - no server side implementation required because our reliable infra management service is delivered with the SDK. This section presents a brief overview of the SDK’s functionalities and logic, then let you go through the preliminary steps of implementing SendBird in your own application


First, try out the sample app!

Our sample app is a fully functional messaging app. Download and build the sample from GitHub to chat freely with other people. The app gives you a picture of what you can build using SendBird, although it is by no means the limit of its capabilities.

The sample app is a useful reference when developing your own project using SendBird. In fact, a simple way to implement chat is to build your app on top of the sample. Note that you must change the App ID to your own in this case - reference to the Create a new SendBird application from our dashboard section.


How SendBird works with messaging

To build a messaging with the SendBird SDK is simple: a user connects, enters a channel, send a message to the channel, and receives the messages from all other users within the channel. There are two types of channels: Open and Group Channel. Open Channel is a public channel which anyone can enter and chat freely. Group Channel is basically a private channel that a user can join as a new member through an invitation. But it has various properties for its functionalities, so you can make a public group channel working like Open Channel.

When using the SDK, messages are automatically delivered to channel delegates. As long as an app instance is connected to our server, it receives callbacks to didReceiveMessage:, userDidJoin:, and so on, with the message or channel objects containing the latest information, in case of a message incoming or other relevant events happened.


Install and configure iOS SDK

Step 1: Create a new SendBird application from our dashboard

A SendBird application comprises everything that goes in a chatting service such as users, messages, and channels. Create a new SendBird application by singing in to our dashboard. Either that, you can sign up with Google, GitHub, or create a new account with the dashboard.

Once you create an application, all users within can communicate with each other, across all platforms. This means users using iOS, Android, and web clients can all chat with one another without any additional setup. However, all data is limited to the scope of one application, meaning users in different SendBird applications cannot 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 SendBird 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.

$ pod init

Add the following lines to the Podfile.

platform :ios, '8.0'

target 'YourProject' do
  use_frameworks!

  pod 'SendBirdSDK'
end

And then install the SendBird framework through CocoaPods.

$ pod install

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

With Carthage

  1. Add github "smilefam/sendbird-ios-framework" to your Cartfile.
  2. Run carthage update.
  3. Go to your Xcode project's General settings. Open <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS in 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

Turning on Automatic Reference Counting (ARC) is necessary to use the SendBird framework. Go to your project's Build Settings, 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 Build Phases - Compile Sources and add -fobjc-arc to the Compiler Flags in the source file that 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 with just one import statement - without a bridging header file - in both Objective-C and Swift.

#import <SendBirdSDK/SendBirdSDK.h>
import SendBirdSDK

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


Send your first message

The iOS SDK abstracts messaging into a simple and straightforward process. To send your first message, do the following steps:

Note: The following methods, excluding the initWithApplicationId: method of SBDMain, are asynchronous. This means you must ensure that you've received a success callback to proceed to the next step. A simple way to do this is the nest methods - see the example in Step 4: Enter the channel when enterChannelWithCompletionHandler: is called after receiving a getChannelWithUrl:completionHandler: callback of SBDOpenChannel.

Step 1: Initialize the SDK

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

Note: The initWithApplicationId: method of SBDMain should be called once across an iOS app. We recommend that you perform the SDK initialization in the application:didFinishLaunchingWithOptions: of AppDelegate class.

[SBDMain initWithApplicationId:APP_ID];
SBDMain.initWithApplicationId(APP_ID)

Step 2: Connect to SendBird server

Connect a user to a SendBird server using their User ID. Any untaken user ID creates a new user in the SendBird application before connecting, while an existing ID makes the user log in directly. Authentication with Access Tokens are discussed in the Authentication section.

[SBDMain connectWithUserId:USER_ID completionHandler:^(SBDUser * _Nullable user, SBDError * _Nullable error) {
    if (error != nil) {    // Error.
        return;
    }
}];
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 the SendBird application can freely enter the channel to converse.

Note: A group channel can be created in a similar manner. However, to have other users join the channel, an existing member of the channel (for example, the creator) must invite them first.

[SBDOpenChannel createChannelWithCompletionHandler:^(SBDOpenChannel * _Nullable channel, SBDError * _Nullable error) {
    if (error != nil) {    // Error.
        return;
    }
}];
SBDOpenChannel.createChannel { (channel, error) in
    guard error == nil else {    // Error. 
        return
    }
}

Step 4: Enter the channel

Enter the channel to view and send messages.

[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nullable channel, SBDError * _Nullable error) {
    if (error != nil) {    // Error.
        return;
    }

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

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

Step 5: Send a message to the channel

And finally, send a message to the channel! There are three types of messages: a User Message is a plain text message, a File Message is a binary file, such as an image or PDF, and an Admin Message is a special type of message sent through our dashboard or Platform API.

[channel sendUserMessage:MESSAGE data:DATA customType:CUSTOM_TYPE completionHandler:^(SBDUserMessage * _Nullable userMessage, SBDError * _Nullable error) {
    if (error != nil) {    // Error. 
        return;
    }
}];
channel?.sendUserMessage(MESSAGE, data: DATA, customType: CUSTOM_TYPE, completionHandler: { (message, error) in
    guard error == nil else {    // Error. 
        return
    }
})