React Native

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

• Setup
• User authentication
• Components and hooks
• Channels
• Topics
• Messages
• Presence
• Storage
• Lock
• Enumerated types
• Troubleshooting

Setup

The RTM SDK API reference introduces the API definitions, methods, basic usage examples, and return values related to real-time messaging.

RtmConfig

Description

RtmConfig is used to configure additional properties during RTM initialization. These configuration properties take effect for the entire lifecycle of the RTM client and affect its behavior.

Method

You can create an RtmConfig instance as follows:

new RtmConfig({
    userId: uid,
    appId: appId,
})

RtmLogConfig

An RtmLogConfig instance is used to configure and store the local log file agora.log. During debugging, logs help track app status and significantly improve efficiency. If complex issues occur, Agora support may ask for these logs. RtmLogConfig includes the following properties:

RtmProxyConfig

An RtmProxyConfig instance configures proxy-related properties for the client. You may need this in restricted network environments.

RtmProxyConfig includes the following properties:

RtmEncryptionConfig

An RtmEncryptionConfig instance configures encryption properties for the client. Once encryption mode and key are properly set, all messages and states are automatically encrypted and decrypted by the client.

RtmEncryptionConfig includes the following properties:

RtmPrivateConfig

An RtmPrivateConfig instance configures properties required for private deployment.

Basic usage

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

createAgoraRtmClient

Description

Call the createAgoraRtmClient method to create and initialize an RTM client instance.

Method

You can create and initialize an instance as follows:

createAgoraRtmClient(config: RtmConfig): RTMClient

Basic usage

const rtm = createAgoraRtmClient(
    new RtmConfig({
        userId: uid,
        appId: appId,
    })
);

Return value

Returns an RTM client instance for calling other RTM APIs.

Event Listener

Description

RTM supports seven types of event notifications, as shown in the table below:

Add Listener

You can add an event listener object during initialization or call the addEventListener method at any point during the app lifecycle to add one or more event listeners.

Add Listener

You can call the addEventListener method to listen for specific event notifications. See the sample code below:

 // Add the message event listener

 // Message
rtm.addEventListener("message", event => {
    const channelType = event.channelType; // Channel type: "STREAM", "MESSAGE", or "USER"
    const channelName = event.channelName; // The channel from which this message originates
    const topic = event.topicName; // The Topic from which this message originates, valid when channelType is "STREAM"
    const messageType = event.messageType; // Message type: "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; // Action type: 'SNAPSHOT', 'INTERVAL', 'JOIN', 'LEAVE', 'TIMEOUT', 'STATE_CHANGED', 'OUT_OF_SERVICE'
    const channelType = event.channelType; // Channel type: "STREAM", "MESSAGE", or "USER"
    const channelName = event.channelName; // The channel from which this event originates
    const publisher = event.publisher; // The user who triggered 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; // Action type: 'SNAPSHOT', 'JOIN', 'LEAVE'
    const channelName = event.channelName; // The channel from which this event originates
    const publisher = event.userId; // The user who triggered this event
    const topicInfos = event.topicInfos; // Topic information payload
    const totalTopics = event.totalTopics; // Total number of topics
    const timestamp = event.timestamp; // Event timestamp
});

 // Storage
rtm.addEventListener("storage", event => {
    const channelType = event.channelType; // Channel type: "STREAM", "MESSAGE", or "USER"
    const channelName = event.channelName; // The channel from which this event originates
    const publisher = event.publisher; // The user who triggered this event
    const storageType = event.storageType; // Storage category: 'USER' or 'CHANNEL'
    const action = event.eventType; // Action type: "SNAPSHOT", "SET", "REMOVE", "UPDATE", or "NONE"
    const data = event.data; // Payload: 'USER_METADATA' or 'CHANNEL_METADATA'
    const timestamp = event.timestamp; // Event timestamp
});

 // Lock
rtm.addEventListener("lock", event => {
    const channelType = event.channelType; // Channel type: "STREAM", "MESSAGE", or "USER"
    const channelName = event.channelName; // The channel from which this event originates
    const publisher = event.publisher; // The user who triggered this event
    const action = event.evenType; // Action type: 'SET', 'REMOVED', 'ACQUIRED', 'RELEASED', 'EXPIRED', 'SNAPSHOT'
    const lockName = event.lockName; // The lock affected
    const ttl = event.ttl; // Time-to-live of this lock
    const snapshot = event.snapshot; // Snapshot payload
    const owner = event.owner; // Owner of this lock
    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 reasonCode = event.reasonCode;
    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; // The channel whose token will expire
});

Remove Listener

If you no longer need to listen for a specific event but still want to keep other event listeners, you can call the removeEventListener method to remove the specified event listener.

rtm.removeEventListener("tokenPrivilegeWillExpire", yourhandler);

RtmClient

login

Description

After creating and initializing an RTM instance, you need to call the login operation to log in to the RTM service. A successful login establishes a persistent connection between the client and the RTM server, allowing the client to access RTM resources properly.

Method

You can log in to the RTM system using the following method:

login(options?: LoginOptions): 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, it returns a LoginResponse type:

type LoginResponse {
    timestamp: number; // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

logout

Description

When you no longer need to use the service, you can log out by calling the logout method. This operation affects the PCU metric in your billing.

Method

You can log out using the following method:

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, it returns a LogoutResponse type:

type LogoutResponse {
    timestamp: number; // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

User authentication

Authentication refers to the process of verifying a user's identity before they access your system. When users use Agora services, such as joining an audio/video call or logging into the signaling system, Agora uses a Token for authentication.

RTM provides three types of channels: Message Channel, User Channel, and Stream Channel. Each channel type requires a different kind of Token:

• For Message Channel or User Channel: You only need to pass an RTM Token (Token with RTM service enabled) when calling the login method to log in to the RTM system.
• For Stream Channel: In addition to using an RTM Token for authentication, you must also pass an RTC Token (Token with RTC service enabled) when calling the join method to join a Stream Channel.

The maximum validity period of a Token is 24 hours. Agora recommends that you renew the Token before it expires. This document describes how to renew a Token.

renewToken

Description

Calls the renewToken method to renew a Token.

Different parameters are required depending on the type of Token being renewed:

• RTM Token: Only the token parameter is required.
• RTC Token: Both token and channelName parameters are required.

To ensure timely Token renewal, Agora recommends that you listen for the tokenPrivilegeWillExpire callback. See Event Listener for details. Once the event listener is successfully added, the SDK triggers the tokenPrivilegeWillExpire callback 30 seconds before the RTM Token expires, notifying the user that the Token is about to expire. Upon receiving this callback, you can regenerate the RTM Token on your server and call the renewToken method to pass the new RTM Token to the SDK.

Method

You can call the renewToken method as follows:

renewToken(
    token: string,
    options?: RenewTokenOptions
): Promise<RenewTokenResponse>;

The options object includes the following properties:

Basic usage

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

Return value

If the method call succeeds, it returns a RenewTokenResponse type:

type RenewTokenResponse = {
    timestamp: number // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

Components and hooks

Components

RTMProvider

This component provides Context to its child components, allowing all components within children to access the client prop you pass in.

Props

Basic usage

function App({ children }) {
    const [client] = useState(() => createAgoraRtmClient(
        new RtmConfig({
            userId: uid,
            appId: appId,
        })
    ));
    return <RTMProvider client={client}>{children}</RTMProvider>;
}

Hooks

useLogin

Logs in to the RTM service. Logs in when the component is ready and automatically logs out when the component is unmounted.

Parameters

Basic usage

useLogin(client, { token: "your_token" });

useRtm

Retrieves the RTMClient object.

Parameters

Return value

Returns an RTMClient object.

Basic usage

const rtmClient = useRtm();

useRtmEvent

Registers a listener for a specific event on the RTMClient object.

• Registers the specified event listener when the component is mounted.
• Removes the event listener when the component is unmounted.

Parameters

Basic usage

useRtmEvent(client, 'message', (message: MessageEvent) => {
 // your code
});

Channels

A channel is a management mechanism for data transmission in the RTM real-time network. Any user who subscribes to or joins a channel can receive messages and events transmitted in the channel within 100 milliseconds. RTM allows clients to subscribe to hundreds or even thousands of channels. Most RTM APIs perform sending, receiving, encryption, and other operations based on channels.

Based on Agora's capabilities, RTM channels are categorized into three types to match different application scenarios:

• Message Channel: Follows the industry-standard Pub/Sub (publish/subscribe) model. Channels do not need to be created in advance. You can send and receive messages in a channel by subscribing to it. There is no limit to the number of publishers and subscribers in a channel.
• User Channel: Enables point-to-point messaging based on the Pub/Sub model. Users do not need to subscribe to a channel. You can send a message by specifying the user ID, and receive messages by simply listening to the message event.
• Stream Channel: Follows a room-based observer pattern similar to that used in the industry. Users must create and join a channel before sending and receiving messages. Channels can contain multiple Topics, and messages are organized and managed through Topics.

subscribe

Description

RTM provides capabilities for message, status, and event change notifications. By setting up event listeners, you can receive messages and events from the channels you have subscribed to. For how to add and configure event listeners, see the Event Listener section.

By calling the subscribe method, the client can subscribe to a Message Channel and start receiving messages and event notifications from that channel. After the method is successfully called, users who subscribe to the channel and have enabled Presence event listening will receive a presence event of type remoteJoinChannel. See Event Listener for details.

Method

You can call the subscribe method as follows:

subscribe(
    channelName: string,
    options?: SubscribeOptions
): 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 SDK returns a SubscribeResponse type:

type SubscribeResponse = {
    timestamp : number // Reserved field
    channelName : string // Name of the channel in this operation
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

unsubscribe

Description

If you no longer need to follow a channel, you can call the unsubscribe method to unsubscribe from it. After a successful unsubscription, other users who have subscribed to the channel and enabled event listening will receive a presence event of type remoteLeaveChannel. See Event Listener for details.

Method

You can call the unsubscribe method as follows:

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 SDK returns a UnsubscribeResponse type:

type UnsubscribeResponse = {
    timestamp : number // Reserved field
    channelName : string // Name of the channel in this operation
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

createStreamChannel

Description

Before using a Stream Channel, you need to call the createStreamChannel method to create an RTMStreamChannel instance. After the instance is successfully created, you can call its related methods such as joining the channel, leaving the channel, sending Topic messages, and subscribing to Topic messages.

Method

You can call the createStreamChannel method as follows:

createStreamChannel(channelName: string): Promise<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.

RTMStreamChannel

join

Description

After successfully creating a Stream Channel, you can call the join method to join the Stream Channel.

You must join the channel before performing any channel-related operations. Users who subscribe to the channel and have added event listeners will receive the following event notifications:

• Local user:
  • A presence event of type snapshot.
  • A topic event of type snapshot.
• Remote users: A presence event of type remoteJoinChannel.

Method

You can call the join method as follows:

join(options?: JoinChannelOptions): 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 SDK returns a JoinChannelResponse type:

type JoinChannelResponse = {
    timestamp : number, // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

leave

Description

If you no longer need to stay in a channel, you can call the leave method to leave it. After leaving, you will no longer receive any messages, status updates, or event notifications from the channel. Your publisher role and all Topic subscriptions in that channel will be automatically removed. To restore your previous publisher role and subscriptions, you must call the join method again and manually call joinTopic and subscribeTopic.

After successfully leaving the channel, remote users in the channel will receive a presence event of type remoteLeaveChannel. See Event Listener for details.

Method

You can call the leave method as follows:

abstract 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 SDK returns a LeaveChannelResponse type:

export type LeaveChannelResponse = {
    timestamp : number // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

Topics

A Topic is a data stream management mechanism within a Stream Channel. You can use Topics to subscribe to, distribute, and receive event notifications for data streams in a Stream Channel.

RTMStreamChannel

joinTopic

Description

Calling joinTopic registers the user as a publisher to the specified Topic, allowing them to send messages to it. This operation does not affect whether the user is a subscriber to the Topic.

After successfully joining a Topic, users who have subscribed to that Topic and enabled event listening will receive a topic event of type remoteJoinTopic. See Event Listener for details.

Method

You can call the joinTopic method as follows:

joinTopic(
    topicName: string,
    options?: JoinTopicOptions
): 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, it returns a JoinTopicResponse type:

type JoinTopicResponse = {
    timestamp: number, // Reserved field
    topicName: string // Name of the Topic joined
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

publishTopicMessage

Description

The publishTopicMessage method sends a message to a Topic. Users in the channel who have subscribed to the Topic and the publisher will receive the message within 100 milliseconds. To use this method, you must first join the Stream Channel and register as a publisher of the Topic by calling joinTopic.

Messages sent by the user are encrypted with TLS during transmission. Data link encryption is enabled by default and cannot be disabled. You can also enable end-to-end encryption during initialization for higher data security. See Initial Configuration for details.

Method

You can call the publishTopicMessage method as follows:

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

The options object includes the following properties:

Basic usage

Example 1: Send a string message to a specific Topic

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

Example 2: Send a Uint8Array message to a specific Topic

try {
    const result = await stChannel.publishTopicMessage("Gesture", new Uint8Array(Buffer.from(your_message)));
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, it returns a PublishTopicMessageResponse type:

type PublishTopicMessageResponse = {
    timestamp: number, // Reserved field
    topicName: string // Name of the Topic the message was sent to
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

leaveTopic

Description

If you no longer need to publish messages to a Topic, you can call the leaveTopic method to unregister as a publisher, thereby releasing resources. This method does not affect your subscription to the Topic or any operations by other users.

After a successful call, users who subscribe to the channel and have enabled event listening will receive a topic event of type remoteLeaveTopic. See Event Listener for details.

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, it returns a LeaveTopicResponse type:

type LeaveTopicResponse = {
    timestamp: number, // Reserved field
    topicName: string // Name of the Topic
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

subscribeTopic

Description

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

subscribeTopic is incremental. For example, if the first call subscribes to [UserA, UserB] and the second call subscribes to [UserB, UserC], the final result is [UserA, UserB, UserC].

Each user can subscribe to up to 50 Topics in the same channel, and up to 64 publishers per Topic.

Method

You can call the subscribeTopic method as follows:

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

The options object includes the following properties:

Basic usage

Example 1: Subscribe to specific publishers 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 publishers 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, it returns a SubscribeTopicResponse type:

type SubscribeTopicResponse = {
    succeedUsers: string[], // List of users successfully subscribed to
    failedUsers: string[], // List of users failed to subscribe to
    timestamp: number, // Reserved field
    topiclName: string // Name of the Topic subscribed to
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

unsubscribeTopic

Description

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

Method

You can call the unsubscribeTopic method as follows:

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

The options object includes the following properties:

Basic usage

Example 1: Unsubscribe from specific publishers 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 publishers 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, it returns an UnsubscribeTopicResponse type:

type UnsubscribeTopicResponse = {
    timestamp: number // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

Messages

Sending and receiving messages is one of the core features of the RTM service. Any message sent using RTM will be delivered to any online subscribed user within 100 ms. You can send a message to a single user or broadcast messages to multiple users, depending on your use case.

RTM supports three types of channels: Message Channel, User Channel, and Stream Channel. The main differences between these channel types are as follows:

• Message Channel: A real-time channel with strong scalability where messages are transmitted through the channel. A local user can call the publish method, set the channelType parameter to message, and provide the channelName to send a message. Remote users can call the subscribe method to subscribe to the channel and receive messages.
• User Channel: Sends point-to-point messages to a specified user. A local user can call the publish method, set the channelType to user, and set channelName to the target user's userId to send a message. The target user receives the message via the message event notification.
• Stream Channel: A stream-based channel where users must first join the channel and then join a Topic. Messages are transmitted through Topics. A local user can call the publishTopicMessage method to send messages to a Topic. Remote users can call the subscribeTopic method to subscribe to the Topic and receive messages.

This document describes how to send and receive messages in Message Channels and User Channels.

publish

Description

You can directly call the publish method to send a message to all online users subscribed to the specified channel. You can still send messages to a channel even if you haven't subscribed to it.

After the method is successfully called, the SDK triggers a message event notification. Users who have subscribed to the channel and enabled event listening will receive this notification. See Event Listener for details.

Method

You can call the publish method as follows:

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

The options object includes the following properties:

Basic usage

Example 1: Send a string message to a specified Message Channel and store it in history

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

Example 2: Send a Uint8Array message to a specified Message Channel and store it in history

try {
    const result = await rtm.publish("my_channel", new Uint8Array(Buffer.from(your_message)), { channelType: "MESSAGE", storeInHistory: true });
    console.log(result);
} catch (status) {
    console.log(status);
}

Example 3: Send a string message to a specified User Channel

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

Example 4: Send a Uint8Array message to a specified User Channel

try {
    const result = await rtm.publish("user_b", new Uint8Array(Buffer.from(your_message)), { channelType: "USER" });
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, it returns a PublishResponse type:

type PublishResponse = {
    timestamp: number, // Reserved field
    channelName: string // Channel name
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

RtmHistory

getMessages

Description

If you need to retrieve historical messages from a specified channel, call the getMessages method on the client.

Method

You can call the getMessages method as follows:

getMessages(
    channelName: string,
    channelType: RtmChannelType,
    options?: GetHistoryMessagesOptions
): Promise<GetMessagesResponse>;

The GetHistoryMessagesOptions type includes the following properties:

Basic usage

const options = { messageCount: 50, start: 0, end: 0 };
try {
    const result = await rtm.history.getMessages("my_channel", "MESSAGE", options);
    console.log(result);
} catch (status) {
    console.log(status);
}

Return value

If the method call succeeds, it returns a GetMessagesResponse type:

type GetMessagesResponse = BaseResponse & {
    messageList: HistoryMessage[]; // List of historical messages
    count: number; // Total number of historical messages
    newStart: number; // Timestamp of the next message. If 0, there are no more messages
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

Receiving messages

RTM provides event notifications for messages, status updates, and other changes. By setting up event listeners, you can receive messages and events from subscribed channels. The following example shows how to receive messages from a User Channel:

rtm.addEventListener("message", event => {
    const channelType = event.channelType; // Channel type: "STREAM", "MESSAGE", or "USER"
    const channelName = event.channelName; // Channel name where the message comes from
    const topic = event.topicName; // Topic name, valid only if channelType is "STREAM"
    const messageType = event.messageType; // Message type: "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 details on how to add and configure event listeners, see the Event Listener section.

Presence

Presence provides the ability to monitor user online and offline status as well as historical state change notifications. With Presence, you can retrieve the following information in real time:

• Real-time event notifications when users join or leave a specified channel
• Real-time event notifications when temporary user states are set or changed
• Query which channels a specific user has joined or subscribed to
• Query which users have joined a specific channel and their temporary state data

getOnlineUsers

Description

Call the getOnlineUsers method to get real-time information about the number of online users, the list of online users, and their temporary states in a specified channel.

Method

You can call the getOnlineUsers method as follows:

getOnlineUsers(
    channelName: string,
    channelType: RtmChannelType,
    options?: PresenceOptions
): Promise<getOnlineUsersResponse>;

The options object includes 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, it returns a getOnlineUsersResponse type:

type getOnlineUsersResponse = {
    timestamp: number, // Reserved field
    totalOccupancy: number, // Total number of online users in the channel
    occupants: [{
        states: StateItem[{}],
        userId: string,
        statesCount: number
    }], // List of online users and their temporary state information
    nextPage: string // Bookmark for the next page
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

getUserChannels

Description

In scenarios such as data analysis or app debugging, you may need to know all the channels a specific user has joined or subscribed to. Call the getUserChannels method to retrieve a list of channels the user is currently in.

Method

You can call the getUserChannels method as follows:

getUserChannels(userId: string): Promise<getUserChannelsResponse>;

Basic usage

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

Return value

If the method call succeeds, it returns a getUserChannelsResponse type:

type getUserChannelsResponse = {
    timestamp: number, // Reserved field
    totalChannel: number, // Number of channels the user is in
    channels: [{
        channelName: string, // Name of the channel
        channelType: RtmChannelType // Type of the channel
    }]
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

setState

Description

To meet various business needs for user status, RTM provides the setState method to set custom temporary user states. Users can define states such as score, game status, location, mood, mic status, etc.

Once set successfully, the custom state persists in the channel as long as the user remains subscribed and online. The setState method sets a temporary user state. When the user leaves the channel or disconnects from RTM, the state is lost. To restore the state after rejoining or reconnecting, you must cache the data locally. To persist user state permanently, Agora recommends using the Storage feature's setUserMetadata method instead.

If a user updates their temporary state, RTM triggers a presence event of type remoteStateChanged in real time. You can receive this event by subscribing to the channel and enabling the corresponding event listener.

Method

You can call the setState method as follows:

setState(
    channelName: string,
    channelType: RtmChannelType,
    state: StateItem
): 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, it returns a SetStateResponse type:

type SetStateResponse = {
    timestamp: number // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

getState

Description

To get the temporary state of a specified user in a specified channel, call the getState method.

Method

You can call the getState method as follows:

getState(
    userId: string,
    channelName: string,
    channelType: RtmChannelType
): Promise<GetStateResponse>;

Basic usage

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

Return value

If the method call succeeds, it returns a GetStateResponse type:

type GetStateResponse = {
    timestamp: number, // Reserved field
    userId: string, // User ID
    states: object, // Key-value pairs of user state
    statesCount: number // Number of user states
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

removeState

Description

When a temporary user state is no longer needed, you can call the removeState method to delete one or more of your own temporary states. After successful deletion, users who subscribe to the channel and have enabled Presence event listening will receive a presence event of type remoteStateChanged. See Event Listener for details.

Method

You can call the removeState method as follows:

removeState(
    channelName: string,
    channelType: RtmChannelType,
 // Pass in state keys; if omitted, all states will be removed
    options?: RemoveStateOptions
): Promise<RemoveStateResponse>;

The options object includes the following properties:

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, it returns a RemoveStateResponse type:

type RemoveStateResponse = {
    timestamp: number // Reserved field
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

Storage

The Storage feature in RTM 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 Channel Metadata for a channel (Message Channel or Stream Channel). A channel can only have one set of metadata, but each set can contain one or more Metadata Items. If you call this method multiple times, the SDK will iterate through the Metadata Item key values and process them as follows:

• If the key values are different, new items are added in the order of the calls.
• If the key values are the same, the value from the most recent call overwrites the previous one.

After setting the Channel Metadata successfully, users who have subscribed to the channel and enabled event listening will receive a storage event of type channel. See Event Listener for details.

Channel Metadata also supports CAS (Compare And Set) version control. This method provides two independent version control fields, and you can choose one or both depending on your business needs:

• Use the majorRevision property in options to enable version validation for the entire set of Channel Metadata.
• Use the revision property in a single Metadata Item in data to enable version validation for that specific item.

When setting Channel Metadata or Metadata Items, you can control whether version validation is enabled using the version properties:

• If the version property is -1 (default), CAS validation is disabled. If the Channel Metadata or Metadata Item exists, it will be overwritten with the new value; if it does not exist, the SDK will create it.
• If the version property is a positive integer, CAS validation is enabled. The SDK will update the value only if the version matches; otherwise, it will return an error.

Method

You can call the setChannelMetadata method as follows:

setChannelMetadata(
    channelName: string,
    channelType: RtmChannelType,
    data: Metadata,
    options?: IMetadataOptions
): Promise<SetChannelMetadataResponse>;

The data object includes the following properties:

Each Metadata Item includes the following properties:

class MetaDataItem = {
    key: string, // Metadata Item key
    value: string, // Metadata Item value
    revision: number, // Metadata Item version
    updatedTs: string, // Last updated timestamp
    authorUserId: string, // User ID of the last editor
}

The options object includes 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, it returns a SetChannelMetadataResponse type:

type SetChannelMetadataResponse = {
    timestamp: number, // Reserved field
    channelName: string, // Channel name
    channelType: RtmChannelType // Channel type
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

getChannelMetadata

Description

The getChannelMetadata method retrieves the Metadata of a specified channel.

Method

You can call the getChannelMetadata method as follows:

getChannelMetadata(
    channelName: string,
    channelType: RtmChannelType
): 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, it returns a GetChannelMetadataResponse type:

type GetChannelMetadataResponse = {
    timestamp: number, // Reserved field
    channelName: string, // Channel name
    channelType: RtmChannelType, // Channel type
    majorRevision: number, // Version number
    items: MetadataItem[], // JSON object containing Metadata Item data
    itemCount: number // Number of Metadata Items
}

Each Metadata Item includes the following properties:

class MetaDataItem = {
    key: string, // Metadata Item key
    value: string, // Metadata Item value
    revision: number, // Metadata Item version
    updatedTs: string, // Last updated timestamp
    authorUserId: string // User ID of the last editor
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

removeChannelMetadata

Description

The removeChannelMetadata method deletes Channel Metadata or an array of Channel Metadata Items.

When deleting, you can control whether version validation is enabled by using the version property as follows:

• If the version property is set to -1 (default), CAS validation is disabled. If the Channel Metadata or Metadata Item exists, the SDK deletes it; if it does not exist, the SDK returns an error code.
• If the version property is a positive integer, CAS validation is enabled. If the Channel Metadata or Metadata Item exists, the SDK deletes it only after the version number passes validation; otherwise, the SDK returns an error code.

After successfully deleting Channel Metadata or a Metadata Item, users who subscribe to the channel and have enabled event listening will receive a storage event of type channel. See Event Listener for details.

Method

You can call the removeChannelMetadata method as follows:

removeChannelMetadata(
    channelName: string,
    channelType: RtmChannelType,
    options?: RemoveChannelMetadataOptions
): Promise<RemoveChannelMetadataResponse>;

The options object includes the following properties:

Each Metadata Item includes the following properties:

class MetaDataItem = {
    key: string, // Metadata Item key
    value: string, // Metadata Item value
    revision: number, // Metadata Item version
    updatedTs: string, // Last updated timestamp
    authorUserId: string, // User ID of the last editor
}

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, it returns a RemoveChannelMetadataResponse type:

type RemoveChannelMetadataResponse = {
    timestamp: number, // Reserved field
    channelName: string, // Channel name
    channelType: string // Channel type
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

updateChannelMetadata

Description

The updateChannelMetadata method updates existing Channel Metadata. Each call can update the entire Channel Metadata or one or more Metadata Items.

After a successful update, users who subscribe to the channel and have enabled event listening will receive a storage event of type channel. See Event Listener for details.

Method

You can call the updateChannelMetadata method as follows:

updateChannelMetadata(
    channelName: string,
    channelType: RtmChannelType,
    data: Metadata,
    options?: IMetadataOptions
): Promise<UpdateChannelMetadataResponse>;

The data object includes the following properties:

Each Metadata Item includes the following properties:

class MetaDataItem = {
    key: string, // Metadata Item key
    value: string, // Metadata Item value
    revision: number, // Metadata Item version
    updatedTs: string, // Last updated timestamp
    authorUserId: string, // User ID of the last editor
}

The options object includes the following properties:

Basic usage

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

Return value

If the method call succeeds, it returns an UpdateChannelMetadataResponse type:

type UpdateChannelMetadataResponse = {
    timestamp: number, // Reserved field
    channelName : string, // Channel name
    channelType : RtmChannelType // Channel type
}

If the method call fails, it returns an ErrorInfo type object:

type ErrorInfo = {
    error: boolean;        // Whether the operation failed
    reason: string;        // Name of the API that triggered the error
    operation: string;     // Operation code
    errorCode: number;     // Error code
};

You can look up the value of the errorCode field in the error code list to understand the cause and find the corresponding solution.

setUserMetadata

Description

The setUserMetadata method sets User Metadata. If this method is called multiple times, the SDK will iterate over the key values of the User Metadata Items and handle them according to the following rules:

• If the key values of the Metadata Items are different, they are added sequentially in the order of the calls.
• If the key values are the same, the value of the last Metadata set will overwrite the previous one.

Once User Metadata is successfully set, users who subscribe to the Metadata of that user and have enabled event listening will receive an event notification of type user. See Event Listening for details.

User Metadata also introduces CAS (Compare-And-Swap) version control logic. This method provides two independent version control fields, and you can configure either or both depending on your business needs:

• Use the majorRevision property in options to enable version verification for the entire group of User Metadata.
• Use the revision property in data to enable version verification for each Metadata Item in the array.

When setting User Metadata, the version attributes determine whether to enable version verification for the current call, following this logic:

• If the version attribute is set to -1 (default), CAS verification is disabled. If the User Metadata or Metadata Item already exists, the value will be overwritten with the new value; if it does not exist, it will be created.
• If the version attribute is a positive integer, CAS verification is enabled. If the User Metadata or Metadata Item already exists, the SDK will update the value only if the version matches; otherwise, the SDK will return an error code.

Method Signature

You can call the setUserMetadata method as follows:

setUserMetadata(
    data: Metadata,
    options?: SetOrUpdateUserMetadataOptions
): Promise<SetUserMetadataResponse>;

The data object contains the following properties:

Each Metadata Item contains the following properties:

class MetaDataItem = {
    key: string, // Key of the Metadata Item
    value: string, // Value of the Metadata Item
    revision: number, // Version number of the Metadata Item
    updatedTs: string, // Timestamp of the last update
    authorUserId: string, // User ID of the last editor
}

The options object 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 : true,
    addUserId : true
};
try {
    const result = await rtm.storage.setUserMetadata(data, options);
    console.log(result);
} catch (status) {
    console.log(status);
}