Home
/
Calls
/
Android

Make your first call

Sendbird Calls for Android 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 Android 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 Kotlin or Java.


Requirements

The minimum requirements for Calls SDK for Android are:

  • Android 4.1 (API level 16) or higher
  • Java 8 or higher
  • Gradle 3.4.0 or higher

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 Android.

Step 1 Create a project

To get started, open Android Studio and create a new project for Calls in the Project window as follows:

  1. Click Start a new Android Studio project in the Welcome to Android Studio window.

  2. Select Empty Activity and click Next.

  3. Enter your project name in the Name field.

  4. Select your language as either Java or Kotlin from the Language drop-down menu.

  5. Select minimum API level as 16 or higher.

Step 2 Install using Gradle

You can install Calls for Android through Gradle. Begin by opening the root build.gradle file and add the code blocks below:

build.gradle
Light Color Skin
Copy
allprojects {
    repositories {
        ...
        maven { url "https://repo.sendbird.com/public/maven" }
    }
}

Note: Make sure the above code block isn't added to your module build.gradle file.

Then, add the dependency to your module build.gradle file.

build.gradle
Light Color Skin
Copy
dependencies {
    implementation 'com.sendbird.sdk:sendbird-calls:1.7.0'
}

Note: Call SDK versions 1.5.3 or lower can be downloaded from JCenter until February 1, 2022. SDK versions higher than 1.5.3 will be available on Sendbird's remote repository.

Step 3 Request to access system permissions

The Calls SDK requires system permissions. To allow the Calls SDK to record audio and discover bluetooth devices, add the following lines to the AndroidManifest.xml file.

AndroidManifest.xml
Light Color Skin
Copy
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The CAMERA and RECORD_AUDIO permissions are considered as dangerous permissions and require user agreement when your app is first launched on a user’s device with Android 6.0 or higher.

Note: For more information about requesting app permissions, see the Android’s Request app permissions guide.

Step 4 (Optional)   Configure ProGuard to shrink code and resources

When you build your APK with minifyEnabled true, add the following line to the module's ProGuard rules file.

Light Color Skin
Copy
# Sendbird Calls SDK
-keep class com.sendbird.calls.** { *; }
-keep class org.webrtc.** { *; }
-dontwarn org.webrtc.**
-keepattributes InnerClasses

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.init(getApplicationContext(), APP_ID);

Note: The SendBirdCall.init() method must be called at least once in your Android client app. It is recommended to initialize the Calls SDK in the onCreate() method of the Application instance.

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.
AuthenticateParams params = new AuthenticateParams(USER_ID)
    .setAccessToken(ACCESS_TOKEN);

SendBirdCall.authenticate(params, new AuthenticateHandler() {
    @Override
    public void onResult(User user, SendBirdException e) {
        if (e == null) {
            // 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 11 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 a 1-to-1 call

Step 7 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 by using the SendBirdCall.registerPushToken() method.

Light Color Skin
Copy
SendBirdCall.registerPushToken(PUSH_TOKEN, true, new CompletionHandler() {
    @Override
    public void onResult(@Nullable SendBirdException e) {
        if (e == null) {
            // The push token is registered successfully.
        }
    }
});

Step 8 Add an event handler

You can add a device-specific SendBirdCallListener event handler using the SendBirdCall.addSendBirdCallListener() method. Once the event handler is added, responding to device events such as incoming calls can be managed as shown below:

Light Color Skin
Copy
SendBirdCall.addListener(UNIQUE_HANDLER_ID, new SendBirdCallListener() {
    @Override
    public void onRinging(DirectCall call) {
        ...

    }
});

Note: If a SendBirdCallListener event handler isn’t registered, a user can't receive an onRinging callback event. Thus, this handler should be added at the initialization of the app. Also, a SendBirdCallListener event handler is automatically removed when the app closes by default.

Step 9 Make a call

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

Light Color Skin
Copy
DialParams params = new DialParams(CALLEE_ID);
params.setVideoCall(true);
params.setCallOptions(new CallOptions());

DirectCall call = SendBirdCall.dial(params, new DialHandler() {
    @Override
    public void onResult(DirectCall call, SendBirdException e) {
        if (e == null) {
            // The call has been created successfully.
        }
    }
});

call.setListener(new DirectCallListener() {
    @Override
    public void onEstablished(DirectCall call) {
    }

    @Override
    public void onConnected(DirectCall call) {
    }

    @Override
    public void onEnded(DirectCall call) {
    }
});

Step 10 Receive a call

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

Light Color Skin
Copy
SendBirdCall.addListener(UNIQUE_HANDLER_ID, new SendBirdCallListener() {
    @Override
    public void onRinging(DirectCall call) {
        call.setListener(new DirectCallListener() {
            @Override
            public void onEstablished(DirectCall call) {
            }

            @Override
            public void onConnected(DirectCall call) {
            }

            @Override
            public void onEnded(DirectCall call) {
            }

            @Override
            public void onRemoteAudioSettingsChanged(DirectCall call) {
            }
        });

        call.accept(new AcceptParams());
    }
});

Start a group call

Step 11 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
val params = RoomParams(RoomType.SMALL_ROOM_FOR_VIDEO)
SendBirdCall.createRoom(params, object : RoomHandler {
    override fun onResult(room: Room?, e: SendBirdException?) {
         if (room == null || e != null) {
              // Handle error.
              return
         }

         // `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:
- SMALL_ROOM_FOR_VIDEO: type of a room that supports audio and video, can have up to 6 participants.
- LARGE_ROOM_FOR_AUDIO_ONLY: type of a room that only supports audio and can have up to 25 participants.

Step 12 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.fetchRoomById() method. Also, you can use the SendBirdCall.getCachedRoomById() method that returns the most recently cached room instance from Sendbird Calls SDK.

Light Color Skin
Copy
SendBirdCall.fetchRoomById(ROOM_ID, object : RoomHandler {
    override fun onResult(room: Room?, e: SendBirdException?) {
         if (room == null || e != null) {
              // Handle error.
              return
         }

         // `room` with the identifier `ROOM_ID` is fetched from Sendbird Server.
    }
})

val room = SendBirdCall.getCachedRoomById(ROOM_ID)
// Returns the most recently cached room with the identifier `ROOM_ID` from the SDK.
// If there is no such room with the given room ID, `null` 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() method to enter the room.

Light Color Skin
Copy
room.enter(params, object : CompletionHandler {
    override fun onResult(e: SendBirdException?) {
        if (e != null) {
            // 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.