1. Introduction
2. Before getting started
3. Getting started
4. Making your first call
5. Implementation guide
6. Appendix

Sendbird Calls is the latest addition to our product portfolio. It enables real-time calls between users within a Sendbird application. SDKs are provided for iOS, Android, and JavaScript. Using Sendbird SDK helps developers to quickly integrate voice and video call functions into their client apps. This allows users to make and receive web-based real-time voice and video calls on Sendbird platform.

If you need any help in resolving any issues or have questions, please visit our community

Sendbird Calls SDK for Android provides a framework to make and receive voice and video calls. Direct calls in the SDK refers to one-to-one calls. To make a direct voice or video call, the caller specifies the user ID of the intended callee, and dials. Upon dialing, all of the callee’s authenticated devices will receive notifications for an incoming call. The callee then can choose to accept the call from any one of the devices. When the call is accepted, a connection is established between the devices of the caller and the callee. This marks the start of a direct call. Call participants can mute themselves, or call with either or both of the audio and video by using output devices such as speaker and microphone for audio, and front, rear camera for video. A call may be ended by either party. The Sendbird Dashboard displays call logs in the Calls menu for dashboard owners and admins to review.

Find out more about Sendbird Calls for Android on Calls SDK for Android doc.

This section shows the prerequisites you need to check to use Sendbird Calls SDK for Android.

The minimum requirements for Calls SDK for Android are:

• Android 4.1 (API level 16) or later
• Java 8 or later

// build.gradle(app)
android {
    defaultConfig {
        minSdkVersion 16
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

This section gives you information you need to get started with Sendbird Calls SDK for Android.

Download and install the SDK using Gradle.

allprojects {
	repositories {
		...
		maven { url "https://repo.sendbird.com/public/maven" }
	}
}

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

dependencies {
    implementation 'com.sendbird.sdk:sendbird-calls:1.11.14'
}

Note: Calls 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.

The SDK requires system permissions. The following permissions allow the SDK to access the microphone and use audio, as shown here:

<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.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

When launching the client app for the first time, users are required to grant runtime permissions.

For a device with Android 6.0 or higher, CAMERA, RECORD_AUDIO permissions are required. For a client app with targetSdkVersion with Android 12 or higher, BLUETOOTH_CONNECT permission is required.

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

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

# SendBird Calls SDK
-keep class com.sendbird.calls.** { *; }
-keep class org.webrtc.** { *; }
-dontwarn org.webrtc.**
-keepattributes InnerClasses

Follow the step-by-step instructions below to authenticate and make your first call.

As shown below, the SendBirdCall instance must be initiated when a client app is launched. Initialize the SendBirdCall instance with the APP_ID of the Sendbird application you would like to use to make a call.

SendBirdCall.init(getApplicationContext(), APP_ID);

Note: If another initialization with another APP_ID takes place, all existing data will be deleted and the SendBirdCall instance will be initialized with the new APP_ID.

In order to make and receive calls, users must first be authenticated on Sendbird server using the SendBirdCall.authenticate() method. To receive calls while an app is either in the background or closed entirely, a device registration token must be registered. A push token may be registered during authentication as a parameter in the authenticate() method, or after authentication as a parameter in the SendBirdCall.registerPushtokensToken() method.

For more details on registering a push token, refer to Push notifications for Android.

// Authentication
AuthenticateParams params = new AuthenticateParams(USER_ID)
        .setAccessToken(ACCESS_TOKEN)
        .setPushToken(PUSH_TOKEN, isUnique);

SendBirdCall.authenticate(params, new AuthenticateHandler() {
    @Override
    public void onResult(User user, SendBirdException e) {
        if (e == null) {
            // The user is authenticated successfully.
        }
    }
});

// Update push token
public class MyFirebaseMessagingService extends FirebaseMessagingService {
    ...
    @Override
    public void onNewToken(@NonNull String token) {
        SendBirdCall.registerPushToken(token, isUnique, new CompletionHandler() {
            @Override
            public void onResult(SendBirdException e) {
                if (e == null) {
                    // The push token has been registered successfully.
                }
            }
        });
    }
    ...
}

There are two types of event handlers the SDK provides for a client app to respond to various events: SendBirdCallListener and DirectCallListener.

Register a device-specific SendBirdCallListener event handler using the SendBirdCall.addListener() method. It is recommended to add the event handler during initialization because it is a prerequisite for detecting onRinging() event. The code below shows the way device-wide events such as incoming calls are handled once SendBirdCallListener is added.

SendBirdCall.addListener(UNIQUE_HANDLER_ID, new SendBirdCallListener() {
    @Override
    public void onRinging(DirectCall call) {
    }
});

SendBirdCallListener is removed upon terminating the app.

UNIQUE_HANDLER_ID is any unique string value such as UUID.

Register a call-specific DirectCallListener event handler using the DirectCall.addCallListener() method. Responding to call-specific events, such as establishing a sucessfull call connection, is then handled as shown below:

directCall.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) {}

    @Override
    public void onRemoteVideoSettingsChanged(DirectCall call) {}

    @Override
    public void onCustomItemsUpdated(DirectCall call, List<String> updatedKeys) {}

    @Override
    public void onCustomItemsDeleted(DirectCall call, List<String> deletedKeys) {}

    @Override
    public void onReconnecting(DirectCall call) {}

    @Override
    public void onReconnected(DirectCall call) {}

    @Override
    public void onAudioDeviceChanged(DirectCall call, AudioDevice currentAudioDevice, Set<AudioDevice> availableAudioDevices) {}

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

First, prepare the DialParams call parameter object to initiate a call. The parameter contains the intended callee’s user id and the CallOptions object. The CallOptions is used to set the call’s initial configuration, such as mute or unmute. Once prepared, the DialParams object is then passed into the SendBirdCall.dial() method to start making a call.

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) {
    }
});

Register SendBirdCallListner first to receive incoming calls. Accept or decline incoming calls by using the directCall.accept() or the directCall.end() methods. If the call is accepted, a media session will automatically be established.

Before accepting any calls, the directCall.setListener() must be registered in the SendBirdCallListener. Once registered, directCall.setListener() enables reacting to in-call events through callback methods.

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());
    }
});

First, prepare the DialParams call parameter object to initiate a call. The parameter contains the intended callee’s user id and the CallOptions object. The CallOptions is used to set the call’s initial configuration, such as mute or unmute. Once prepared, the DialParams object is then passed into the SendBirdCall.dial() method to start making a call.

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) {
    }
});

Register SendBirdCallListner first to receive incoming calls. Accept or decline incoming calls by using the directCall.accept() or the directCall.end() methods. If the call is accepted, a media session will automatically be established.

Before accepting any calls, the directCall.setListener() must be registered in the SendBirdCallListener. Once registered, directCall.setListener() enables reacting to in-call events through callbacks methods.

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());
    }
});

When the app is in the foreground, incoming call events are received through the SDK’s persistent internal server connection. However, when the app is closed or in the background, incoming calls are received through the Firebase Cloud Messaging’s (FCM) push notifications. The FCM messages received by SendBirdCall must be delivered to the SDK through the SendBirdCall.handleFirebaseMessageData() method.

public class MyFirebaseMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        if (SendBirdCall.handleFirebaseMessageData(remoteMessage.getData())) {
        } else {
            // Handle non-SendBirdCall Firebase messages.
        }
    }
}

During an ongoing call, a caller may mute or unmute their microphone by using the directCall.muteMicrophone() or directCall.unmuteMicrophone() methods. If the callee changes their audio settings, the caller is notified through the DirectCallListener.onRemoteAudioSettingsChanged() listener. The caller may start or stop video by using the directCall.startVideo() or directCall.stopVideo() methods.

If the callee changes their video settings, the caller is notified through the DirectCallListener.onRemoteVideoSettingsChanged() listener. Switching between the front and the back cameras is done using the directCall.switchCamera(CompletionHandler).

// mutes my microphone
directCall.muteMicrophone();

// unmutes my microphone
directCall.unmuteMicrophone();

// starts to show video
directCall.startVideo();

// stops showing video
directCall.stopVideo();

// switches camera
directCall.switchCamera(new CompletionHandler() {
    @Override
    public void onResult(SendBirdException e) {
        if (e != null) {
            Log.e(TAG, "switchCamera(e: " + e.getMessage() + ")");
        }
    }
});

// receives the event
directCall.setListener(new DirectCallListener() {
    ...
    @Override
    public void onRemoteAudioSettingsChanged(DirectCall call) {
        if (call.isRemoteAudioEnabled()) {
            // The peer has been unmuted.
            // Consider displaying an unmuted icon.
        } else {
            // The peer has been muted.
            // Consider displaying and toggling a muted icon.
        }
    }

    @Override
    public void onRemoteVideoSettingsChanged(DirectCall call) {
        if (call.isRemoteVideoEnabled()) {
            // The peer has started video.
        } else {
            // The peer has stopped video.
        }
    }
    ...
});

A caller may end a call using the directCall.end() method. The event can then be processed through the DirectCallListener.onEnded() listener. This listener is also triggered if the callee ends the call.

// End a call
directCall.end();

// Receives the event
directCall.setListener(new DirectCallListener() {
    ...
    
    @Override
    public void onEnded(DirectCall call) {
        // Consider releasing or destroying call-related views from here.
    }
    ...
    
});

Calls SDK for Android automatically mirrors SendBirdVideoView when the current camera is front-facing for a user’s local video view. By using the code below, you can manually set the current user’s local video view as mirrored or reversed when the camera is facing the user.

SendBirdVideoView videoView;
videoView.setMirror(true);  // or false

User information of a local or remote user can be accessed by using the directCall.getLocalUser() and directCall.getRemoteUser() methods.

Sendbird server automatically stores details of calls, which can later be used to display a call history for users. A user’s call history can be retrieved by using the DirectCallLogListQuery.next() method.

DirectCallLogListQuery.Params params = new DirectCallLogListQuery.Params();
DirectCallLogListQuery query = SendBirdCall.createDirectCallLogListQuery(params);

query.next(new DirectCallLogListQueryResultHandler() {
    @Override
    public void onResult(List<DirectCallLog> callLogs, SendBirdException e) {
        if (e == null) {
            if (query.hasNext() && !query.isLoading()) {
                // query.next() can be called once more.
                // If a user wants to fetch more call logs.
            }
        }
    }
});

The following table lists a set of methods of the SendBirdCall class.

Information relating the end result of a call can be obtained at any time through the directCall.getEndResult() method, best invoked within the onEnded() callback.

As shown below, there are two types of ThreadOption in the SendbirdCall SDK: UI_THREAD and HANDLER. If ThreadOption is set to UI_THREAD, every callback will be called on the UI thread, and vice versa. UI_THREAD is set by default.

SendBirdCall.Options.setThreadOption(SendBirdCall.Options.ThreadOption.UI_THREAD, null);

Handler myHandler = new Handler();
SendBirdCall.Options.setThreadOption(SendBirdCall.Options.ThreadOption.HANDLER, myHandler);

Sendbird Calls is based on WebRTC to enable real-time calls between users with P2P connections, but sometimes connectivity issues may occur for users due to network policies that won’t allow WebRTC communications through Firewalls and NATs (Network Address Translators). For this, Sendbird Calls uses two different types of protocols, Session Traversal Utilities for NAT (STUN) and Traversal Using Relays around NAT (TURN). STUN and TURN are protocols that support establishing a connection between users.

Note: See our GitHub page to learn about the requirements and how to use the Calls SDKs behind a firewall.

Session Traversal Utilities for NAT (STUN) is a protocol that helps hosts to discover the presence of a NAT and the IP address, which eventually makes the connection between two endpoints. Traversal Using Relays around NAT (TURN) is a protocol that serves as a relay extension for data between two parties.

Sendbird Calls first try to make a P2P connection directly using the Calls SDK. If a user is behind a NAT/Firewall, Calls will discover the host's public IP address as a location to establish connection using STUN. In most cases, STUN server is only used during the connection setup and once the session has been established, media will flow directly between two users. If the NAT/Firewall still won't allow the two users to connect directly, TURN server will be used to make a connection to relay the media data between two users. Most of the WebRTC traffic is connected with STUN.