Peer-to-peer or Channel Messaging

You can use this guide to quickly start messaging with the Agora RTM Android SDK.

Try the demo

We provide an open-source demo project on GitHub, Agora-RTM-Tutorial-Android, which implements an elementary messaging system.

Prerequisites

• Android SDK API Level 16 or higher

• To run your app on Android 9, see Android Privacy Changes for more information.

• Android Studio 3.0 or later

• A valid Agora account. (Sign up for free)

Set up the development environment

We will walk you through the following steps in this section:

• Get an App ID
• Integrate the SDK into your project
• Add Android device permissions
• Prevent Obfuscation of the Agora Classes

Get an App ID

You can skip to Integrate the SDK into your project if you already have an App ID.

Integrate the SDK into your project

Choose either of the following methods to integrate the Agora RTM Android SDK into your project.

Method 1: Automatically integrate the SDK using JCenter

Add the following line in the /app/build.gradle file of your project (1.2.2 is the version number):

...
dependencies {
    ...
    implementation 'io.agora.rtm:rtm-sdk:1.2.2'
}

Method 2: Manually copy the SDK files

1. Download the latest version of the Agora RTM Android SDK and unzip.
2. Save the .jar package and .so files under the libs folder of the unzipped SDK package to the corresponding folders of your project.

File	Project Folder
agora-rtm_sdk.jar	~/app/libs/
/arm64-v8a/libagora-rtm-sdk-jni.so	~/app/src/main/jniLibs/arm64-v8a/
/armeabi-v7a/libagora-rtm-sdk-jni.so	~/app/src/main/jniLibs/armeabi-v7a/
/x86/libagora-rtm-jni.so	~/app/src/main/jniLibs/x86/
/x86_64/libagora-rtm-sdk-jni.so	~/app/src/main/jniLibs/x86_64/

Add project permissions

Add the following permissions in the /app/src/main/AndroidManifest.xml file for device access according to your needs:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="io.agora.rtmtutorial">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

...
</manifest>

Prevent code obfuscation

Add the following line in the app/proguard-rules.pro file to prevent code obfuscation:

-keep class io.agora.**{*;}

Implement peer-to-peer and channel messaging

This section provides API call sequence diagrams and sample codes related to peer-to-peer messaging and channel messaging.

API Call sequence diagrams

Login and logout of the Agora RTM system



Send or receive peer-to-peer messages



Join and leave an Agora RTM channel



Send or receive channel messages



Create and Initialize an Agora RTM Client

1. Put in the App ID you get from Console when creating and initializing an Agora RTM client.
2. Implement an event callback RtmClientListener, the SDK uses its callbacks to notify the app of ongoing events, including:
   • The connection between the SDK and the Agora RTM system changes.
   • A peer-to-peer message arrives.
   • Miscellaneous events.

import io.agora.rtm.ErrorInfo;
import io.agora.rtm.ResultCallback;
import io.agora.rtm.RtmChannel;
import io.agora.rtm.RtmChannelListener;
import io.agora.rtm.RtmChannelMember;
import io.agora.rtm.RtmClient;
import io.agora.rtm.RtmClientListener;
import io.agora.rtm.RtmMessage;
import io.agora.rtm.SendMessageOptions;

public void init() {
        try {
                mRtmClient = RtmClient.createInstance(mContext, APPID,
                                                new RtmClientListener() {
                        @Override
                        public void onConnectionStateChanged(int state, int reason) {
                                Log.d(TAG, "Connection state changes to "
                                        + state + " reason: " + reason);
                        }

                        @Override
                        public void onMessageReceived(RtmMessage rtmMessage, String peerId) {
                                String msg = rtmMessage.getText();
                                Log.d(TAG, "Message received " + " from " + peerId + msg 
                                                        );
                        }
                });
        } catch (Exception e) {
                Log.d(TAG, "RTM SDK initialization fatal error!");
                throw new RuntimeException("You need to check the RTM initialization process.");
        }
}

Log in and log out of the Agora RTM system

Only when you successfully log in the Agora RTM system, can you use most of the core features provided by the Agora RTM SDK. When logging in the Agora RTM system, you need to:

• Pass an RTM Token, which identifies a user and its privilege. If your development environment does not require high security, set token as null. You need to generate an RTM Token from your business server. For more information, see Token Security.
• An userId is the unique identifier of each user. You must not set it as empty, null, or "null".
• Pass a ResultCallback instance, which returns the onSuccess or onFailure callback.

mRtmClient.login(null, userId, new ResultCallback<Void>() {
        @Override
        public void onSuccess(Void responseInfo) {
                loginStatus = true;
                Log.d(TAG, "login success!");
        }
        @Override
        public void onFailure(ErrorInfo errorInfo) {
                loginStatus = false;
                Log.d(TAG, "login failure!");
        }
});

To log out of the system:

mRtmClient.logout(null);

Peer-to-peer messaging

Send an offline peer-to-peer message

You need to call the following method to send an peer-to-peer message to a specified user.

sendMessageToPeer(@NonNull String, @NonNull RtmMessage, @NonNull SendMessageOptions, @Nullable ResultCallback<void>)

You need to:

• Pass a user ID of the specified message receiver.
• Call the createMessage method to create an RtmMessageinstance and pass it to

public void sendPeerMessage(String dst, String content) {

        final RtmMessage message = mRtmClient.createMessage();
        message.setText(content);

        SendMessageOptions option = new SendMessageOptions();
        option.enableOfflineMessaging = true;

        mRtmClient.sendMessageToPeer(dst, message, option, new ResultCallback<Void>() {

            @Override
            public void onSuccess(Void aVoid) {

            }

            @Override
            public void onFailure(ErrorInfo errorInfo) {

            }
        });
    }

Receive a peer-to-peer message

You can use the RtmClientListener instance that you passed in when creating an RtmClient instance to listen for events that a peer-to-peer message is received. The onMessageReceived(RtmMessage message, String peerId) callback of the listener takes an RtmMessage instance with it.

• You can use the message.getText() method to get the text content of the message.
• peerId refers to the user ID of the message sender.

The received RtmMessage object cannot be reused.

Channel messaging

Ensure that you have logged in the Agora RTM system before being able to use the channel messaging function.

Create and join a channel

When creating an RtmChannel, you need to pass a channel ID, a string that must not be empty, null, "null", or exceed 64 Bytes in length. You also need to specify a channel listener:

private RtmChannelListener mRtmChannelListener = new RtmChannelListener() {
    @Override
    public void onMessageReceived(RtmMessage message, RtmChannelMember fromMember) {
        String text = message.getText();
        String fromUser = fromMember.getUserId();
    }

    @Override
    public void onMemberJoined(RtmChannelMember member) {

    }

    @Override
    public void onMemberLeft(RtmChannelMember member) {

    }
};

try {
        mRtmChannel = mRtmClient.createChannel("demoChannelId", mRtmChannelListener);
} catch (RuntimeException e) {
        Log.e(TAG, "Fails to create channel. Maybe the channel ID is invalid," +
                        " or already in use. See the API Reference for more information.");
}

        mRtmChannel.join(new ResultCallback<Void>() {
                @Override
                public void onSuccess(Void responseInfo) {
                        Log.d(TAG, "Successfully joins the channel!");
                }

                @Override
                public void onFailure(ErrorInfo errorInfo) {
                        Log.d(TAG, "join channel failure! errorCode = "
                                                                + errorInfo.getErrorCode());
                }
        });

Channel messaging

After successfully joining a channel, you can send messages to the channel. As we mentioned in the previous section, you need to set a channel listener for events such as a channel message is received.

When calling a sendChannelMessage()message method to send channel messages, you need to:

• Pass an RtmMessage object. You need to use the createMessage() method of the RtmClient class to create an RtmMessage object and use the setText() method to set the message content.
• When sending a channel message, pass a ResultCallback instance.

public void sendChannelMessage(String msg) {
        RtmMessage message = mRtmClient.createMessage();
        message.setText(msg);

        mRtmChannel.sendMessage(message, new ResultCallback<Void>() {
                @Override
                public void onSuccess(Void aVoid) {
                }

                @Override
                public void onFailure(ErrorInfo errorInfo) {
                }
        });
}

Leave a channel

You can call the leave() method to leave a channel.

Considerations

• The Agora RTM SDK supports creating multiple RtmClient instances that are independent of each other.

• To send and receive peer-to-peer or channel messages, ensure that you have successfully logged in the Agora RTM system (i.e., ensure that you have received onSuccess).

• To use any of the channel features, you must first call the createChannel method to create a channel instance.

• You can create multiple channel instances for each RtmClient instance, but you can only join a maximum of 20 channels at the same time. The channelId parameter needs to be channel-specific.

• When you leave a channel and do not want to join it again, you can call the release method to release all resources used by the channel instance.

• You cannot reuse a received RtmMessage instance.