Web

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

• Setup
• User authentication
• 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 you initialize a Signaling client instance, import the Signaling JavaScript SDK into your project:

• Using CDN:

    <script src="your_path_to_signaling_sdk/agora-rtm.x.y.z.min.js"></script>

• Using a package manager:

    npm install agora-rtm-sdk

Initialization

Description

Initialization in Signaling refers to creating and initializing a Signaling client instance. When initializing the instance, you need to pass in parameters including appId and userId. You can create a project and get the App ID on the Agora console.

Method

You can create and initialize an instance as follows:

class RTM(
    constructor(
        appId: string,
        userId: string,
        rtmConfig?: {
             encryptionMode: string,
             cipherKey: string,
             salt: Uint8Array,
             useStringUserId: boolean,
             presenceTimeout: number,
             logUpload: boolean,
             logLevel: string,
             cloudProxy: boolean
         }
    );
)

Basic Usage

const { RTM } = AgoraRTM;
const rtm = new RTM("yourAppId", "Tony");

Return Value

A Signaling client instance. Now you can call other Signaling APIs.

RTMConfig

Description

RTMConfig is used to configure additional properties when you initializing a Signaling client instance. These configuration properties take effect throughout the lifecycle of the Signaling client and affect the behaviors of the Signaling client.

Method

You can create a RTMConfig instance as follows:

const { RTMConfig } = AgoraRTM;

privateConfig contains the following properties:

Basic Usage

const { RTM, EncryptionMode } = AgoraRTM;
const rtmConfig = {
    encryptionMode : EncryptionMode.AES_256_GCM,
    salt : yourSalt,
    cipherKey : "yourCipherKey",
    presenceTimeout : 300,
    logUpload : true,
    logLevel : "debug",
    cloudProxy : false,
    useStringUserId : false,
    privateConfig: {
        serviceType: ["MESSAGE", "STREAM"],
        domainMode: 2
    },
    heartbeatInterval: 5
};
const rtm = new RTM("yourAppId", "Tony", rtmConfig);

Event Listeners

Description

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

Add event listeners

You can add event listeners as follows:

 // Add message event listeners
 // Message
rtm.addEventListener("message", event => {
    const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER".
    const channelName = event.channelName; // Which channel does this message come from
    const topic = event.topicName; // Which Topic does this message come from, it is valid when the channelType is "STREAM".
    const messageType = event.messageType; // Which message type it is, Should be "STRING" or "BINARY" .
    const customType = event.customType; // User defined type
    const publisher = event.publisher; // Message publisher
    const message = event.message; // Message payload
    const timestamp = event.timestamp; // Event timestamp
});
 // Presence
rtm.addEventListener("presence", event => {
    const action = event.eventType; // Which action it is ,should be one of 'SNAPSHOT'、'INTERVAL'、'JOIN'、'LEAVE'、'TIMEOUT、'STATE_CHANGED'、'OUT_OF_SERVICE'.
    const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER".
    const channelName = event.channelName; // Which channel does this event come from
    const publisher = event.publisher; // Who trigger this event
    const states = event.stateChanged; // User state payload, only for stateChanged event
    const interval = event.interval; // Interval payload, only for interval event
    const snapshot = event.snapshot; // Snapshot payload, only for snapshot event
    const timestamp = event.timestamp; // Event timestamp
});
 // Topic
rtm.addEventListener("topic", event => {
    const action = event.evenType; // Which action it is ,should be one of 'SNAPSHOT'、'JOIN'、'LEAVE'.
    const channelName = event.channelName; // Which channel does this event come from
    const publisher = event.userId; // Who trigger this event
    const topicInfos = event.topicInfos; // Topic information payload
    const totalTopics = event.totalTopics; // How many topics
    const timestamp = event.timestamp; // Event timestamp
});
 // Storage
rtm.addEventListener("storage", event => {
    const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER".
    const channelName = event.channelName; // Which channel does this event come from
    const publisher = event.publisher; // Who trigger this event
    const storageType = event.storageType; // Which category the event is, should be 'USER'、'CHANNEL'
    const action = event.eventType; // Which action it is ,should be one of "SNAPSHOT"、"SET"、"REMOVE"、"UPDATE" or "NONE"
    const data = event.data; // 'USER_METADATA' or 'CHANNEL_METADATA' payload
    const timestamp = event.timestamp; // Event timestamp
});
 // Lock
rtm.addEventListener("lock", event => {
    const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER".
    const channelName = event.channelName; // Which channel does this event come from
    const publisher = event.publisher; // Who trigger this event
    const action = event.evenType; // Which action it is ,should be one of 'SET'、'REMOVED'、'ACQUIRED'、'RELEASED'、'EXPIRED'、'SNAPSHOT'
    const lockName = event.lockName; // Which lock it effect
    const ttl = event.ttl; // The ttl of this lock
    const snapshot = event.snapshot; // Snapshot payload
    const owner = event.owner; // The owner of this lock
    const timestamp = event.timestamp; // Event timestamp
});
 // Connection State Change
rtm.addEventListener("status", event => {
    const currentState = event.state; // Which connection state right now
    const changeReason = event.reason; // Why trigger this event
    const timestamp = event.timestamp; // Event timestamp
});
 // Link State Change
rtm.addEventListener('linkState', event => {
    const currentState = event.currentState;
    const previousState = event.previousState;
    const serviceType = event.serviceType;
    const operation = event.operation;
    const reason = event.reason;
    const affectedChannels = event.affectedChannels;
    const unrestoredChannels = event.unrestoredChannels;
    const timestamp = event.timestamp;
    const isResumed = event.isResumed;
 // Token Privilege Will Expire
rtm.addEventListener("tokenPrivilegeWillExpire", (channelName) => {
    const channelName = channelName; // Which Channel Token Will Expire
});

Remove event listeners

You can call the config. removedelegate[javascript] method to remove a specified event listener.

rtm.removeEventListener("status", statusHandler);

login

Description

After creating and initializing a Signaling client instance, you need to perform the login operation to log in to the Signaling service. With successful login, the client establishes a long link to the Signaling server and allow the client to access Signaling resources.

Method

You can call the login method as follows:

rtm.login(options?: object): Promise<LoginResponse>;

The options object includes the following properties:

Basic Usage

try{
    const result = await rtm.login({ token: "your_token" });
    console.log(result);
} catch (status){
    console.log(status);
}

Return Value

If the method call succeeds, the LoginResponse response as follows is returned:

type LoginResponse = {
    timestamp: number // Reserved property, indicating the timestamp of the successful operation
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

logout

Description

You can log out of the Signaling system if you don't need to perform any operation.

Method

You can call the logout method as follows:

rtm.logout(): Promise<LogoutResponse>;

Basic Usage

try{
    const result = await rtm.logout();
    console.log(result);
} catch (status){
    console.log(status);
}

Return Value

If the method call succeeds, the LogoutResponse response as follows is returned:

type LoginResponse = {
    timestamp: number // Reserved property, indicating the timestamp of the successful operation
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

User authentication

Authentication is the process of validating the identity of each user before they access a system. Agora uses digital tokens to authenticate users and their privileges.

Signaling provides 3 types of channels: message channels, user channels and stream channels. Different types of channels require different types of tokens:

• For message channels and user channels: When logging in to the Signaling system using the login method, you only need to pass the token that enables Signaling service.
• For stream channels: In addition to the Signaling token, when joining a stream channel using the joinTopic method, you also need to pass the token that enables RTC service.

The token is valid for up to 24 hours. Agora recommends that you update the token before it expires. This article describes how to update the token.

For more information on generating and using tokens, see the following guide:

renewToken

Description

Call the renewToken method to renew the RTC token.

Different parameter settings applies to different token types:

• RTM Token: Only need to fill in the token parameter.
• RTC Token: Need to fill in both the token and channelName parameters.

To ensure timely token updates, Agora recommends listening for the tokenPrivilegeWillExpire callback. See Event listeners for details. Once you successfully add the event listener, when the RTC token is about to expire within 30 seconds, the SDK triggers the tokenPrivilegeWillExpire callback to notify the user about the impending token expiration.

Upon receiving this callback, you can generate a new token on the server-side and call the renewToken method to provide the SDK with the newly generated token.

Method

You can call the renewToken method as follows:

rtm.renewToken(token: string, options?: object): Promise<RenewTokenResponse>

options contains the following properties:

Basic usage

Example 1: Renew the Signaling token

rtmClient.addEventListener('tokenPrivilegeWillExpire', async (channelName) => {
    if(!channelName){
        // The RTM Token is about to expire
        const newToken = "<Your new token>";
        await rtmClient.renewToken(newToken);
    }
});

Example 2: Renew the RTC token

rtmClient.addEventListener('tokenPrivilegeWillExpire', async (streamChannelName) => {
    if(streamChannelName){
        // The RTC Token is about to expire
        const newToken = "<Your new token>";
        await rtmClient.renewToken(newToken, {
            channelName: streamChannelName
        });
    }
});

Return value

If the method call succeeds, the RenewTokenResponse response as follows is returned:

type RenewTokenResponse = {
    timestamp: number , // Timestamp of the successful operation.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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.

subscribeTopic

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 up event listeners, see Event Listener.

By calling the subscribeTopic 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 presence event with the REMOTE_JOIN type.

Method

You can call the subscribeTopic method as follows:

rtm.subscribe(
    channelName: string,
    options?: object
): Promise<SubscribeResponse>;

The options object includes the following properties:

Basic usage

const options ={
    withMessage : true,
    withPresence : true,
    beQuiet : false,
    withMetadata : false,
    withLock : false
};
try {
    const result = await rtm.subscribe("chat_room", options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the SubscribeTopicResponse response as follows is returned:

type SubscribeResponse = {
    timestamp : number // Timestamp of the successful operation.
    channelName : string // Channel name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

unsubscribeTopic

Description

If you no longer need to subscribe to a channel, you can call the unsubscribeTopic method to cancel your subscription. After successfully unsubscribing from the channel, other users who subscribe to the channel and enable event listeners can receive a presence event notification with the REMOTE_LEAVE type. For details, see Event Listener.

Method

You can call the unsubscribeTopic method as follows:

rtm.unsubscribe(
    channelName: string
): Promise<UnsubscribeResponse>;

Basic usage

try {
    const result = await rtm.unsubscribe("chat_room");
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the UnsubscribeTopicResponse response as follows is returned:

type UnsubscribeResponse = {
    timestamp : number // Timestamp of the successful operation.
    channelName : string // Channel name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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 RTMStreamChannel 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:

rtm.createStreamChannel(chanelName: string): RTMStreamChannel;

Basic usage

try{
    const Loc_stChannel = await rtm.createStreamChannel( "Location");
    console.log("Create Stream Channel success!: ");
} catch (status){
    console.log(status);
}

Return value

An RTMStreamChannel instance.

joinTopic

Description

After successfully creating a stream channel, you can call the joinTopic 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:

• Local users:
  • presence event notification with the SNAPSHOT type.
  • topicevent notification with the SNAPSHOT type.
• Remote users: presence event notification with the REMOTE_JOIN type.

Method

You can call the joinTopic method as follows:

join(options?: object): Promise<JoinChannelResponse>;

The options object includes the following properties:

Basic usage

const options ={
    token : "yourToken",
    withPresence : true,
    beQuiet : false,
    withMetadata : false,
    withLock : false
};
try {
    const result = await stChannel.join(options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the JoinTopicResponse response as follows is returned:

type JoinChannelResponse = {
    timestamp : number , // Timestamp of the successful operation.
    channelName : string // Channel name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

leaveTopic

Description

If you no longer need to stay in a channel, you can call the leaveTopic 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 joinTopic, joinTopic and subscribeTopic methods in order.

After successfully leaving the channel, remote users in the channel can receive a presence event notification with the REMOTE_LEAVE type. For details, see Event Listener.

Method

You can call the leaveTopic method as follows:

leave(): Promise<LeaveChannelResponse>;

Basic usage

try{
    const result = await streamChannel.leave();
    console.log(result);
} catch (status){
    console.log(status);
}

Return value

If the method call succeeds, the LeaveTopicResponse response as follows is returned:

type LeaveChannelResponse = {
    timestamp : number // Timestamp of the successful operation.
    channelName : string // Channel name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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.

For more information on the features of topic, click the following card:

joinTopic

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 topic event notification with the REMOTE_JOIN type. For details, see Event Listener.

Method

You can call the joinTopic method as follows:

joinTopic(
    topicName: string,
    options?: object
): Promise<JoinTopicResponse>;

Basic usage

try {
    const result = await stChannel.joinTopic( "gesture", options);
    console.log( result);
} catch (status) {
     console.log(status);
}

Return value

If the method call succeeds, the JoinTopicResponse response as follows is returned:

type JoinTopicResponse = {
    timestamp: number , // Timestamp of the successful operation.
    topicName: string // Topic name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

publishTopicMessage

Description

Call the publishTopicMessage method to send messages to a topic. Users who subscribe to this topic and the message publisher in the channel can receive the message within 100 ms. Before calling the publishTopicMessage method, users need to join the stream channel, and then register as a message publisher for that topic by calling the joinTopic 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 publishTopicMessage method as follows:

publishTopicMessage(
    topicName: string,
    message: string | Uint8Array,
    options?: object
): Promise<PublishTopicMessageResponse>;

The options object includes the following property:

Basic usage

Example 1: Send string messages to a specified channel.

try {
    const result = await stChannel.publishTopicMessage( "Gesture", JSON.stringify({such: "object"}) );
    console.log(result);
} catch (status) {
    console.log(status);
}

Example 2: Send Uint8Array messages to a specified channel.

const str2ab = function(str) {
    var buf = new ArrayBuffer(str.length * 2); // Each character occupies 2 bytes.
    var bufView = new Uint16Array(buf);
    for (var i = 0, strLen = str.length; i < strLen; i++) {
        bufView[i] = str.charCodeAt(i);
    }
    return buf;
}
var Message=str2ab("hello world")
try {
    const result = await stChannel.publishTopicMessage( "Gesture",Message);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the PublishTopicMessageResponse response as follows is returned:

type PublishTopicMessageResponse = {
    timestamp: number , // Timestamp of the successful operation.
    topicName: string // Topic name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

leaveTopic

Description

To release resources when you no longer need to publish messages to a topic, you can call the leaveTopic 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 topic event notification with the REMOTE_LEAVE type. For details, see Event Listener.

Method

You can call the leaveTopic method as follows:

leaveTopic(topicName: string): Promise<LeaveTopicResponse>;

Basic usage

try {
    const result = await stChannel.leaveTopic("gesture");
    console.log(result);
} catch (status) {
     console.log(status);
}

Return value

If the method call succeeds, the LeaveTopicResponse response as follows is returned:

type LeaveTopicResponse = {
    timestamp: number , // Timestamp of the successful operation.
    topicName: string // Topic name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

subscribeTopic

Description

After joining a channel, you can call the subscribeTopic method to subscribe to message publishers of topics in the channel.

subscribeTopic 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].

There is no limit to the number of message publishers that can be registered for a single topic in a channel, but a user can only subscribe to a maximum of 50 topics at the same time in the same channel, and a maximum of 64 message publishers in each topic.

Method

You can call the subscribeTopic method as follows:

subscribeTopic(
    topicName: string,
    options?: object
): Promise<SubscribeTopicResponse>;

The options object includes the following property:

Basic usage

Example 1: Subscribe to a specified message publisher in a topic.

var UIDs = ["zhangsan","lisi","wangwu"]
try {
    const result = await rtm.subscribeTopic( "Gesture", { users:UIDs } );
    console.log(result);
} catch (status) {
    console.log( status);
}

Example 2: Randomly subscribe to 64 message publisher in a topic.

try {
    const result = await stChannel.subscribeTopic("Gesture");
    console.log(result);
}catch(status) {
    console.log(status);
}

Return value

If the method call succeeds, the SubscribeTopicResponse response as follows is returned:

type SubscribeTopicResponse = {
    succeedUsers : string[] , // A list of users who successfully subscribe to the topic.
    failedUsers : string[], // A list of users who fail to subscribe to the topic.
    failedDetails : [ // A list of reasons for subscription failure.
        {
            user : string , // User ID.
            errorCode : number , // Error code.
            reason : string // Reason for the error.
        },
    ],
    timestamp : number, // Timestamp of the successful operation.
    topiclName : string // Topic name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

unsubscribeTopic

Description

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

Method

You can call the unsubscribeTopic method as follows:

unsubscribeTopic(
    topicName: string,
    options?: object
): Promise<UnsubscribeTopicResponse>;

The options object includes the following property:

Basic usage

Example 1: Unsubscribe from a specified message publisher in a topic.

try {
    const result = await rtm.unsubscribeTopic( "Gesture", { users:["Tony","Bo"] });
    console.log("unsubscribe Topic success: ", result);
} catch (status) {
    console.log("unsubscribe Topic failed: ", result);
}

Example 2: Randomly unsubscribe from 64 message publisher in a topic.

try {
    const result = await rtm.unsubscribeTopic("Gesture");
    console.log("unsubscribe topic success: ", result);
} catch (status) {
    console.log("unsubscribe topic failed: ", result);
}

Return value

If the method call succeeds, the UnsubscribeTopicResponse response as follows is returned:

type UnsubscribeTopicResponse = {
    timestamp: number , // Timestamp of the successful operation.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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 3 types of channels: message channels, user 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 publishTopicMessage method, set the channelType parameter to MESSAGE, and set the channelName parameter to the channel name to send messages in the channel. The remote users can call the subscribeTopic method to subscribe to the channel and receive messages.
• User Channel: The real-time channel. Messages are transmitted to the specified user. Local users can call the publishTopicMessage method, set the channelType parameter to USER, and set the channelName parameter to the user ID to send messages to the specified user. The specified remote users receive messages through the message event notifications.
• 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 publishTopicMessage method to send messages in the topic, and remote users can call the subscribeTopic method to subscribe to the topic and receive messages.

This page introduces how to send and receive messages in a message channel or a user channel.

publishTopicMessage

Description

You can directly call the publishTopicMessage method to send messages to all online users who subscribe to the 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 message event notification. Users who subscribe to the channel and enabled the event listener can receive this event notification. For details, see Event Listener.

Method

You can call the publishTopicMessage method as follows:

rtm.publish(
    channelName: string,
    message: string | Uint8Array,
    options?: object
): Promise<PublishResponse>;

The options object includes the following property:

Basic usage

Example 1: Send string messages to a specified channel.

try {
    const result = await rtm.publish( "my_channel", "Hello world" );
    console.log(result);
} catch (status) {
    console.log(status);
}

Example 2: Send Uint8Array messages to a specified channel.

const str2ab = function(str) {
    var buf = new ArrayBuffer(str.length * 2); // Each character occupies 2 bytes.
    var bufView = new Uint16Array(buf);
    for (var i = 0, strLen = str.length; i < strLen; i++) {
        bufView[i] = str.charCodeAt(i);
    }
    return buf;
};
var Message=str2ab("hello world");
try {
    const result = await rtm.publish("my_channel", Message );
    console.log(result);
} catch (status) {
    console.log(status);
}

Example 3: Send string messages to a specified user.

try {
    const result = await rtm.publish("user_b", "Hello world", { channelType: "USER"} );
    console.log(result);
} catch (status) {
    console.log(status);
}

Example 4: Send Uint8Array messages to a specified user.

const str2ab = function(str) {
    var buf = new ArrayBuffer(str.length * 2); // 每个字符占用 2 个字节
    var bufView = new Uint16Array(buf);
    for (var i = 0, strLen = str.length; i < strLen; i++) {
        bufView[i] = str.charCodeAt(i);
    }
    return buf;
};
var Message=str2ab("hello world");
try {
    const result = await rtm.publish("user_b", Message, { channelType: "USER"} );
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the PublishTopicMessageResponse response as follows is returned:

type PublishResponse = {
    timestamp: number , // Timestamp of the successful operation.
    chanelName : string // Channel name.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

Receive

Signaling provides event notifications for messages, states, and event changes. By listening for callbacks, you can receive messages and events within subscribed channels. As an example, the code snippet below shows how to receive messages from the user channel.

rtm.addEventListener("message", event => {
    const channelType = event.channelType; // Which channel type it is, Should be "STREAM", "MESSAGE" or "USER" .
    const channelName = event.channelName; // Which channel does this message come from
    const topic = event.topicName; // Which Topic does this message come from, it is valid when the channelType is "STREAM".
    const messageType = event.messageType; // Which message type it is, Should be "STRING" or "BINARY" .
    const customType = event.customType; // User defined type
    const publisher = event.publisher; // Message publisher
    const message = event.message; // Message payload
    const timestamp = event.timestamp; // Message timestamp
});

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

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.

getOnlineUsers

Description

Call the getOnlineUsers method to query user information in real time such as the number of online users, the list of online users and their temporary user status in the specified channel.

Method

You can call the getOnlineUsers method as follows:

rtm.presence.getOnlineUsers(
    channelName: string,
    channelType: string,
    options?: object
): Promise<getOnlineUsersResponse>;

options contains the following properties:

Basic Usage

const options = {
    includedUserId : true ,
    includedState : true,
    page : "yourBookMark"
}
try{
    const result = await rtm.presence.getOnlineUsers( "chat_room", "MESSAGE", options );
    console.log(result);
} catch(status){
    console.log(status);
}

Return Value

If the method call succeeds, the WhoNowResponse response as follows is returned:

type getOnlineUsersResponse = {
    timestamp: number , // Timestamp of the successful operation.
    totalOccupancy : number , // Number of the online users in the channel.
    occupants : Array<object> , // List of the online users in the channel and their temporary user state.
    nextPage : string // Page number of the next page.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

getUserChannels

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 getUserChannels method to get the list of channels where the specified user is in real time.

Method

You can call the getUserChannels method as follows:

rtm.presence.getUserChannels(userId: string): Promise<GetUserChannelsResponse>;

Basic Usage

try{
    const result = await rtm.presence.whereNow( "Tony" );
    console.log(result);
} catch(status){
    console.log(status);
}

Return Value

If the method call succeeds, the WhereNowResponse response as follows is returned:

type GetUserChannelsResponse = {
    timestamp: number , // Timestamp of the successful operation.
    totalChannel : number , // Number of the channels that the user has joined or subscribed to.
    channels : Array<object> // List of the channels including channel name and channel type.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

setState

Description

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

The setState method sets temporary user state. It means these user states remains in the channel as long as the user stays subscribed to the channel and stays online, and they disappear 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 setUserMetadata method of the storage function instead.

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

Method

Set the temporary user state as follows:

rtm.presence.setState(
    channelName: string,
    channelType: string,
    state: object
): Promise<SetStateResponse>;

Basic Usage

var newState = { "mood":"pumped", "isTyping":false};

try{
    const result = await rtm.Presence.setState("chat_room", "MESSAGE", newState);
    console.log(result);
} catch(status){
    console.log(status);
}

Return Value

If the method call succeeds, the SetStateResponse response as follows is returned:

type SetStateResponse = {
    timestamp: number , // Timestamp of the successful operation.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

getState

Description

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

Method

Get the temporary user state as follows:

rtm.presence.getState(
    userId: string,
    channelName: string,
    channelType: string,
): Promise<GetStateResponse>;

Basic Usage

try{
    const result = await rtm.presence.getState("Tony", "chat_room", "MESSAGE" );
    const.log(result);
} catch (status) {
    console.log(status);
}

Return Value

If the method call succeeds, the GetStateResponse response as follows is returned:

type GetStateResponse = {
    timestamp: number , // Timestamp of the successful operation.
    userId : string , // User ID.
    states : object , // Key-value pairs of the user states.
    statesCount : number // Numbers of the user states.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

removeState

Description

When a temporary user state is no longer needed, you can call the removeState method to remove it. When the user state is removed, the user who has subscribed to the channel and enabled the presence event monitoring receives the presence notification in the REMOTE_STATE_CHANGED type. For details, see Event Listener.

Method

You can call the removeState method as follows:

rtm.presence.removeState(
    channelName: string,
    channelType: string,
    options?: object
): Promise<RemoveStateResponse>;

The options object includes the following property:

Basic Usage

const options = {
    states:["mode","Typing"]
}
try{
    const result = await rtm.Presence.removeState("chat_room", "MESSAGE" , options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return Value

If the method call succeeds, the RemoveStateResponse response as follows is returned:

type RemoveStateResponse = {
    timestamp: number , // Timestamp of the successful operation.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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.

setChannelMetadata

Description

The setChannelMetadata 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 storage event notification with the CHANNEL type. For details, see Event Listener.

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 options parameter.
• Enable version number verification for a single metadata item by setting the revision property in the data parameter.

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 no CAS verification is performed for this method call. 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, CAS verification is performed for this method call. 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 setChannelMetadata method as follows:

rtm.storage.setChannelMetadata(
    channelName: string,
    channelType: string,
    data: Array<object>,
    options?: object
): Promise<SetChannelMetadataResponse>;

data contains the following properties:

options contains the following properties:

Basic usage

const data = [
    {
        key : "Apple",
        value : "100"
        revision : 174298200
    },
    {
        key : "Banana",
        value : "200",
        revision : 174298100
    }
];
const options = {
    majorRevision : 174298270,
    lockName: "lockName",
    addTimeStamp : true,
    addUserId : true
};
try {
    const result = await rtm.storage.setChannelMetadata( "channel_name", "MESSAGE", data, options );
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the SetChannelMetadataResponse response as follows is returned:

type SetChannelMetadataResponse = {
    timestamp: number , // Timestamp of the successful operation.
    channelName : string , // Channel name.
    channelType : string , // Channel type.
    totalCount : number // Number of metadata items.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

getChannelMetadata

Description

getChannelMetadata 方法可以获取指定频道的 Metadata。

Method

You can call the getChannelMetadata method as follows:

rtm.storage.getChannelMetadata(
    channelName: string,
    channelType: string
): Promise<GetChannelMetadataResponse>;

Basic usage

try {
    const result = await rtm.storage.getChannelMetadata("channel_name", "MESSAGE");
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the GetChannelMetadataResponse response as follows is returned:

type GetChannelMetadataResponse = {
    timestamp: number , // Timestamp of the successful operation.
    channelName : string , // Channel name.
    channelType : string , // Channel type.
    totalCount : number , // Number of metadata items.
    majorRevision : number , // Version of metadata.
    metadata : Record<string, MetaDataDetail> // JSON object containing metadata item.
}

MetaDataDetail contains the following properties:

type MetaDataDetail = {
    value: string , // Value of a metadata item.
    revision : number , // Version of a metadata item.
    updated : string , // Timestamp of the last update.
    authorUid : string , // User ID of the last editor.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

removeChannelMetadata

Description

Call the removeChannelMetadata method to 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 no CAS verification is performed for this method call. 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, CAS verification is performed for this method call. 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 storage event notification with the CHANNEL type. For details, see Event Listener.

Method

You can call the removeChannelMetadata method as follows:

rtm.storage.removeChannelMetadata(
    channelName: string,
    channelType: string,
    options?: object
): Promise<RemoveChannelMetadataResponse>;

options contains the following properties:

data contains the following properties:

Basic usage

const data = [
    {
        key : "Apple",
        revision : 174298200
    }
];
const options = {
    data : data,
    majorRevision : 174298270,
};
try {
    const result = await rtm.storage.removeChannelMetadata("channel_name", "MESSAGE", options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the RemoveChannelMetadataResponse response as follows is returned:

type RemoveChannelMetadataResponse = {
    timestamp: number , // Timestamp of the successful operation.
    channelName : string , // Channel name.
    channelType : string , // Channel type.
    totalCount : number // Number of metadata items.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

updateChannelMetadata

Description

The updateChannelMetadata method can update existing channel metadata. Each time you call this method, you can update one channel metadata or an array of channel metadata items.

After successfully updating, users who subscribe to the channel and enable event listeners can receive the storage event notification with the CHANNEL type. For details, see Event Listener.

Method

You can call the updateChannelMetadata method as follows:

rtm.storage.updateChannelMetadata(
    channelName: string,
    channelType: string,
    data: Array<object>,
    options?: object
): Promise<UpdateChannelMetadataResponse>;

data contains the following properties:

options contains the following properties:

Basic usage

const data = [
    {
        key : "Apple",
        value : "120",
        revision : 174298200
    },
    {
        key : "Banana",
        value : "220",
        revision : 174298100
    }
];
const options = {
    majorRevision : 174298270,
    addTimeStamp : true,
    addUserId : true
};
try {
    const result = await rtm.storage.updateChannelMetadata("channel_name", "MESSAGE", data, options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the UpdateChannelMetadataResponse response as follows is returned:

type UpdateChannelMetadataResponse = {
    timestamp: number , // Timestamp of the successful operation.
    channelName : string , // Channel name.
    channelType : string , // Channel type.
    totalCount : number // Number of metadata items.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

setUserMetadata

Description

The setUserMetadata method sets metadata for a user. A user 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 user metadata, users who subscribe to the user metadata and enable event listeners can receive the storage event notification with the USER type. For details, see Event Listener.

User 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 user metadata by setting the majorRevision property in the options parameter.
• Enable version number verification for a single metadata item by setting the revision property in the data parameter.

When setting user 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 no CAS verification is performed for this method call. If the user metadata or metadata item already exists, the latest value overwrites the previous one. If the user metadata or metadata item does not exist, the SDK creates it.
• If the revision property is a positive integer, CAS verification is performed for this method call. If the user metadata or metadata item already exists, the SDK updates the corresponding value after the version number verification succeeds. If the user metadata or metadata item does not exist, the SDK returns the error code.

Method

You can call the setUserMetadata method as follows:

rtm.storage.setUserMetadata(
    data: Array<object>,
    options?: object
): Promise<SetUserMetadataResponse>;

data contains the following properties:

options contains the following properties:

Basic usage

const data = [
    {
        key : "Name",
        value : "Tony"
        revision : 174298200
    },
    {
        key : "Mute",
        value : "true",
        revision : 174298100
    }
];
const options = {
    userId : "Tony",
    majorRevision : 174298270,
    addTimeStamp : ture，
    addUserId : true
};
try {
    const result = await rtm.storage.setUserMetadata(data, options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the SetUserMetadataResponse response as follows is returned:

type SetUserMetadataResponse = {
    timestamp: number , // Timestamp of the successful operation.
    userId : string , // User ID.
    totalCount : number // Number of metadata items.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

getUserMetadata

Description

getUserMetadata 方法可以获取指定用户的 Metadata 和 User Metadata Item。

Method

You can call the getUserMetadata method as follows:

rtm.storage.getUserMetadata(options?: object): Promise<GetUserMetadataResponse>;

Basic usage

try {
    const result = await rtm.storage.getUserMetadata({ userId: "Tony" });
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, the GetChannelMetadataResponse response as follows is returned:

type GetChannelMetadataResponse = {
    timestamp: number , // Timestamp of the successful operation.
    userId : string , // User ID.
    totalCount : number , // Number of metadata items.
    majorRevision : number , // Version of metadata.
    metadata : Record<string, MetaDataDetail> // JSON object containing metadata item.
}

MetaDataDetail contains the following properties:

type MetaDataDetail = {
    value: string , // Value of a metadata item.
    revision : number , // Version of a metadata item.
    updated : string , // Timestamp of the last update.
    authorUid : string , // User ID of the last editor.
}

If the method call fails, the ErrorInfo response as follows is returned:

type ErrorInfo = {
    error: boolean; // Whether there is an error in this operation
    operation: string; // The API name of this operation
    errorCode: number; // Error code.
    reason: string; // Error reason.
}

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

removeUserMetadata

Description

Call the removeUserMetadata method to remove user metadata or metadata items.

After successfully removing user metadata or metadata items, users who subscribe to the user metadata and enable event listeners can receive the storage event notification with the USER type. For details, see Event Listener.

Method

You can call the removeUserMetadata method as follows:

rtm.storage.removeUserMetadata(
    options?: object
): Promise<RemoveUserMetadataResponse>;