Unity

The Signaling SDK API reference is divided into the following sections:

• Setup
• Channels
• Topics
• Messages
• Presence
• Storage
• Lock
• Enumerated types
• Troubleshooting

Setup

The API reference for the Signaling SDK documents interface descriptions, methods, basic usage, and return values of the Signaling APIs.

Before initializing the Signaling client instance, you need to import the Signaling SDK as follows:

1. Download the latest Signaling Unity SDK.
2. In Unity, click Assets > Import Package > Custom Package to import the SDK.
3. In your script file, add the following to the list of namespace declarations:

  using Agora.Rtm;

CreateAgoraRtmClient

Description

Create and initialize the Signaling client instance. You need to provide appId and userId parameters, and you can get the App ID when you create an Agora project in the Agora Console.

Method

Call the CreateAgoraRtmClient method as follows:

IRtmClient CreateAgoraRtmClient(RtmConfig config);

Basic usage

RtmConfig config = new RtmConfig();
// get the appId from your Agora console
config.appId = "my_appId";
// user ID to be used as a device identifier
config.userId ="Tony";
// set Presence Timeout
config.presenceTimeout = 30;
// it is recommended to use the Try-catch pattern to catch initialization errors
try
{
    rtmClient = RtmClient.CreateAgoraRtmClient(config);
}
catch (RTMException e)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode : {1}, due to: {2}", e.Status.Operation , e.Status.ErrorCode , e.Status.Reason));
}

Return value

The SDK returns the IRtmClient instance，for subsequent calls of other Signaling APIs.

RtmConfig

Description

Use the RtmConfig instance to set the configuration parameters of the Signaling client. These configuration parameters take effect throughout the lifecycle of the Signaling client and affect the behavior of the Signaling client.

Method

Create the RtmConfig instance as follows:

new RtmConfig()

RtmLogConfig

Use the RtmLogConfig instance to configure and store local log files named agora.log. During the debugging phase, you can greatly improve efficiency by storing and tracking the running status of the app through logs. If you encounter complex problems and need Agora technical support to assist with the investigation, you need to provide the log information. The RtmLogConfig data type contains the following properties:

RtmProxyConfig

Use the RtmProxyConfig instance to set properties related to the client Proxy service. In some restricted network environments, you might need to use this feature.

The RtmProxyConfig data type contains the following properties:

RtmEncryptionConfig

Use the RtmEncryptionConfig instance to set the properties required for the client-side encryption. After successfully setting encryption modes, encryption keys, and other related properties, the SDK automatically encrypts and decrypts all messages sent or all statuses set by the user on the client side.

The RtmEncryptionConfig data type contains the following properties:

Basic usage

// Create an RtmConfig instance
RtmConfig config = new RtmConfig();
// get the appId from your Agora console
config.appId = "my_appId";
// user ID to be used as a device identifier
config.userId ="Tony";
// set Presence Timeout
config.presenceTimeout = 30;

// Create a LogConfig instance.
LogConfig logConfig = new LogConfig()
// set log file path.
logConfig.filePath = "./logfile/";
// set agore.log file size.
logConfig.fileSizeInKB = 512;
// set log report level.
logConfig.level = LOG_LEVEL.INFO;
// initialize logconfig
config.logConfig = logConfig;

// Create an RtmProxyConfig instance.
RtmProxyConfig proxyConfig = new RtmProxyConfig()
// set proxy type as HTTP.
proxyConfig.proxyType = RTM_PROXY_TYPE.HTTP;
// set your Proxy Server address.
proxyConfig.server = "192.168.11.101";
// set your listener port.
proxyConfig.port = 8080;
// set your proxy account
proxyConfig.account = "Tony";
// set your proxy password
proxyConfig.password = "my_password"
// initialize proxyConfig
config.proxy = proxyConfig;

// Create an RtmEncryptionConfig instance.
RtmEncryptionConfig encryptionConfig = new RtmEncryptionConfig()
// set encryption Mode as RTM_ENCRYPTION_MODE_AES_128_GCM.
encryptionConfig.encryptionMode = RTM_ENCRYPTION_MODE.AES_128_GCM;
// set your cipherKey, you must keep your cipherKey safety.
encryptionConfig.encryptionKey = "your_cerpherKey";
// set your Salt.
encryptionConfig.encryptionKdfSalt = "yourSalt";
// when you set the config.encryptionConfig  parameter. the end-to-end encryption will be turned on automatically
config.encryptionConfig = encryptionConfig;

// it is recommended to use the Try-catch pattern to catch initialization errors
try
{
    rtmClient = RtmClient.CreateAgoraRtmClient(config);
}
catch (RTMException e)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode : {1}, due to: {2}", e.Status.Operation , e.Status.ErrorCode , e.Status.Reason));
}

Return value

The SDK returns the RtmConfig instance.

Event Listeners

Description

IRtmClient Signaling client instance

Signaling has a total of 7 types of event notifications, as shown in the following table:

Add event listeners

You can add event listeners as follows:

// add message event listener
rtmClient.OnMessageEvent += ( MessageEvent event ) =>
{
    var channelName = event.channelName;
    var channelType = event.channelType;
    var topic = event.channelTopic;
    var publisher = event.publiser;
    var messageType = event.messageType;
    var message = event.message;
    var customType = event.customType;
    Debug.Log(string.Format("Received Message {0} from userId:{1} at channel:{2} with channel type of {3}. ", message, publisher , channelName, channelType));
    if (message != null)
    {
        // your logic
    }
};

// add presence event listener
rtmClient.OnPresenceEvent += ( PresenceEvent event ) =>
{
    var channelName = event.channelName;
    var channelType = event.channelType;
    var eventType = event.type;
    var publisher = event.publiser;
    var stateItems = event.stateItems;
    var interval = event.interval;
    var snapshot = event.snapshot;
    Debug.Log(string.Format("Received presence Event {0} from userId:{1} at channel:{2} with channel type of {3}. ", eventType, publisher , channelName, channelType));
}

// add topic event listener
rtmClient.OnTopicEvent += ( TopicEvent event ) =>
{
    var channelName = event.channelName;
    var eventType = event.type;
    var publisher = event.publisher;
    var topicInfos = event.topicInfos;
    Debug.Log(string.Format("Received topic event {0} from userId:{1} at channel:{2} with channel type of {3}. ", eventType, publisher , channelName, channelType));
    if (topicInfos != null)
    {
        // your logic
    }
}

// add storage event listener
rtmClient.OnStorageEvent += ( StorageEvent event ) =>
{
    var channelName = event.channelName;
    var channelType = event.channelType;
    var eventType = event.eventType;
    var category = event.target;
    var data = event.data;
    Debug.Log(string.Format("Received storage event {0} at channel:{1} with channel type of {2}. ", category , channelName, channelType));
    if (data != null)
    {
        // your logic
    }
}

// add lock event listener
rtmClient.OnLockEvent += ( LockEvent event ) =>
{
    var channelName = event.channelName;
    var channelType = event.channelType;
    var eventType = event.type;
    var LockDetail = event.lockDetailList;
    Debug.Log(string.Format("Received lock event {0} at channel:{2} with channel type of {3}. ", eventType, publisher , channelName, channelType));
    if( LockDetail != null )
    {
        // your logic
    }
}

// add OnConnectionStateChanged event listener
rtmClient.OnConnectionStateChanged += ( string channelName, RTM_CONNECTION_STATE state, RTM_CONNECTION_CHANGE_REASON reason ) =>
{
    Debug.Log(string.Format("OnConnectionStateChanged channelName {0}: state:{1} reason:{2}", channelName, state, reason);
}

// add OnTokenPrivilegeWillExpire event listener
rtmClient.OnTokenPrivilegeWillExpire += ( string channelName ) =>
{
    Debug.Log(string.Format("OnTokenPrivilegeWillExpire channelName {0}", channelName));
}

Message event. MessageEvent contains the following properties:

PresenceEvent

User presence event. PresenceEvent contains the following properties:

IntervalInfo contains the following properties:

SnapshotInfo contains the following properties:

TopicEvent

Topic event.TopicEvent contains the following properties:

TopicInfo data type contains the following properties:

PublisherInfo[] data type contains the following properties:

StorageEvent

Storage event.StorageEvent contains the following properties:

LockEvent

Lock event. LockEvent contains the following properties:

The LockDetail data type contains the following properties:

Remove event listeners

If you no longer need to use event notifications, to avoid memory leaks, errors or anomalies, Agora recommends removing event listeners.

private void AddEventsListener()
{
    rtmClient.OnMessageEvent += OnMessageEvent;
    rtmClient.OnPresenceEvent += OnPresenceEvent;
    rtmClient.OnTopicEvent += OnTopicEvent;
    rtmClient.OnStorageEvent += OnStorageEvent;
    rtmClient.OnLockEvent += OnLockEvent;
    rtmClient.OnConnectionStateChanged += OnConnectionStateChanged;
    rtmClient.OnTokenPrivilegeWillExpire += OnTokenPrivilegeWillExpire;
}

private void RemoveEventsListener()
{
    rtmClient.OnMessageEvent -= OnMessageEvent;
    rtmClient.OnPresenceEvent -= OnPresenceEvent;
    rtmClient.OnTopicEvent -= OnTopicEvent;
    rtmClient.OnStorageEvent -= OnStorageEvent;
    rtmClient.OnLockEvent -= OnLockEvent;
    rtmClient.OnConnectionStateChanged -= OnConnectionStateChanged;
    rtmClient.OnTokenPrivilegeWillExpire -= OnTokenPrivilegeWillExpire;
}

private void OnMessageEvent( MessageEvent Event)
{
    // your logic
 };

private void OnPresenceEvent( PresenceEvent Event)
{
    // your logic
};

private void OnTopicEvent( TopicEvent Event)
{
    // your logic
};

...

LoginAsync

Description

After creating and initializing the Signaling instance, you need to perform the LoginAsync operation to log in to the Signaling service. After successful login, the client establishes a long connection with the Signaling server, and then the SDK allows the client to access Signaling resources.

Method

You can log in to the Signaling system as follows:

RtmResult<LoginResult> LoginAsync(string token);

Basic usage

var ( status,response ) = await rtmClient.LoginAsync(token);
if (status.Error)
{
   Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation , status.ErrorCode , status.Reason));
}
else
{
   Debug.Log("Login Successfully")
}

Return value

This operation returns the RtmResult<LoginResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

LogoutAsync

Description

When you no longer need to operate, you can log out of the system. This operation affects the PCU item in your billing data.

Method

You can log out as follows:

RtmResult<LogoutResult> LogoutAsync();

Basic usage

var (status,response) = await rtmClient.LogoutAsync();

Return value

This operation returns the RtmStatus data type, including the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

ReleaseLockAsync

Description

Once you no longer need the Signaling service, it is best to destroy the IRtmClient instance. Doing so protects you from the performance degradation caused by memory leaks, errors, and exceptions.

Method

You can destroy the IRtmClient instance as follows:

RtmStatus Dispose();

Basic usage

var status = Dispose();

Return value

This operation returns the RtmStatus data type, including the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

Channels

Signaling provides a highly efficient channel management mechanism for data transmission. Any user who subscribes or joins a channel can receive messages and events transmitted within 100 milliseconds. Signaling allows clients to subscribe to hundreds or even thousands of channels. Most Signaling APIs perform actions such as sending, receiving, and encrypting based on channels.

Based on capabilities of Agora, Signaling channels are divided into two types to match different application use-cases:

• Message Channel: Follows the industry-standard Pub/Sub (publish/subscribe) mode. You can send and receive messages within the channel by subscribing to a channel, and do not need to create the channel in advance. There is no limit to the number of publishers and subscribers in a channel.
• Stream Channel: Follows a concept similar to the observer pattern in the industry, where users need to create and join a channel before sending and receiving messages. You can create different topics in the channel, and messages are organized and managed through topics.

IRtmClient Signaling client instance

SubscribeTopicAsync

Description

Signaling provides event notification capabilities for messages and states. By listening for callbacks, you can receive messages and events within subscribed channels. For information on how to add and set event listeners, see Event Listeners.

By calling the SubscribeTopicAsync method, the client can subscribe to a message channel and start receiving messages and event notifications within the channel. After successfully calling this method, users who subscribe to the channel and enable the presence event listener can receive a REMOTE_JOIN type of the OnPresenceEvent event. See Event Listeners.

Method

You can call the SubscribeTopicAsync method as follows:

RtmResult<SubscribeResult> SubscribeAsync(string channelName, SubscribeOptions options);

SubscribeOptions contains the following properties:

Basic usage

var options = new SubscribeOptions();
options.withMessage = true;
options.withPresence = true;
var (status,response) = await rtmClient.SubscribeAsync("Chat_room", options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode:{1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("Subscribe channel success! at Channel:{0}", response.ChannelName));
}

Return value

The SubscribeTopicAsync operation returns a RtmResult<SubscribeTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The SubscribeTopicResult data type contains the following properties:

UnsubscribeTopicAsync

Description

If you no longer need to subscribe to a channel, you can call the UnsubscribeTopicAsync method to unsubscribe from the channel. After successfully calling this method, users who subscribe to the channel and enable event listeners can receive the REMOTE_LEAVE type of the OnPresenceEvent event notification. See Event Listeners.

Method

You can call the UnsubscribeTopicAsync method as follows:

RtmResult<UnsubscribeResult> UnsubscribeAsync(string channelName);

Basic usage

var (status,response) = await rtmClient.UnsubscribeAsync(channelName);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}

Return value

The UnsubscribeTopicAsync operation returns a RtmResult<UnsubscribeTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

CreateAgoraRtmClient

Description

Before using a stream channel, you need to call the CreateAgoraRtmClient method to create an IStreamChannel instance. After successfully creating the instance, you can call its relevant methods to implement functions, such as joining the channel, leaving the channel, sending messages in a topic, and subscribing to messages in a topic.

Method

You can call the CreateAgoraRtmClient method as follows:

IStreamChannel CreateStreamChannel(string channelName);

Basic usage

try
{
    IStreamChannel streamChannel = rtmClient.CreateStreamChannel("Chat_room");
}
catch(RTMException e)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode : {1}, due to: {2}", e.Status.Operation , e.Status.ErrorCode , e.Status.Reason));
}

Return value

Returns an IStreamChannel instance.

IStreamChannel Stream channel instance

JoinTopicAsync

Description

After successfully creating a stream channel, you can call the JoinTopicAsync method to join the stream channel. Once you join the channel, you can implement channel-related functions. At this point, users who subscribe to the channel and add event listeners can receive the following event notifications:

• For the local user:
  • The SNAPSHOT type of the OnPresenceEvent event.
  • The SNAPSHOT type of the OnTopicEvent event.
• For remote users: The REMOTE_JOIN type of the OnPresenceEvent event.

Method

You can call the JoinTopicAsync method as follows:

RtmResult<JoinResult> JoinAsync(JoinChannelOptions options);

The JoinChannelOptions data type contains the following properties:

Basic usage

var (status,response) = await streamChannel.JoinAsync(options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0} Join stream channel success! at Channel:{1}", response.UserId, response.ChannelName));
}

Return value

The JoinTopicAsync operation returns a RtmResult<JoinTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The JoinTopicResult data type contains the following properties:

LeaveTopicAsync

Description

If you no longer need to stay in a channel, you can call the LeaveTopicAsync method to leave the channel. After leaving the channel, you can no longer receive any messages, states, or event notifications from this channel. At the same time, you can no loger be the topic publisher or subscriber of all topics. If you want to restore your previous publisher role and subscribing relationship, you need to call JoinTopicAsync, JoinTopicAsync and SubscribeTopicAsync methods in order.

After successfully leaving the channel, remote users in the channel can receive the REMOTE_LEAVE type of the OnPresenceEvent event notification. For details, see Event Listeners.

Method

You can call the LeaveTopicAsync method as follows:

RtmResult<LeaveResult> LeaveAsync();

Basic usage

var (status,response) = await streamChannel.LeaveAsync();
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode:{1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0} Join stream channel success! at Channel:{1}", response.UserId, response.ChannelName));
}

Return value

The LeaveTopicAsync operation returns a RtmResult<LeaveTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The LeaveTopicResult data type contains the following properties:

ReleaseLockAsync

Description

If you no longer need a channel, you can call the ReleaseLockAsync method to destroy the corresponding stream channel instance and release resources. Calling the ReleaseLockAsync method does not destroy the stream channel, and it can be re-joined later by calling CreateAgoraRtmClient and JoinTopicAsync again.

Method

You can call the ReleaseLockAsync method as follows:

RtmStatus Dispose();

Basic usage

var status = streamChannel.Dispose();
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode:{1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log("Dispose Channel Success!");
}

Return value

This operation returns the RtmStatus data type.

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

Topics

Topic is a data stream management mechanism in stream channels. Users can use topics to subscribe to and distribute data streams, as well as notify events in data streams in stream channels.

IStreamChannel Stream channel instance

JoinTopicAsync

Description

The purpose of joining a topic is to register as one of the message publishers for the topic, so that the user can send messages in the topic. This operation does not affect whether or not the user becomes a subscriber to the topic.

After successfully joining a topic, users who subscribe to that topic and add event listeners can receive the REMOTE_JOIN type of the OnTopicEvent event notification. For details, see Event Listeners.

Method

You can call the JoinTopicAsync method as follows:

RtmResult<JoinTopicResult> JoinTopicAsync(string topic, JoinTopicOptions options);

The JoinTopicOptions data type contains the following properties:

Basic usage

var options = new JoinTopicOptions();
options.qos = RTM_MESSAGE_QOS.ORDERED;

var (status,response) = await streamChannel.JoinTopicAsync(topic, options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, because of: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName));
}

Return value

The JoinTopicAsync operation returns a RtmResult<JoinTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The JoinTopicResult data type contains the following properties:

PublishTopicMessageAsync

Description

Use the PublishTopicMessageAsync method to send messages to a topic. Users who have subscribed to the topic and the message publisher in the channel can receive the message within 100 milliseconds. Before calling the PublishTopicMessageAsync method, users need to join the stream channel, and then register as a message publisher for that topic by calling the JoinTopicAsync method.

The messages sent by users are encrypted with TLS during transmission, and data link encryption is enabled by default and cannot be disabled. To achieve a higher level of data security, users can also enable client encryption during initialization. For details, see Setup.

Method

You can call the PublishTopicMessageAsync[1/2] and PublishTopicMessageAsync[2/2] method as follows:

// PublishTopicMessageAsync[1/2]
RtmResult<PublishTopicMessageResult> PublishTopicMessageAsync(string topic, byte[] message, TopicMessageOptions option);

// PublishTopicMessageAsync[2/2]
RtmResult<PublishTopicMessageResult> PublishTopicMessageAsync(string topic, string message, TopicMessageOptions option);

The TopicMessageOptions data type contains the following properties:

Basic usage

var message = "Hello World";
var topic = "Motion";
var options = new TopicMessageOptions();
options.customType = "PlainText";
var (status,response) = await streamChannel.PublishTopicMessageAsync(topic, message, options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}

Return value

The PublishTopicMessageAsync operation returns a RtmResult<PublishTopicMessageResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

LeaveTopicAsync

Description

When you no longer need to publish messages to a topic, to release resources, you can call the LeaveTopicAsync method to unregister as a message publisher for that topic. This method does not affect whether or not you subscribe to that topic or any other operations performed by other users on that topic.

After successfully calling this method, users who subscribe to the channel and enable event listeners can receive the REMOTE_LEAVE type of the OnTopicEvent event notification. See Event Listeners.

Method

You can call the LeaveTopicAsync method as follows:

RtmResult<LeaveTopicResult> LeaveTopicAsync(string topic);

Basic usage

var (status,response) = await streamChannel.LeaveTopicAsync("Motion");
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName));
}

Return value

The LeaveTopicAsync operation returns a RtmResult<LeaveTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The LeaveTopicResult data type contains the following properties:

SubscribeTopicAsync

Description

After joining the channel, you can call the SubscribeTopicAsync method to subscribe to the message publisher of the topic in the channel.

SubscribeTopicAsync is an incremental method. For example, if you call this method for the first time with a subscribing list of [UserA, UserB], and then call it again with a subscribing list of [UserB, UserC], the final successful subscribing result is [UserA, UserB, UserC].

A user can subscribe to a maximum of 50 topics in each channel, and a maximum of 64 message publishers in each topic. See API usage restrictions.

Method

You can call the SubscribeTopicAsync method as follows:

RtmResult<SubscribeTopicResult> SubscribeTopicAsync(string topic, TopicOptions options);

The TopicOptions data type contains the following properties:

Basic usage

List<string> userList = new List<string>();
userList.Add("Tony");
userList.Add("Marry");

var options = new TopicOptions();
options.users = userList.ToArray();

var (status,response) = await streamChannel.SubscribeTopicAsync(subtopic, options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0} Join Topic:{1} success! at Channel:{2}", response.UserId, response.Topic, response.ChannelName));
}

Return value

The SubscribeTopicAsync operation returns a RtmResult<SubscribeTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The SubscribeTopicResult data type contains the following properties:

UnsubscribeTopicAsync

Description

If you are no longer interested in a specified topic, or no longer need to subscribe to one or more message publishers in the topic, you can call the UnsubscribeTopicAsync method to unsubscribe from the topic or the specified message publishers in the topic.

Method

You can call the UnsubscribeTopicAsync method as follows:

RtmResult<UnsubscribeTopicResult> UnsubscribeTopicAsync(string topic, TopicOptions options);

The TopicOptions data type contains the following properties:

Basic usage

List<string> userList = new List<string>();
userList.Add("Tony");
userList.Add("Marry");

var options = new TopicOptions();
topicOptions.users = userList.ToArray();

var (status,response) = await streamChannel.UnsubscribeTopicAsync(subtopic, options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}

Return value

The UnsubscribeTopicAsync operation returns a RtmResult<UnsubscribeTopicResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

Messages

Sending and receiving messages is the most basic function of the Signaling service. Any message sent by the Signaling server can be delivered to any online subscribing user within 100 ms. Depending on your business requirements, you can send messages to one user only or broadcast messages to multiple users.

Signaling offers two types of channels: message channels and stream channels. These channel types have the following differences in how messages are transmitted and methods are called:

• Message Channel: The real-time channel. Messages are transmitted through the channel, and the channel is highly scalable. Local users can call the PublishTopicMessageAsync method to send messages in the channel, and remote users can call the SubscribeTopicAsync method to subscribe to the channel and receive messages.
• Stream Channel: The streaming transmission channel. Messages are transmitted through the topic. Users need to join a channel first, and then join a topic. Local users can call the PublishTopicMessageAsync method to send messages in the topic, and remote users can call the SubscribeTopicAsync method to subscribe to the topic and receive messages.

This page introduces how to send and receive messages in a Message Channel.

IRtmClient Signaling client instance

PublishTopicMessageAsync

Description

You can directly call the PublishTopicMessageAsync method to send messages to all online users subscribed to this channel. Even if you do not subscribe to the channel, you can still send messages in the channel.

After successfully calling this method, the SDK triggers a OnMessageEvent event notification. Users who subscribe to the channel and enabled the event listener can receive this event notification. For details, see Event Listeners.

Method

You can call the PublishTopicMessageAsync [1/2] and PublishTopicMessageAsync [2/2] methods as follows:

// PublishAsync[1/2]
RtmResult<PublishResult> PublishAsync(string channelName, byte[] message, PublishOptions option);

// PublishAsync[2/2]
RtmResult<PublishResult> PublishAsync(string channelName, string message, PublishOptions option);

The TopicMessageOptions data type contains the following properties:

Basic usage

var message = "Hello World";
var channelName = "my_channel";
var options = new PublishOptions();
options.customType = "PlainText";

var (status,response) = await rtmClient.PublishAsync(channelName, message, options);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log("Publish Message Success!");
}

Return value

The PublishTopicMessageAsync operation returns a RtmResult<PublishTopicMessageResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The PublishTopicMessageResult data type contains the following properties:

Receive

Signaling provides event notifications for messages, states, and event changes. By listening for callbacks, you can receive messages and events within subscribed channels.

For information on how to add and set event listeners, see Event Listeners.

Presence

The presence feature provides the ability to monitor user online, offline, and user historical state change. With the Presence feature, you can get real-time access to the following information:

• Real-time event notification when a user joins or leaves a specified channel.
• Real-time event notification when the custom temporary user state changes.
• Query which channels a specified user has joined or subscribed to.
• Query which users have joined a specified channel and their temporary user state data.

IRtmClient Signaling client instance

WhoNowAsync

Description

By calling the WhoNowAsync method, you can query real-time information about the number of online users, the list of online users, and the temporary state of online users in a specified channel.

Method

You can call the WhoNowAsync method as follows:

RtmResult<GetOnlineUsersResult> rtmClient.GetPresence().GetOnlineUsersAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    PresenceOptions options
    );

The PresenceOptions data type contains the following properties:

Basic usage

var options = new PresenceOptions();
options.withState = true;

var (status,response) = await rtmClient.GetPresence().GetOnlineUsersAsync("Chat_room", RTM_CHANNEL_TYPE.MESSAGE, options);
if (result.Status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("You have got {0} users information ", response.TotalOccupancy));
    if (response.NextPage != null)
    {
        Debug.Log("you have the next page information waiting for read!");
    }
}

Return value

The WhoNowAsync operation returns a RtmResult<WhoNowResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The WhoNowResult data type contains the following properties:

The UserState[] data type contains the following properties:

StateItem data type contains the following properties:

WhereNowAsync

Description

In use-cases such as statistic analytics and debugging, you may need to know all the channels that a specified user has subscribed to or joined. Call the WhereNowAsync method to get the list of channels where the specified user is in real time.

Method

You can call the WhereNowAsync method as follows:

RtmResult<GetUserChannelsResult> rtmClient.GetPresence().GetUserChannelsAsync(string userId);

Basic usage

var (status,respones) = await rtmClient.GetPresence().GetUserChannelsAsync("Tony");
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User Tony is now in {0} channels ", response.Channels.Length));
    if (response.Channels.Length > 0)
    {
        for (int i = 0; i < response.Channels.Length; i++)
        {
            var channelInfo = response.Channels[i];
            string infor = string.Format("Tony is in channelName:{0}, channelType:{1}", channelInfo.channelName, channelInfo.channelType);
            Debug.Log(infor);
        }
    }
}

Return value

The WhereNowAsync operation returns a RtmResult<WhereNowResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The WhereNowResult data type contains the following properties:

The ChannelInfo data type contains the following properties:

SetStateAsync

Description

To meet different requirements in different business use-cases for setting user states, Signaling provides the SetStateAsync method to customize the temporary user state. Users can add custom states such as scores, game state, location, mood, and hosting state for themselves.

After successful setup, as long as the user keeps subscribing to the channel and stays online, the custom states can persist in the channel. SetStateAsync method sets the temporary user state, and the state disappears when the user leaves the channel or disconnects from Signaling. If you need to restore user states when rejoining a channel or reconnecting, you need to cache the data locally in real time. If you want to permanently save user states, Agora recommends you use the SetUserMetadataAsync method of the storage function instead.

If a user modifies the temporary user state, Signaling triggers the REMOTE_STATE_CHANGED type of the OnPresenceEvent event in real time. You can receive the event by subscribing to the channel and configuring the corresponding property.

Method

You can call the SetStateAsync method as follows:

RtmResult<SetStateResult> rtmClient.GetPresence().SetStateAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    StateItem[] items
    );

StateItem data type contains the following properties:

Basic usage

var stateItems = new StateItem[1];
stateItems[0] = new StateItem("state", "Online");
var (status,response) = await rtmClient.GetPresence().SetStateAsync(channelName, RTM_CHANNEL_TYPE.MESSAGE, stateItems);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log("Set State Success!");
}

Return value

The SetStateAsync operation returns a RtmResult<SetStateResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

GetStateAsync

Description

To get the temporary user state of a specified user in the channel, you can use the GetStateAsync method.

Method

You can call the GetStateAsync method as follows:

RtmResult<GetStateResult> rtmClient.GetPresence().GetStateAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    string userId
    );

Basic usage

var (status,response) = await rtmClient.GetPresence().GetStateAsync(channelName, RTM_CHANNEL_TYPE.MESSAGE, userId);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("User:{0}, have stateCount:{1} states",response.State.userId, response.State.states.Length));
}

Return value

The GetStateAsync operation returns a RtmResult<GetStateResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The GetStateResult data type contains the following properties:

The UserState data type contains the following properties:

StateItem data type contains the following properties:

RemoveStateAsync

Description

When a temporary user state is no longer needed, you can call the RemoveStateAsync method to remove one or more of your temporary states. When the user state is removed, the user who has subscribed to the channel and enabled the presence event listener receives the REMOTE_STATE_CHANGED type of OnPresenceEvent event notification. See Event Listeners.

Method

You can call the RemoveStateAsync method as follows:

RtmResult<RemoveStateResult> rtmClient.GetPresence().RemoveStateAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    string[] keys
    );

Basic usage

var channelName = "Chat_room";
string[] keys = new string[] { "mode" };
var (status,respones) = await rtmClient.GetPresence().RemoveStateAsync(channelName, RTM_CHANNEL_TYPE.MESSAGE, keys);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log("Remove State Success!");
}

Return value

The RemoveStateAsync operation returns a RtmResult<RemoveStateResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

Storage

The storage feature provides a dynamic database mechanism that allows developers to dynamically set, store, update, and delete data such as channel metadata and user metadata.

IRtmClient Signaling client instance

SetChannelMetadataAsync

Description

The SetChannelMetadataAsync method sets metadata for a message channel or stream channel. A channel can only have one set of metadata, but each set of metadata can have one or more metadata items. If you call this method multiple times, the SDK retrieves the key of the metadata items in turn and apply settings according to the following rules:

• If you set metadata with different key, the SDK adds each set of metadata in sequence according to the order of the method calls.
• If you set metadata with the same key, the value of the last setting overwrites the previous one.

After successfully setting channel metadata, users who subscribe to the channel and enable event listeners can receive the CHANNEL type of the OnStorageEvent event notification. See Event listeners.

Channel metadata also introduces the version control logic CAS (Compare And Set). This method provides two independent version control fields, and you can set one or more of them according to your actual business use-case:

• Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the RtmMetadata class.
• Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class within the RtmMetadata class.

When setting channel metadata or metadata items, you can control whether to enable version number verification by specifying the revision property:

• The default value of the revision property is -1, indicating that this method call does not perform any CAS verification. If the channel metadata or metadata item already exists, the latest value overwrites the previous one. If the channel metadata or metadata item does not exist, the SDK creates it.
• If the revision property is a positive integer, this method call performs the CAS verification. If the channel metadata or metadata item already exists, the SDK updates the corresponding value after the version number verification succeeds. If the channel metadata or metadata item does not exist, the SDK returns the error code.

Method

You can call the SetChannelMetadataAsync method as follows:

RtmResult<SetChannelMetadataResult> rtmClient.GetStorage().SetChannelMetadataAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    RtmMetadata data,
    MetadataOptions options,
    string lockName
    );

The RtmMetadata data type contains the following properties:

The MetadataItem data type contains the following properties:

The MetadataOptions data type contains the following properties:

Basic usage

var metadata = new RtmMetadata();
metadata.majorRevision = 174298270;
var apple = new MetadataItem()
            {
                key = "Apple",
                value = "100",
                revision = 174298200,
            };
var banana = new MetadataItem()
            {
                key = "Banana",
                value = "200",
                revision = 174298100,
            };
metadata.metadataItems = new MetadataItem[] { apple, banana };
metadata.metadataItemsSize = 2;
var metadataOptions = new MetadataOptions()
            {
                recordUserId = true,
                recordTs = true
            };
var lockName = "lockName";

var (status,respones) = await rtmClient.GetStorage().SetChannelMetadataAsync("channel_name", RTM_CHANNEL_TYPE.MESSAGE, metadata, metadataOptions, lockName);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("Set Channel :{0} metadata success! Channel Type is :{1}! ", response.ChannelName, response.ChannelType));
}

Return value

The SetChannelMetadataAsync operation returns a RtmResult<SetChannelMetadataResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The SetChannelMetadataResult data type contains the following properties:

GetChannelMetadataAsync

Description

The GetChannelMetadataAsync method can get the metadata of the specified channel.

Method

You can call the GetChannelMetadataAsync method as follows:

RtmResult<GetChannelMetadataResult> rtmClient.GetStorage().GetChannelMetadataAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType
    );

Basic usage

var (status,respones) = await rtmClient.GetStorage().GetChannelMetadataAsync("channel_name", RTM_CHANNEL_TYPE.MESSAGE);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("Get Channel :{0} metadata success! Channel Type is :{1}! ", response.ChannelName, response.ChannelType));
    var data =  response.data;
    if (data.metadataItemsSize != 0)
    {
        Debug.Log(string.Format("Channel Metadata Major Revision is :{0} ! ", data.majorRevision));
        for ( int i =0; i < data.metadataItemsSize; i++)
        {
            Debug.Log(string.Format("The {0}'th iterms Key is:{1}, Value is {2} ! ", i, data.metadataItems[i].key, data.metadataItems[i].value));
        }
    }
}

Return value

The GetChannelMetadataAsync operation returns a RtmResult<GetChannelMetadataResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The GetChannelMetadataResult data type contains the following properties:

The RtmMetadata data type contains the following properties:

The MetadataItem data type contains the following properties:

The MetadataOptions data type contains the following properties:

RemoveChannelMetadataAsync

Description

The RemoveChannelMetadataAsync method can remove channel metadata or metadata items.

When removing channel metadata or metadata items, you can control whether to enable version number verification by specifying the revision property:

• The default value of the revision property is -1, indicating that this method call does not perform any CAS verification. If the channel metadata or metadata item already exists, the SDK removes it. If the channel metadata or metadata item does not exist, the SDK returns the error code.
• If the revision property is a positive integer, this method call performs the CAS verification. If the channel metadata or metadata item already exists, the SDK removes the corresponding value after the version number verification succeeds. If the channel metadata or metadata item does not exist, the SDK returns the error code.

After successfully removing channel metadata or metadata items, users who subscribe to the channel and enable event listeners can receive the CHANNEL type of the OnStorageEvent event notification. See Event listeners.

Method

You can call the RemoveChannelMetadataAsync method as follows:

RtmResult<RemoveChannelMetadataResult> rtmClient.GetStorage().RemoveChannelMetadataAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    RtmMetadata data,
    MetadataOptions options,
    string lockName
    );

The RtmMetadata data type contains the following properties:

The MetadataItem data type contains the following properties:

The MetadataOptions data type contains the following properties:

Basic usage

var metadata = new RtmMetadata();
metadata.majorRevision = 174298270;
var metadataItem = new MetadataItem()
            {
                key = "174298270",
                revision = 174298200,
            };
metadata.metadataItems = new MetadataItem[] { metadataItem };
metadata.metadataItemsSize = 1;
var options = new MetadataOptions() { };

var (status,response) = await rtmClient.GetStorage().RemoveChannelMetadataAsync("channel_name", RTM_CHANNEL_TYPE.MESSAGE, oOptions,"");
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("Remove Channel :{0} metadata success! Channel Type is :{1}! ", response.ChannelName, response.ChannelType));
}

Return value

The RemoveChannelMetadataAsync operation returns a RtmResult<RemoveChannelMetadataResult> data type, including the following properties:

The RtmStatus data type contains the following properties:

To find out the cause of the error and get the corresponding solution, use the errorCode field with the error codes table.

The RemoveChannelMetadataResult data type contains the following properties:

UpdateChannelMetadataAsync

Description

The UpdateChannelMetadataAsync method can update existing channel metadata. Each time you call this method, you can update one channel metadata or a channel metadata item.

After successfully updating channel metadata, users who subscribe to the channel and enable event listeners can receive the CHANNEL type of the OnStorageEvent event notification. See Event listeners.

Method

You can call the UpdateChannelMetadataAsync method as follows:

RtmResult<UpdateChannelMetadataResult> rtmClient.GetStorage().UpdateChannelMetadataAsync(
    string channelName,
    RTM_CHANNEL_TYPE channelType,
    RtmMetadata data,
    MetadataOptions options,
    string lockName
    );

The RtmMetadata data type contains the following properties:

The MetadataItem data type contains the following properties:

The MetadataOptions data type contains the following properties:

Basic usage

var metadata = new RtmMetadata();
metadata.majorRevision = 174298270 ;
var apple = new MetadataItem()
            {
                key = "Apple",
                value = "120",
                revision = 174298200,
            };
var banana = new MetadataItem()
            {
                key = "Banana",
                value = "220",
                revision = 174298100,
            };
metadata.metadataItems = new MetadataItem[] { apple, banana };
metadata.metadataItemsSize = 2;
var options = new MetadataOptions()
            {
                recordUserId = true,
                recordTs = true
            };

var lockName = "lockName";

var (status,response) = await rtmClient.GetStorage().UpdateChannelMetadataAsync("channel_name", RTM_CHANNEL_TYPE.MESSAGE, data, options, lockName);
if (status.Error)
{
    Debug.Log(string.Format("{0} is failed, ErrorCode: {1}, due to: {2}", status.Operation, status.ErrorCode, status.Reason));
}
else
{
    Debug.Log(string.Format("Remove Channel :{0} metadata success! Channel Type is :{1}! ", response.ChannelName, response.ChannelType));
}