需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

频道

  • Web

更新时间不可用

频道是 RTM 实时网络中一种数据传输的管理机制，任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件，RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。

基于声网的能力，RTM 的频道分成三种类型以匹配不同的应用场景：

  • Message Channel：遵循行业标准的 Pub/Sub （发布/订阅）模式，频道无需提前创建，订阅频道即可在频道内收发消息。频道内的发布者和订阅者数量没有上限。
  • User Channel：基于 Pub/Sub （发布/订阅）模式的点对点消息收发。用户无需订阅频道操作，可以直接指定用户 ID 发送消息，接收消息也只需监听 message 事件。
  • Stream Channel：遵循行业类似观察者模式的 Room （房间）概念，用户需要创建并加入频道才能在频道内收发消息。频道中允许创建不同的 Topic，消息通过 Topic 进行组织和管理。

想要了解 Message Channel 和 Stream Channel 的更多用法及适用场景，可以查看：

subscribe

接口描述

RTM 提供消息、状态、事件变更等事件通知能力。通过设置事件监听，你可以接收已订阅频道中的消息和事件。关于如何添加和设置事件监听，详见事件监听章节。

通过调用 subscribe 方法，客户端可以订阅 Message Channel 并开始接收频道中的消息和事件通知。成功调用该方法后，订阅该频道且开启 Presence 事件监听的用户会收到 REMOTE_JOIN 类型的 presence 事件，详见事件监听。

从 v2.3.0 起，当 SDK 处于 CONNECTING、DISCONNECTED 或 SUSPENDED 状态时，你仍可以调用该方法。SDK 会缓存订阅请求，并在连接恢复后继续执行。

该方法返回成功表示 Message Channel 订阅已完成，但 Presence 加入可能仍在异步执行。如果订阅后需要立即调用 Presence API，应用仍需处理 Presence 服务尚未就绪或请求异步失败的结果。

信息

该方法仅适用于 Message Channel。

接口方法

你可以通过以下方式调用 subscribe 方法：

JavaScript
rtm.subscribe(
    channelName: string,
    options?: object
): Promise<SubscribeResponse>;
参数类型是否必填默认值描述
channelNamestring必填-频道名称。
optionsobject选填-订阅频道选项。
表格内容超出当前宽度，可横向滚动查看更多列。

options 包含以下属性：

属性类型是否必填默认值描述
withMessageboolean选填true是否订阅此频道中的消息事件通知。
withPresenceboolean选填true是否订阅此频道中的 Presence 事件通知。
beQuietboolean选填false

是否静默订阅频道。该参数设置为 true 时表示静默订阅频道，表现如下：

  • 不影响你接收频道内其他用户的事件通知。
  • 频道内其他用户不会收到你订阅/取消订阅频道、设置/获取/删除临时状态的事件通知。
  • 调用 whoNow 方法查询不到自己。
  • 调用 whereNow 方法查询不到自己静默订阅的频道。
withMetadataboolean选填false是否订阅此频道中的 Storage 事件通知。
withLockboolean选填false是否订阅此频道中的 Lock 事件通知。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

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);
}

返回值

如果方法调用成功，则 SDK 返回一个 SubscribeResponse 类型数据结构：

JavaScript
type SubscribeResponse = {
    timestamp : number               // 保留字段
    channelName : string             // 本次操作的频道名称
}

如果方法调用失败，则返回一个 ErrorInfo 类型数据：

JavaScript
type ErrorInfo = {
    error: boolean;                     // 本次操作是否出错
    operation: string;                  // 本次操作的 API 名称
    errorCode: number;                  // 错误码
    reason: string;                     // 错误描述
}

你可以通过检索 errorCode 字段的错误码了解错误原因，并找到对应的解决方法。

unsubscribe

接口描述

如果你不再需要关注某个频道，可调用 unsubscribe 方法取消订阅该频道。成功取消订阅该频道后，其他订阅该频道并开启事件监听的用户会收到 REMOTE_LEAVE 类型的 presence 事件通知，详见事件监听。

如果在订阅完成前对同一频道调用该方法，进行中的订阅请求会返回 RTM_ERROR_CHANNEL_SUBSCRIBE_CANCELED (-11040)，随后 SDK 完成取消订阅。取消后到达的迟到消息不会再透传给应用。

信息

该方法仅适用于 Message Channel。

接口方法

你可以通过以下方式调用 unsubscribe 方法：

JavaScript
rtm.unsubscribe(
    channelName: string
): Promise<UnsubscribeResponse>;
参数类型是否必填默认值描述
channelNamestring必填-频道名称。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

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

返回值

如果方法调用成功，则 SDK 返回一个 UnsubscribeResponse 类型数据结构：

JavaScript
type UnsubscribeResponse = {
    timestamp : number               // 保留字段
    channelName : string             // 本次操作的频道名称
}

如果方法调用失败，则返回一个 ErrorInfo 类型数据：

JavaScript
type ErrorInfo = {
    error: boolean;                     // 本次操作是否出错
    operation: string;                  // 本次操作的 API 名称
    errorCode: number;                  // 错误码
    reason: string;                     // 错误描述
}

你可以通过检索 errorCode 字段的错误码了解错误原因，并找到对应的解决方法。

createStreamChannel

接口描述

在使用 Stream Channel 之前，你需要先调用 createStreamChannel 方法创建 RTMStreamChannel 实例。成功创建实例后，你可以调用其相关方法，例如：加入频道、离开频道、发送 Topic 消息、订阅 Topic 消息等。

信息

该方法仅适用于 Stream Channel。

接口方法

你可以通过以下方式调用 createStreamChannel 方法：

JavaScript
rtm.createStreamChannel(chanelName: string): RTMStreamChannel;
参数类型是否必填默认值描述
channelNamestring必填-频道名称。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

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

返回值

一个 RTMStreamChannel 实例。

join

接口描述

成功创建 Stream Channel 后，你可以调用 join 方法加入 Stream Channel。

加入频道后，你才能进行频道相关操作。此时，订阅该频道并添加事件监听的用户会收到如下事件通知：

  • 本地用户：
    • SNAPSHOT 类型的 presence 事件通知。
    • SNAPSHOT 类型的 topic 事件通知。
  • 远端用户：REMOTE_JOIN 类型的 presence 事件通知。

信息

该方法仅适用于 Stream Channel。

接口方法

你可以通过以下方式调用 join 方法：

JavaScript
join(options?: object): Promise<JoinChannelResponse>;
参数类型是否必填默认值描述
optionsobject选填-加入频道选项。
表格内容超出当前宽度，可横向滚动查看更多列。

options 包含以下属性：

属性类型是否必填默认值描述
tokenstring选填-

加入 Stream Channel 的 Token。

  • 如果你的项目开启了 Token 鉴权，你可以填入 RTC 临时 Token 或 Token 服务器生成的 RTC 正式 Token。
  • 如果你的项目未开启 Token 鉴权，你可以不填，或填入开通了 RTC 和 RTM 服务的项目 App ID。
withPresenceboolean选填true是否订阅此频道中的 Presence 事件通知。
beQuietboolean选填false

是否静默加入频道。该参数设置为 true 时表示静默加入频道，表现如下：

  • 不影响你接收频道内其他用户的事件通知。
  • 频道内其他用户不会收到你加入/离开频道、设置/获取/删除临时状态的事件通知。
  • 调用 whoNow 方法查询不到自己。
  • 调用 whereNow 方法查询不到自己静默加入的频道。
withMetadataboolean选填false是否订阅此频道中的 Storage 事件通知。
withLockboolean选填false是否订阅此频道中的 Lock 事件通知。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

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);
}

返回值

如果方法调用成功，则 SDK 返回一个 JoinChannelResponse 类型数据结构：

JavaScript
type JoinChannelResponse = {
    timestamp : number,              // 保留字段
    channelName : string             // 本次操作的频道名称
}

如果方法调用失败，则返回一个 ErrorInfo 类型数据：

JavaScript
type ErrorInfo = {
    error: boolean;                     // 本次操作是否出错
    operation: string;                  // 本次操作的 API 名称
    errorCode: number;                  // 错误码
    reason: string;                     // 错误描述
}

你可以通过检索 errorCode 字段的错误码了解错误原因，并找到对应的解决方法。

leave

接口描述

如果你不再需要待在某个频道中，你可以调用 leave 方法离开该频道。离开后你将不再会接收到此频道中的任何消息、状态及事件通知，你在该频道中创建的 Topic 发布者的角色及你与所有 Topic 的订阅关系都将自动解除。如果想再次恢复之前的发布者角色和订阅关系，你需要调用 join 方法再次进入该频道并自行调用 joinTopic 和 subscribeTopic 方法进行设置。

成功离开频道后，频道中的远端用户会收到 REMOTE_LEAVE 类型的 presence 事件通知，详见事件监听。

信息

该方法仅适用于 Stream Channel。

接口方法

你可以通过以下方式调用 leave 方法：

JavaScript
leave(): Promise<LeaveChannelResponse>;

基本用法

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

返回值

如果方法调用成功，则 SDK 返回一个 LeaveChannelResponse 类型数据结构：

JavaScript
type LeaveChannelResponse = {
    timestamp : number               // 保留字段
    channelName : string             // 本次操作的频道名称
}

如果方法调用失败，则返回一个 ErrorInfo 类型数据：

JavaScript
type ErrorInfo = {
    error: boolean;                     // 本次操作是否出错
    operation: string;                  // 本次操作的 API 名称
    errorCode: number;                  // 错误码
    reason: string;                     // 错误描述
}

你可以通过检索 errorCode 字段的错误码了解错误原因，并找到对应的解决方法。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利