Home
/
Calls
/
iOS

Make your first call

Sendbird Calls for iOS enables real-time voice and video calls for 1-to-1 calls or group calls among users within your Sendbird-integrated app. Our development kit can initialize, configure, and build voice and video calling functionality in your iOS app.

Sendbird Calls supports both Direct call and Group call. Follow the guide below to make your 1-to-1 call or start a group call from scratch using Swift and Objective-C.


Requirements

The minimum requirements for Calls SDK for iOS are:

  • iOS 9.0 and later
  • Swift 4.0 and later
  • Xcode 12 and later

Get started

You can start making a 1-to-1 call with Direct call or create a room to start a group call with Group call by installing Sendbird Calls for iOS.

Step 1 Create a project

Open Xcode and create a new project. Sendbird Calls supports Swift and Objective-C.

Step 2 Install Git Large File Storage

To use Sendbird Calls, you need to add our custom-built WebRTC and SendBirdCalls frameworks to your project. The WebRTC framework is a large sized file which requires you to install Git Large File Storage.

Light Color Skin
Copy
brew install git-lfs
git lfs install

Step 3 Install the SDK

You can install Calls for iOS through either CocoaPods or Carthage.

With CocoaPods

  1. Add SendBirdCalls framework into your Podfile in Xcode as below:
Light Color Skin
Copy
pod `SendBirdCalls`
  1. Install the SendBirdCalls framework through CocoaPods.
Light Color Skin
Copy
$ pod install

With Carthage

  1. Add SendbirdCalls and WebRTC into your Cartfile as below:
Light Color Skin
Copy
github "sendbird/sendbird-calls-ios"
github "sendbird/sendbird-webrtc-ios"
  1. Update the SendBirdCalls framework through Carthage.
Light Color Skin
Copy
$ carthage update
  1. Go to your Xcode project target’s General tab in the Frameworks and Libraries section. Then drag the built .framework binaries from the <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS folder into your application's Xcode project.

  2. Go to your Xcode project target’s Build Phases tab, click the + icon, and choose New Run Script Phase. Create a Run Script, specify your shell (ex: /bin/sh), and add /usr/local/bin/carthage copy-frameworks to the script below the shell.

  3. Add the following paths to the SendBirdCalls and WebRTC frameworks under Input Files.

Light Color Skin
Copy
$(SRCROOT)/Carthage/Build/iOS/SendBirdCalls.framework
$(SRCROOT)/Carthage/Build/iOS/WebRTC.framework

Note: Errors may occur if the size of the WebRTC.framework in the YOUR_PROJECT_DIRECTORY/Pods/SendBirdWebRTC folder is less than 800 MB. To fix these errors, refer to Troubleshooting in our GitHub repository.

Step 4 Request permission to access camera and microphone

Your users need to grant your app the permission to access camera and microphone on the device.

  1. Add NSMicrophoneUsageDescription key in your app’s Info.plist file to access microphone for audio call.

  2. Add NSCameraUsageDescription in your app’s Info.plist file to access camera for video call.

Step 5 Initialize with APP_ID

To integrate and run Sendbird Calls in your application, you need to initialize it first. Initialize the SendBirdCall instance by using the APP_ID of your Sendbird application, which can be found on the Sendbird Dashboard after creating an application. 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.

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.

Light Color Skin
Copy
// Initialize SendBirdCall instance to use APIs in your app.
SendBirdCall.configure(appId: APP_ID)

Step 6 Authenticate a user

To make and receive a 1-to-1 call or start a group call, authenticate a user to Sendbird server by using their user ID through the authenticate() method.

Light Color Skin
Copy
// The USER_ID below should be unique to your Sendbird application.
let params = AuthenticateParams(userId: USER_ID, accessToken: ACCESS_TOKEN)
SendBirdCall.authenticate(with: params) { (user, error) in
    guard let user = user, error == nil else {
        // Handle error.
    }

    // The user has been authenticated successfully and is connected to Sendbird server.
    ...
}

After authenticating a user, you can continue to either make a 1-to-1 call with Direct call or start a group call with Group call. Skip to Step 12 if you wish to start a group call.

Note: You can implement both the Chat and Calls SDKs to your app. Two SDKs 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 app by using the Chat SDK’s method or Chat API.


Make 1-to-1 call

Step 7 Add capabilities to your app

You can receive push notifications about an incoming 1-to-1 call with either VoIP notifications or remote notifications.

To receive notifications using VoIP notifications, add CallKit and PushKit. Then, go to your Xcode project’s Signing & Capabilities and enable Background Modes. Select the Voice over IP option under the list of available modes.

To receive notifications using remote notifications, go to your Xcode project’s Signing & Capabilities and enable Remote notifications.

Step 8 Add a device token

You can receive a 1-to-1 call by adding the user’s device token to the server. You can add the token for either VoIP notifications or remote notifications. Use the SendBirdCall.registerVoIPPush() method to add a device token for VoIP notifications. Use the SendBirdCall.registerRemotePush(token:completionHandler:) method if you wish to add a token with remote notifications.

Note: To learn more about the differences between the two types of notifications, go to Notifications.

Step 9 Add event delegates

Sendbird Calls provides SendBirdCallDelegate and DirectCallDelegate event delegates to handle events related to Direct call. The SendBirdCallDelegate is used to respond to device events such as incoming calls. The DirectCallDelegate is used to respond to call specific events such as call results.

  1. Add SendBirdCallDelegate by using the SendBirdCall.addDelegate(:) method.
Light Color Skin
Copy
SendBirdCall.addDelegate(self, identifier: UNIQUE_HANDLER_ID)

class MyClass: SendBirdCallDelegate {
    func didStartRinging(_ call: DirectCall) {
        // Process an incoming call.
        // IMPORTANT: - Refer to the Make a call and Receive a call sections below for what to do here.
        ...
    }
}
  1. Add DirectCallDelegate by using call.delegate.
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 10 Make a call

You are now ready to make your first 1-to-1 call. To make a call, pass the callee’s user ID as an argument to a parameter in the SendBirdCall.dial() method. To choose initial call configuration such as audio or video capabilities, video settings and mute settings, use the CallOption object.

Light Color Skin
Copy
let params = DialParams(calleeId: CALLEE_ID, callOptions: CallOptions())

let directCall = SendBirdCall.dial(with: params) { directCall, error in
    // The call was successfully made.
}

directCall.delegate = self

Step 11 Receive a call

You can accept or decline an incoming call. To accept an incoming call, use the directCall.accept() method. To decline the call, use the directCall.end() method. When you accept the call, a media session will automatically be established by the Calls SDK.

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 app receives an incoming call through either VoIP notifications or the remote notifications. In order to receive incoming calls to the callee’s app, the received notification must be delivered to the Calls SDK through the SendBirdCall instance.

To receive notifications using VoIP notifications, refer to the code below:

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

To receive notifications using remote notifications, refer to the code below:

Light Color Skin
Copy
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    SendBirdCall.application(application, didReceiveRemoteNotification: userInfo)
}

Start a group call

Step 12 Create a room

When creating your first room for a group call, you can choose either a room that supports up to 6 participants with video or a room that supports up to 25 participants with audio. When the room is created, a ROOM_ID is generated.

  1. Use the RoomType property to set the room type.

  2. Use the createRoom() method to create a room as shown below.

Light Color Skin
Copy
let roomType = RoomType.smallRoomForVideo
let params = RoomParams(roomType: roomType)
SendBirdCall.createRoom(with: params) { room, error in
    guard let room = room, error == nil else { return } // Handle error.
    // `room` is created with a unique identifier `room.roomId`.
}

List of properties

Property nameDescription

type

Type: RoomType
Specifies the type of the room. Valid values are limited to the following:
- smallRoomForVideo: type of a room that supports audio and video, can have up to 6 participants.
- largeRoomForAudioOnly: type of a room that only supports audio, can have up to 25 participants.

Step 13 Enter a room

You can now enter a room and start your first group call. When you enter a room, a participant is created with a unique participant ID to represent the user in the room.

To enter a room, you must acquire the room instance from Sendbird server with the room ID. To fetch the most up-to-date room instance from Sendbird server, use the SendBirdCall.fetchRoom(by:completionHandler:) method. Also, you can use the SendBirdCall.getCachedRoom(by:) method that returns the most recently cached room instance from Sendbird Calls SDK.

Light Color Skin
Copy
SendBirdCall.fetchRoom(by: ROOM_ID) { room, error in
    guard let room = room, error == nil else { return } // Handle error.
    // `room` with the identifier `ROOM_ID` is fetched from Sendbird Server.
}

let cachedRoom: Room? = SendBirdCall.getCachedRoom(by: ROOM_ID)
// Returns the most recently cached room from the SDK.
//If there is no such room with the given room ID, `nil` is returned.

Note: A user can enter the room using multiple devices or browser tabs. Entering from each device or browser tab will create a new participant.

Once the room is retrieved, call the enter(with:completionHandler:) method to enter the room.

Light Color Skin
Copy
let params = Room.EnterParams(isVideoEnabled: true, isAudioEnabled: true)
room.enter(with: params) { error in
    guard error == nil else { return } // Handle error.
    // User has successfully entered `room`.
}

Note: Share the room ID with other users for them to enter the room from the client app.