iOS
Calls Quick Start

Quick Start

Sendbird Calls enables real-time voice and video calls between users within your Sendbird-integrated app. The Calls SDK for iOS is used to initialize, configure, and build voice and video calling functionality into your iOS application. This quick start shows a brief overview of the Calls SDK’s structure and features, then goes through the preliminary steps of implementing the Calls SDK into your own project.


Try the sample app

Our sample app demonstrates an implementation of the core features of Sendbird Calls SDK. Download the app from our GitHub repository to get an idea of what you can do with the actual SDK and to get started building your own project.

Download Sample App

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


How Sendbird Calls SDK works with your app

Sendbird Calls can only be used by your Sendbird application users. When a user logs in, the user can send and receive direct calls with other users on the same Sendbird application.

Direct call in the Calls SDK refers to a one-to-one call. To make a direct call, the caller first initializes a call request to the callee. The callee will receive incoming call notifications to all logged in devices. When the callee accepts the call on any of these devices, a media connection is established between the caller and callee which marks the start of a direct call.

Call-related events are delivered through call event delegates. The event delegates include didEnterRining:, didConnect:, didEnd:, and other delegate methods. By using the methods of the delegates, your app can implement appropriate responses and actions accordingly such as updating call status on the UI level.


Requirements

The minimum requirements for Calls SDK for iOS are:

  • iOS 9.0 and later
  • Swift 4.0 and later

Install and configure the Calls SDK

Installing the Calls SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. After creating your Sendbird application from your dashboard, install Git Large File Storage (LFS), then you can choose to install the Calls SDK using either CocoaPods or Carthage.

Step 1: Create a Sendbird application from your dashboard

A Sendbird application comprises everything required in a Calls service including users, message, and channels. To create an application:

  1. Go to the Sendbird Dashboard and enter your email and password, and create a new account. You can also sign up with a Google 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. A Sendbird application can also be created through the Chat API.

Only one Sendbird application can be integrated per app for your service regardless of the platform. All users within your Sendbird application can communicate with each other across all platforms. This means that your iOS, Android, and web client app users can all make and receive calls with one another without any further setup. It should be noted that all data are limited to the scope of a single application, and users in different Sendbird applications can't make and receive calls to each other.

Note: For application administrators, the Sendbird Dashboard provides call logs to keep track of all calls made on the application.

Step 2: Install Git Large File Storage

To use Sendbird Calls, you should first add our custom-built WebRTC framework to your project. Git LFS must be installed to use the WebRTC framework along with the SendBirdCalls framework.

  1. Run brew install git-lfs in your project directory.
  2. Refer to https://git-lfs.github.com.

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, and web client app users can all make and receive calls 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 make and receive calls to each other.

Note: Make sure to install Git LFS before installing CocoaPods. Check the size of the WebRTC.framework in the YOUR_PROJECT_DIRECTORY/Pods/SendBirdWebRTC folder. The framework must be over 800 MB. If it is less than 800 MB, follow the steps in the Calls SDK’s Troubleshooting section.

Step 3: Install the Calls SDK with CocoaPods or Carthage

Installing the Calls SDK is simple if you’re familiar with using external libraries or SDKs in your project. You can install the Calls SDK using CocoaPods or Carthage.

CocoaPods

  1. Install CocoaPods into your project by running pod init in your project directory.
  2. Run the command, open Podfile.
  3. In the opened Podfile, include pod ‘SendBirdCalls’ to your configuration under your project target.
  4. Install the SendBirdCalls framework by running pod install in your project directory.

Carthage

You can also use Carthage to integrate the SendBirdCalls framework into your Xcode project.

  1. Install Carthage into your project by running brew install carthage in your project directory or choose another installation options.
  2. Create a Cartfile in the same directory where your .xcodeproj or .xcworkspace is.
  3. Add github “sendbird/sendbird-calls-ios” and github “sendbird/sendbird-webrtc-ios” dependencies to your Cartfile.
  4. Run carthage update.
  5. A Cartfile.resolved file and a Carthage directory will appear in the same directory where your .xcodeproj or .xcworkspace is.
  6. Drag the built .framework binaries from Carthage/Build/iOS into your application’s Xcode project.
  7. On your application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell: usr/local/bin/carthage copy-frameworks
  8. Add the paths to the frameworks you want to use under Input Files. For example:
Light Color Skin
Copy
$(SRCROOT)/Carthage/Build/iOS/SendBirdCalls.framework
Light Color Skin
Copy
$(SRCROOT)/Carthage/Build/iOS/WebRTC.framework
  1. Add the paths to the copied frameworks to the Output Files. For example:
Light Color Skin
Copy
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/SendBirdCalls.framework
Light Color Skin
Copy
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/WebRTC.framework
  1. For more information, refer to the Carthage’s guide.

Step 4: Add capabilities to your app

You can use the Calls SDK along with Callkit in your app. To use some app services, you need to add background modes and push notifications to your app.

  1. For your app to continue running in the background, your app must have Background Modes enabled in the Xcode Project > Signing & Capabilities pane. Select the Voice over IP option under the list of available modes.
  2. Enable Remote notifications in Xcode Project > Signing & Capabilities.
  3. For more information about VoIP push notification and PushKit, refer to Apple's CallKit and PushKit.

Step 5: Request permission to access cameras and microphones

Your iOS client app needs to display authorization messages to your users to grant the app access to camera and microphone.

  1. To access device microphones for audio call, include the NSMicrophoneUsageDescription key in your app’s Info.plist file.
  2. To access device cameras for video call, include the NSCameraUsageDescription in your app’s Info.plist file.

Make your first call

The Calls SDK adds call features to your client app with a few simple steps. To make your first call, do the following steps:

Step 1: Initialize the Calls SDK in your app

First, the SendBirdCall instance must be initialized when a client app is launched. Initialization is done by using the APP_ID of your Sendbird application in the dashboard. If the instance is initialized with a different APP_ID, all existing call-related data in a client app will be cleared and the SendBirdCall instance will be initialized again with the new APP_ID.

Light Color Skin
Copy
SendBirdCall.configure(appId: APP_ID)

Step 2: Authenticate a user and add a registration token

Note: You can implement both the Chat and Calls SDKs to your client app. Two SDKs can work on the same Sendbird application for them to share users. In this case, you can allow Calls to retrieve a list of users in the client app by using the Chat SDK’s method or Chat API.

To make and receive calls, authenticate a user to Sendbird server by using their user ID through the authenticate() method. To receive calls while an app is in the background or closed, a user’s device token must be added to the server. A device token can be added by passing it as a parameter in the authenticate() method when authenticating a user, or by using the SendBirdCall.registerVoIPPush() method after a user’s authentication has been completed.

Note: Go to the VoIP Push Notifications page to learn more about registering push tokens.

Light Color Skin
Copy
// Authentication
let params = AuthenticateParams(userId: USER_ID, voipPushToken: VOIP_PUSH_TOKEN, accessToken: ACCESS_TOKEN)
SendBirdCall.authenticate(params: params) { (user, error) in
    guard let user = user, error == nil else {
        return
    }

    // The user has been authenticated successfully
}

Step 3: Add event delegates

There are two types of event handlers that the Calls SDK provides: SendBirdCallDelegate and DirectCallDelegate.

SendBirdCallDelegate

Add a device-specific SendBirdCallDelegate event delegate using the SendBirdCall.addDelegate(:) method. Once the event delegate is added, responding to device events such as incoming calls can be managed as shown below:

Light Color Skin
Copy
SendBirdCall.addDelegate(self, identifier: UNIQUE_HANDLER_ID)

class MyClass: SendBirdCallDelegate {
    func didStartRinging(_ call: DirectCall) {
        // Process incoming call
        // IMPORTANT: - Refer to Making a Call - Receive a Call for what to do here.
    }
}

DirectCallDelegate

Add a call-specific DirectCallDelegate event delegate using call.delegate. Responding to call-specific events such as call connected is then managed as shown below:

Light Color Skin
Copy
func didEstablish(_ call: DirectCall)
func didConnect(_ call: DirectCall)
func didRemoteAudioSettingsChange(_ call: DirectCall)
func didEnd(_ call: DirectCall)
... more call-specific delegate methods. 

// Refer to the API reference for more delegate methods

Step 4: Make a call

Initiate a call by providing the callee’s user ID into the SendBirdCall.dial() method. Use the CallOptions object to choose initial call configuration, such as audio or video capabilities, video settings, and mute settings.

Light Color Skin
Copy
let directCall = SendBirdCall.dial(to: CALLEE_ID, callOptions: CallOptions()) { (directCall, error) in
    // The call has been created successfully
}

directCall.delegate = self

Step 5: Receive a call

To receive an incoming call, a SendBirdCallDelegate event delegate should already be registered in the callee’s client app. Accept or decline the call using the directCall.accept() or the directCall.end() method. If the call is accepted, a media session will automatically be established by the Calls SDK.

Before accepting the call, the call-specific DirectCallDelegate event delegate must be added to the call object. It enables the callee’s app to react to events happening during the call through its callback methods.

Light Color Skin
Copy
SendBirdCall.addDelegate(self, identifier: UNIQUE_HANDLER_ID)
Class MyClass: SendBirdCallDelegate, DirectCallDelegate {
    func didStartRinging(_ call: DirectCall) {
        call.accept()
        call.delegate = self
    }
}

The callee’s client app receives an incoming call through either the established connection with Sendbird server or a VoIP Push Notifications when the app is in the background. To use the Calls SDK in the callee’s client app, the SendBirdCall instance must deliver received VoIP push notifications to the Calls SDK.

Light Color Skin
Copy
func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType) {
    SendBirdCall.pushRegistry(registry, didReceiveIncomingPushWith: payload, for: type, completionHandler:{ callUUID in 
    //
    })
}