AgoraChatCallKit is an open-source audio and video UI library developed based on Agora's real-time communications and signaling services. With this library, you can implement audio and video calling functionalities with enhanced synchronization between multiple devices. In scenarios where a user ID is logged in to multiple devices, once the user deals with an incoming call that is ringing on one device, all the other devices stop ringing simultaneously.
This page describes how to implement real-time audio and video communications using the AgoraChatCallKit.
The basic process for implementing real-time audio and video communications with AgoraChatCallKit is as follows:
- Initialize AgoraChatCallKit by calling
initand add the
AgoraChatCallKitevent listener by calling
startInviteMultipleCallon the caller's client to send a call invitation for one-to-one or group calls.
- On the callee's client, accept or decline the call invitation after receiving
onReceivedCall. Once a user accepts the invitation, they enter the call.
- When the call ends, the SDK triggers the
Before proceeding, ensure that your development environment meets the following requirements:
- Java Development Kit 1.8 or later.
- Android Studio 3.5 or later.
- Gradle 4.6 or later.
- a Chat project that has integrated the Chat SDK and implemented the basic real-time chat functionalities, including users logging in and out and sending and receiving messages.
Take the following steps to integrate the AgoraChatCallKit into your project and set up the development environment.
Add the dependency
AgoraChatCallKit is developed upon
io.agora.rtc:chat-sdk:x.x.x(1.0.5 and later) and
io.agora.rtc:full-rtc-basic:x.x.x(3.6.2 and later). Follow the steps to add AgoraChatCallKit using Gradle.
/Gradle Scripts/build.gradle(Module: <projectname>.app), add the following lines to integrate the AgoraChatCallKit into your Android project:
Add project permissions
/app/Manifests/AndroidManifest.xml, add the following permissions after
Add the AgoraChatCallKit Activity
/app/Manifests/AndroidManifest.xml, add activities for the one-to-one audio and video call, and the group video call, for example,
This section introduces the core steps for implementing audio and video calls in your project.
init to initialize the AgoraChatCallKit after the Chat SDK is initialized. You can also add callback events to listen for and set the configurations. Refer to the following sample code:
In this method, you need to set the
EaseCallKitConfig class. Some of the configurations include the following:
From the caller's client, call
startInviteMultipleCall to send a call invitation for a one-to-one call or group call. You need to specify the call type when calling the method.
One-to-one audio and video call
startSingleCallto start a one-to-one call. You need to specify the call type as an audio call or video call in this method.
The following screenshot gives an example of the user interface after sending a call invitation for one-to-one audio call:
Group audio and video call
startInviteMultipleCallto start a group call. Set the call type as audio call or video call. You can set the users you want to invite from a chat group or the contact list. Refer to
ConferenceInviteActivityin the sample project for implementation.
Once a call invitaion is sent, the callee receives the invitation in the
If the callee is online and available for a call, you can pop out a user interface that allows the callee to accept or decline the invitation. Refer to the following screenshot to implement the interface:
In call sessions with multiple users, these users can also send call invitations to other users. After sending the invitation, the SDK triggers the
onInviteUsers callback in
EaseCallKitListener on the sender's client.
io.agora.chatdemo.group.fragments.MultiplyVideoSelectMemberChildFragment in the sample project for the user interface of the call invitation.
When a remote user joins the call, all the other users in the call receive the
onRemoteUserJoinChannel callback. You need to look up the Chat user ID corresponding to the Agora UID in you app server.
- If you find the Chat user ID, construct the user ID to an
EaseUserAccountobject and return it to the app using the
onRemoteUserJoinChannel. For the
- If you fail to find the Chat user ID, report the error code and descriptions using the
onSetUserAccountErrorcallback in the
A one-to-one call ends as soon as one of the two users hangs up, while a group call ends only after the local user hangs up. When the call ends, the SDK triggers the
This section contains extra steps you can take for the audio and video call functionalities in your project.
If exceptions or errors occur during a call, the SDK triggers the
onCallError callback in the
EaseCallKitListener class, which reports the detailed information of the exception in
Types of call errors are as follows:
After initializing the AgoraChatCallKit, you can refer to the following sample code to update the configuration of the call kit:
When changes to the UI or the channel state occur, for example, when a new user joins the channel,
onUserInfoUpdated is triggered to notify the app to update the UI.
After a user updates the user information, call
io.agora.chat.callkit.general.EaseCallKitConfig#setUserInfo to set the modified user information. Ensure that this method is implemented in a synchronous function so that the UI is updated timely.
To enhance communication security, Agora recommends that you authenticate app users with the Video SDK token before they join a call. To do this, you need to make sure that the Primary Certificate of your project is enabled, and
setEnableRTCToken in the AgoraChatCallKit is set to
Once you enable token authentication, the SDK triggers the
onGenerateRTCToken callback. You need to retrieve an Video SDK token in this callback following the steps:
- Retrieve the Video SDK token and Agora UID from your app server.
onSetTokento pass the token and UID to the callback object.
- AgoraChatCallKit uses the token and UID to join the channel.
Tokens are generated on your app server using the token generator provided by Agora. For how to generate a token on the server and retrieve and renew the token on the client, see Authenticate Your Users with Tokens.
In scenarios where the app runs on the background or goes offline, use push notifications to ensure that the callee receives the call invitation. To enable push notifications, see Set up push notifications.
Once push notifications are enabled, when a call invitation arrives, a notification message pops out on the notification panel. Users can click the message to see the call invitation.
This section provides other reference information that you can refer to when implementing real-time audio and video communications functionalities.
The AgoraChatCallKit provides the following APIs:
|setCallKitListener||Sets the event listener of the call kit.|
|startSingleCall||Starts a one-to-one call.|
|startInviteMultipleCall||Starts a group call.|
|getCallKitConfig||Retrieves the configurations of AgoraChatCallKit.|
|registerVideoCallClass||Registers a one-to-one video call class.|
|registerMultipleVideoClass||Registers a group video call class.|
EaseCallKitListener provides the following callback events:
|onEndCallWithReason||Occurs when the call ends.|
|onInviteUsers||Occurs when a member of the group call invites other users to the call.|
|onReceivedCall||Occurs when the call invitation is received and the device rings.|
|onGenerateToken||Requests the Video SDK token. You need to pass the token to AgoraChatCallKit with callbacks.|
|onCallError||Reports exceptions and errors during the call.|
|onInviteCallMessageSent||Occurs when the call invitation is sent.|
|onRemoteUserJoinChannel||Occurs when a remote user joins the call.|
|onUserInfoUpdated||Occurs when the user information is updated. This callback is triggered when changes occur to the UI or the channel state in the AgoraChatCallKit.|
EaseCallGetUserAccountCallback contains the following APIs:
|onUserAccount||Occurs when the Chat user ID correspondting to the Agora UID is retrieved.|
|onSetUserAccountError||Occurs when the app fails to retrieve the user account.|
EaseCallKitTokenCallback contains the following APIs:
|onSetToken||Occurs when the app passes the retrieved Video SDK token to the AgoraChatCallKit.|
|onGetTokenError||Occurs when the app fails to get the Video SDK token.|
Agora provides an open-source AgoraChat-android sample project on GitHub. You can download the sample to try it out or view the source code.
The sample project uses the Chat user ID to join a channel, which enables displaying the user ID in the view of the call. If you use the methods of the Agora Video SDK to start a call, you can also use the Integer UID to join a channel.