# Web (/en/api-reference/api-ref/signaling/web)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
The Signaling SDK API reference is divided into the following sections:
* [Setup](#setup)
* [User authentication](#user-authentication)
* [Channels](#channels)
* [Topics](#topics)
* [Messages](#messages)
* [Presence](#presence)
* [Storage](#storage)
* [Lock](#lock)
* [Enumerated types](#enumerated-types)
* [Troubleshooting](#troubleshooting)
## Setup [#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:
```html
```
* Using a package manager:
```bash
npm install agora-rtm-sdk
```
### Initialization [#initialization]
#### Description [#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.
Information
- The initialization step needs to be completed before calling the other Signaling APIs. - In order to identifying users and devices, you need to ensure that `userId` is globally unique and remains constant throughout the lifecycle of the user or device.
#### Method [#method]
You can create and initialize an instance as follows:
```javascript
class RTM(
constructor(
appId: string,
userId: string,
rtmConfig?: {
encryptionMode: string,
cipherKey: string,
salt: Uint8Array,
useStringUserId: boolean,
presenceTimeout: number,
logUpload: boolean,
logLevel: string,
cloudProxy: boolean
}
);
)
```
| Parameter | Type | Required | Default | Description |
| :---------: | :---------: | :------: | :-----: | ----------------------------------------------------------------- |
| `appId` | string | Required | - | The App ID of your Agora project on the Agora console. |
| `userId` | string | Required | - | The unique ID to identify a user or device. |
| `rtmConfig` | `RTMConfig` | Optional | - | The configuration parameters for initialization, see `RTMConfig`. |
#### Basic Usage [#basic-usage]
```javascript
const { RTM } = AgoraRTM;
const rtm = new RTM("yourAppId", "Tony");
```
#### Return Value [#return-value]
A Signaling client instance. Now you can call other Signaling APIs.
### RTMConfig [#rtmconfig]
#### Description [#description-1]
`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 [#method-1]
You can create a `RTMConfig` instance as follows:
```javascript
const { RTMConfig } = AgoraRTM;
```
| Property | Type | Required | Default | 描述 |
| :-----------------: | :--------: | :------: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `encryptionMode` | string | Optional | - | Encryption mode for end-to-end messages. If you do not set this property or set it as `NONE`, end-to-end encryption is disabled. For details, see [Encryption Mode](#enumvencryptionmod-e). |
| `salt` | Uint8Array | Optional | - | The salt required for encryption. The value must be a 32-byte binary array. |
| `cipherKey` | string | Optional | - | The key used for encryption and decryption. You must set this property if you want to enable message encryption. |
| `presenceTimeout` | number | Optional | `300` | Presence timeout in seconds, and the value range is \[5,300]. This parameter refers the delay imposed by the Signaling server before sending a `REMOTE_TIMEOUT` event notification to other users once it determines that a client has timed out. If the client reconnects and returns to the channel within the specified time, the Signaling server does not send the `REMOTE_TIMEOUT` event notification to other participants or delete the temporary user data associated with the user. |
| `logUpload` | boolean | Optional | `false` | Whether to upload logs to the server: - `true`: Enable log upload - `false`: Disable log upload. |
| `cloudProxy` | boolean | Optional | `false` | Whether to enable the cloud proxy: - `true`: Enable. - `false`: Disable. Note: This feature applies to the Message channels and User channels only. |
| `useStringUserId` | boolean | Optional | `true` | Whether to use string-type user IDs: - `true`: Use string-type user IDs. - `false`: Use number-type user IDs. If you set the property as `false`, SDK automatically converts string-type user IDs to number-type ones. In this case, the `userId` parameter must be a numeric string (for example, "123456"), otherwise initialization fails. |
| `logLevel` | string | Optional | - | Set the output level of SDK log. For details, see [log output level](#enumvlogleve-l). |
| `heartbeatInterval` | number | Optional | `5` | Heartbeat interval in seconds, and the value range is \[5,1800]. This parameter refers to the time interval at which the client sends heartbeat packets to the Signaling server. If the client fails to send heartbeat packets to the Signaling server within the specified time, the Signaling server determines that the client has timed out. Please note that this parameter affects the PCU count, which in turn affects billing. |
| `privateConfig` | object | Optional | - | When using the private deployment feature of Signaling, you need to configure this parameter. |
`privateConfig` contains the following properties:
| Property | Type | Required | Default | Description |
| :----------------: | :-------: | :------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `serviceType` | string\[] | Optional | - | Service type. See [Service Types](#enumvrtmservicetyp-e). |
| `accessPointHosts` | string\[] | Optional | - | An addresses list of servers to access the Signaling service. Only supports domain name. |
| `eventUploadHosts` | string\[] | Optional | - | An addresses list of servers for event uploading. Only supports domain name. |
| `logUploadHosts` | string\[] | Optional | - | An addresses list of servers for log uploading. Only supports domain name. |
| `originDomains` | string\[] | Optional | - | A list of domain suffixes used when connecting to the Signaling service. Only supports domain name. |
| `domainMode` | number | Optional | `1` | Domain name format of the SDK edge node server in private deployments of Signaling. The following values are supported: - `1` (default): Custom format. For example, `ip.**`. - `2`: legacy private deployment format. For example, `ip.edge.**`. |
Note
To upgrade the privately deployed Signaling Web SDK to v2.2.4 or later, set `domainMode` to `2` for compatibility. If you omit this parameter or use the default value `1`, the SDK may fail to connect to the Signaling server.
#### Basic Usage [#basic-usage-1]
```javascript
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 [#event-listeners]
#### Description [#description-2]
Signaling has a total of 8 types of event notifications, as shown in the following table:
| Event Type | Description |
| :------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `message` | Receive message event notifications in subscribed message channels and subscribed topics. |
| `presence` | Receive presence event notifications in subscribed message channels and joined stream channels. |
| `topic` | Receive all topic event notifications in joined stream channels. |
| `storage` | Receive channel metadata event notifications in subscribed message channels and joined stream channels, and the user metadata event notification of the subscribed users. |
| `lock` | Receive lock event notifications in subscribed message channels and joined stream channels. |
| `status` | (Deprecated) Receive event notifications when client connection status changes. For details, see [SDK connection state](#enumvconnectionstat-e) and [SDK connection state change reason](#enumvconnectionreaso-n). |
| `linkState` | Receive event notifications when client connection status changes. For details, see [SDK Link State Types](#enumvlinkstat-e). |
| `tokenPrivilegeWillExpire` | Receive event notifications when the client tokens are about to expire. |
#### Add event listeners [#add-event-listeners]
You can add event listeners as follows:
```javascript
// 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 [#remove-event-listeners]
You can call the `config. removedelegate[javascript]` method to remove a specified event listener.
```javascript
rtm.removeEventListener("status", statusHandler);
```
### login [#login]
#### Description [#description-3]
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 [#method-2]
You can call the `login` method as follows:
```javascript
rtm.login(options?: object): Promise;
```
| Parameter | Type | Required | Default | Description |
| :-------: | :----: | :------: | :-----: | :---------------------------------- |
| `options` | object | Optional | - | Options for logging into a channel. |
The `options` object includes the following properties:
| Property | Type | Required | Default | Description |
| :------: | :----: | :------: | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `token` | string | Optional | - | The token used for logging to the Signaling system. - If your project enables token authentication, you can provide either the [Signaling temporary token](https://agora-token-generator-demo.vercel.app/) or the Signaling token generated by your token server. See [User authentication](/en/realtime-media/rtm/build/connect-and-authenticate/authentication-workflow) and [Deploy Signaling token generator](https://github.com/AgoraIO/Tools/tree/master/DynamicKey/AgoraDynamicKey). - If your project does not enable token authentication, you can enter an empty string or the App ID of a project that enables Signaling services. |
#### Basic Usage [#basic-usage-2]
```javascript
try{
const result = await rtm.login({ token: "your_token" });
console.log(result);
} catch (status){
console.log(status);
}
```
#### Return Value [#return-value-1]
If the method call succeeds, the `LoginResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### logout [#logout]
#### Description [#description-4]
You can log out of the Signaling system if you don't need to perform any operation.
#### Method [#method-3]
You can call the `logout` method as follows:
```javascript
rtm.logout(): Promise;
```
#### Basic Usage [#basic-usage-3]
```javascript
try{
const result = await rtm.logout();
console.log(result);
} catch (status){
console.log(status);
}
```
#### Return Value [#return-value-2]
If the method call succeeds, the `LogoutResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
## User authentication [#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 [#renewtoken]
#### Description [#description-5]
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](#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 [#method-4]
You can call the `renewToken` method as follows:
```javascript
rtm.renewToken(token: string, options?: object): Promise
```
| Parameters | Type | Required | Default | Description |
| :--------: | :----: | :------: | :-----: | ------------------------------------ |
| `token` | string | Required | - | The newly generated Signaling token. |
| `options` | object | Optional | - | Token options. |
`options` contains the following properties:
| Property | Type | Required | Default | Description |
| :-----------: | :----: | :------: | :-----: | ------------------------------------------------------- |
| `channelName` | string | Optional | - | Channel name. For RTC token, this property is required. |
#### Basic usage [#basic-usage-4]
Example 1: Renew the Signaling token
```javascript
rtmClient.addEventListener('tokenPrivilegeWillExpire', async (channelName) => {
if(!channelName){
// The RTM Token is about to expire
const newToken = "";
await rtmClient.renewToken(newToken);
}
});
```
Example 2: Renew the RTC token
```javascript
rtmClient.addEventListener('tokenPrivilegeWillExpire', async (streamChannelName) => {
if(streamChannelName){
// The RTC Token is about to expire
const newToken = "";
await rtmClient.renewToken(newToken, {
channelName: streamChannelName
});
}
});
```
#### Return value [#return-value-3]
If the method call succeeds, the `RenewTokenResponse` response as follows is returned:
```javascript
type RenewTokenResponse = {
timestamp: number , // Timestamp of the successful operation.
}
```
If the method call fails, the `ErrorInfo` response as follows is returned:
```javascript
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](#error-codes-table).
## Channels [#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 [#subscribetopic]
#### Description [#description-6]
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](#event-listeners).
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.
Information
This method only applies to the message channel.
#### Method [#method-5]
You can call the `subscribeTopic` method as follows:
```javascript
rtm.subscribe(
channelName: string,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :-----------: | :----: | :------: | :-----: | :--------------------------------- |
| `channelName` | string | Yes | - | The channel name. |
| `options` | object | Optional | - | Options for subscribing a channel. |
The `options` object includes the following properties:
| Property | Type | Required | Default | Description |
| :------------: | :-----: | :------: | :-----: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `withMessage` | boolean | Optional | `true` | Whether to subscribe to message event notifications in the channel. |
| `withPresence` | boolean | Optional | `true` | Whether to subscribe to presence event notifications in the channel. |
| `beQuiet` | boolean | Optional | `false` | Whether to set the silent mode. If you set this parameter as `true`, the SDK has the following behaviors: - You can still receive other users' event notifications. - Event notifications related to your channel activity such as subscribing or unsubscribing the channel, and actions related to setting, getting, or deleting temporary user states, can not be broadcasted to other users. - When calling the `getOnlineUsers` method, your information can not be found. - When calling the `getUserChannels` method, channels that you subscribe in silent mode can not be detected. |
| `withMetadata` | boolean | Optional | `false` | Whether to subscribe to storage event notifications in the channel. |
| `withLock` | boolean | Optional | `false` | Whether to subscribe to lock event notifications in the channel. |
#### Basic usage [#basic-usage-5]
```javascript
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 [#return-value-4]
If the method call succeeds, the `SubscribeTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### unsubscribeTopic [#unsubscribetopic]
#### Description [#description-7]
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](#event-listeners).
Information
This method only applies to the message channel.
#### Method [#method-6]
You can call the `unsubscribeTopic` method as follows:
```javascript
rtm.unsubscribe(
channelName: string
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :-----------: | :----: | :------: | :-----: | :---------------- |
| `channelName` | string | Yes | - | The channel name. |
#### Basic usage [#basic-usage-6]
```javascript
try {
const result = await rtm.unsubscribe("chat_room");
console.log(result);
} catch (status) {
console.log(status);
}
```
#### Return value [#return-value-5]
If the method call succeeds, the `UnsubscribeTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### createAgoraRtmClient [#createagorartmclient]
#### Description [#description-8]
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.
Information
This method only applies to the stream channel.
#### Method [#method-7]
You can call the `createAgoraRtmClient` method as follows:
```javascript
rtm.createStreamChannel(chanelName: string): RTMStreamChannel;
```
| Parameter | Type | Required | Default | Description |
| :-----------: | :----: | :------: | :-----: | :---------------- |
| `channelName` | string | Yes | - | The channel name. |
#### Basic usage [#basic-usage-7]
```javascript
try{
const Loc_stChannel = await rtm.createStreamChannel( "Location");
console.log("Create Stream Channel success!: ");
} catch (status){
console.log(status);
}
```
#### Return value [#return-value-6]
An `RTMStreamChannel` instance.
### joinTopic [#jointopic]
#### Description [#description-9]
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.
* `topic`event notification with the `SNAPSHOT` type.
* Remote users: `presence` event notification with the `REMOTE_JOIN` type.
Information
This method only applies to the stream channel.
#### Method [#method-8]
You can call the `joinTopic` method as follows:
```javascript
join(options?: object): Promise;
```
| Parameter | Type | Required | Default | Description |
| :-------: | :----: | :------: | :-----: | :----------------------------- |
| `options` | object | Optional | - | Options for joining a channel. |
The `options` object includes the following properties:
| Property | Type | Required | Default | Description |
| :------------: | :-----: | :------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | string | Optional | - | The token used for joining a stream channel, which is currently the same as the RTC token. |
| `withPresence` | boolean | Optional | `true` | Whether to subscribe to presence event notifications in the channel. |
| `beQuiet` | boolean | Optional | `false` | Whether to set the silent mode. If you set this parameter as `true`, the SDK has the following behaviors: - You can still receive other users' event notifications. - Event notifications related to your channel activity such as joining or leaving the channel, and actions related to setting, getting, or deleting temporary user states, can not be broadcasted to other users. - When calling the `getOnlineUsers` method, your information can not be found. - When calling the `getUserChannels` method, channels that you subscribe in silent mode can not be detected. |
| `withMetadata` | boolean | Optional | `false` | Whether to subscribe to storage event notifications in the channel. |
| `withLock` | boolean | Optional | `false` | Whether to subscribe to lock event notifications in the channel. |
#### Basic usage [#basic-usage-8]
```javascript
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 [#return-value-7]
If the method call succeeds, the `JoinTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### leaveTopic [#leavetopic]
#### Description [#description-10]
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](#event-listeners).
Information
This method only applies to the stream channel.
#### Method [#method-9]
You can call the `leaveTopic` method as follows:
```javascript
leave(): Promise;
```
#### Basic usage [#basic-usage-9]
```javascript
try{
const result = await streamChannel.leave();
console.log(result);
} catch (status){
console.log(status);
}
```
#### Return value [#return-value-8]
If the method call succeeds, the `LeaveTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
## Topics [#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.
Information
Topics only exist in stream channels. Therefore, before using relevant features, users need to create an `RTMStreamChannel` instance.
For more information on the features of topic, click the following card:
### joinTopic [#jointopic-1]
#### Description [#description-11]
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.
Information
* Currently, Signaling supports a single client joining up to 8 topics in the same stream channel at a time.
* Before joining a topic, a user need to create an `RTMStreamChannel` instance and call the `joinTopic` method to join the stream channel.
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](#event-listeners).
#### Method [#method-10]
You can call the `joinTopic` method as follows:
```javascript
joinTopic(
topicName: string,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :---------: | :----: | :------: | :-----: | :--------------------: |
| `topicName` | string | Yes | - | The topic name. |
| `options` | object | Optional | - | The reserved property. |
#### Basic usage [#basic-usage-10]
```javascript
try {
const result = await stChannel.joinTopic( "gesture", options);
console.log( result);
} catch (status) {
console.log(status);
}
```
#### Return value [#return-value-9]
If the method call succeeds, the `JoinTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### publishTopicMessage [#publishtopicmessage]
#### Description [#description-12]
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](#setup).
#### Method [#method-11]
You can call the `publishTopicMessage` method as follows:
```javascript
publishTopicMessage(
topicName: string,
message: string | Uint8Array,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :---------: | :------------------: | :------: | :-----: | :------------------------------------------------------- |
| `topicName` | string | Required | - | The topic name. |
| `message` | string \| Uint8Array | Required | - | The message payload. Supports string or Uint8Array type. |
| `options` | object | Optional | - | The message options. |
The `options` object includes the following property:
| Property | Type | Required | Default | Description |
| :----------: | :----: | :------: | :-----: | :----------------------------------------------- |
| `customType` | string | Optional | - | A user-defined field. Only supports string type. |
#### Basic usage [#basic-usage-11]
Example 1: Send string messages to a specified channel.
```javascript
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.
```javascript
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 [#return-value-10]
If the method call succeeds, the `PublishTopicMessageResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### leaveTopic [#leavetopic-1]
#### Description [#description-13]
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](#event-listeners).
#### Method [#method-12]
You can call the `leaveTopic` method as follows:
```javascript
leaveTopic(topicName: string): Promise;
```
| Parameter | Type | Required | Default | Description |
| :---------: | :----: | :------: | :-----: | :-------------- |
| `topicName` | string | Required | - | The topic name. |
#### Basic usage [#basic-usage-12]
```javascript
try {
const result = await stChannel.leaveTopic("gesture");
console.log(result);
} catch (status) {
console.log(status);
}
```
#### Return value [#return-value-11]
If the method call succeeds, the `LeaveTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### subscribeTopic [#subscribetopic-1]
#### Description [#description-14]
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 [#method-13]
You can call the `subscribeTopic` method as follows:
```javascript
subscribeTopic(
topicName: string,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :---------: | :----: | :------: | :-----: | :----------------------- |
| `topicName` | string | Required | - | The topic name. |
| `options` | object | Optional | - | The subscribing options. |
The `options` object includes the following property:
| Property | Type | Required | Default | Description |
| :------: | :-------: | :------: | :-----: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users` | string\[] | Optional | - | A list of user IDs of message publishers that you want to subscribe to. If you do not set this property, you can randomly subscribe to up to 64 users by default. |
#### Basic usage [#basic-usage-13]
Example 1: Subscribe to a specified message publisher in a topic.
```javascript
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.
```javascript
try {
const result = await stChannel.subscribeTopic("Gesture");
console.log(result);
}catch(status) {
console.log(status);
}
```
#### Return value [#return-value-12]
If the method call succeeds, the `SubscribeTopicResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### unsubscribeTopic [#unsubscribetopic-1]
#### Description [#description-15]
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 [#method-14]
You can call the `unsubscribeTopic` method as follows:
```javascript
unsubscribeTopic(
topicName: string,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :---------: | :----: | :------: | :-----: | :------------------------- |
| `topicName` | string | Required | - | The topic name. |
| `options` | object | Optional | - | The unsubscribing options. |
The `options` object includes the following property:
| Property | Type | Required | Default | Description |
| :------: | :-------: | :------: | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `users` | string\[] | Optional | - | A list of user IDs of message publishers that you want to unsubscribe from. If you do not set this property, you can unsubscribe from the entire topic. |
#### Basic usage [#basic-usage-14]
Example 1: Unsubscribe from a specified message publisher in a topic.
```javascript
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.
```javascript
try {
const result = await rtm.unsubscribeTopic("Gesture");
console.log("unsubscribe topic success: ", result);
} catch (status) {
console.log("unsubscribe topic failed: ", result);
}
```
#### Return value [#return-value-13]
If the method call succeeds, the `UnsubscribeTopicResponse` response as follows is returned:
```javascript
type UnsubscribeTopicResponse = {
timestamp: number , // Timestamp of the successful operation.
}
```
If the method call fails, the `ErrorInfo` response as follows is returned:
```javascript
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](#error-codes-table).
## Messages [#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 [#publishtopicmessage-1]
#### Description [#description-16]
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.
Information
The following practices can effectively improve the reliability of message transmission: - The message payload should be within 32 KB; otherwise, the sending will fail. - The upper limit of the rate at which messages are sent to a single channel is 60 QPS. If the sending rate exceeds the limit, some messages will be discarded. A lower rate is better, as long as the requirements are met.
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](#event-listeners).
#### Method [#method-15]
You can call the `publishTopicMessage` method as follows:
```javascript
rtm.publish(
channelName: string,
message: string | Uint8Array,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :-----------: | :------------------: | :------: | :-----: | :------------------------------------------------------------------------------------------------------------------------- |
| `message` | string \| Uint8Array | Required | - | The message payload. Supports string or Uint8Array type. |
| `channelName` | string | Required | - | Fill in a channel name to send messages in a specified channel, or fill in a user ID to send messages to a specified user. |
| `options` | object | Optional | - | The message options. |
The `options` object includes the following property:
| Property | Type | Required | Default | Description |
| :-----------: | :----: | :------: | :-----: | :-------------------------------------------------------------- |
| `customType` | string | Optional | - | A user-defined field. Only supports string type. |
| `channelType` | string | Optional | - | Channel type. For details, see [Channel Types](#channel-types). |
#### Basic usage [#basic-usage-15]
Example 1: Send string messages to a specified channel.
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
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);
}
```
Information
After successfully calling this method, the SDK triggers a `message` event notification. Users who subscribe to the channel and enable event listener can receive this event notification. For details, see [Event Listener](#event-listeners).
#### Return value [#return-value-14]
If the method call succeeds, the `PublishTopicMessageResponse` response as follows is returned:
```javascript
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:
```javascript
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](#error-codes-table).
### Receive [#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.
```javascript
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](#event-listeners).
## Presence [#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.
Information
**Presence** applies to both message channels and stream channels.
### getOnlineUsers [#getonlineusers]
#### Description [#description-17]
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 [#method-16]
You can call the `getOnlineUsers` method as follows:
```javascript
rtm.presence.getOnlineUsers(
channelName: string,
channelType: string,
options?: object
): Promise;
```
| Parameter | Type | Required | Default | Description |
| :-----------: | :----: | :------: | :-----: | :-------------------------------------------------------------- |
| `channelName` | string | Required | - | Channel name. |
| `channelType` | string | Required | - | Channel type. For details, see [Channel Types](#channel-types). |
| `options` | object | Optional | - | Query options. |
`options` contains the following properties:
| Property | Type | Required | Default | Description |
| :--------------: | :-----: | :------: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `includedUserId` | boolean | Optional | `true` | Whether the returned result contains the user ID of online users. |
| `includedState` | boolean | Optional | `false` | Whether the returned result contains the temporary user state of online users. |
| `page` | string | Optional | - | Page number of the returned result. If you do not provide this property, the SDK returns the first page by default. You can check whether there is next page in the `nextPage` property of the returned result. |
#### Basic Usage [#basic-usage-16]
```javascript
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 [#return-value-15]
If the method call succeeds, the `WhoNowResponse` response as follows is returned:
```javascript
type getOnlineUsersResponse = {
timestamp: number , // Timestamp of the successful operation.
totalOccupancy : number , // Number of the online users in the channel.
occupants : Array