直播群是一种功能强大的群聊工具。相比于普通群聊，其最大成员无上限。直播群成员之间没有固定的强关系，成员可以随时加入或离开。此外，直播群供了更加丰富的功能和工具，帮助用户更好地管理和互动。本文档介绍如何使用 IM SDK 实现直播群功能。你也可以通过阅读代码，了解直播群最佳实践。

API 接口详细文档参看 Android API 参考、iOS API 参考、Web API 参考、微信小程序 API 参考。

• 自 IM SDK v1.1.0 起支持本功能。
• IM SDK Android v1.1.5、iOS v1.1.4、Web v1.1.2、微信小程序 v1.1.2 对本功能做了如下修改：
  • 最大成员上限由 10000 人扩充至无上限。默认最大值为 10000 人，如需提高上限，请联系技术支持。
  • 支持直播群成员在线状态和人数查询。
  • 支持设置消息优先级。
  • 支持设置直播群管理员、全员禁言状态下可发言的成员。

参看构建基础应用集成使用 IM SDK，版本 v1.1.0 以上。
Web 端需要在创建实例时传入 LivePlugin。

import { BytedIM, LivePlugin } from '@volcengine/im-web-sdk';
const bytedIMInstance = new BytedIM(options, [LivePlugin]);
TypeScript

直播群首先需要创建才能正常使用，创建直播群时可以使用 BIMGroupInfo 自定义群名称，群简介，群头像和群公告，创建成功后服务端会保存此直播群信息，客户端不会持久化会话信息。

BIMGroupInfo groupInfo = new BIMGroupInfo.BIMGroupInfoBuilder()
        .name(name)
        .description(des)
        .avatarUrl(url)
        .notice(notice)
        .build();

BIMClient.getInstance().getService(BIMLiveExpandService.class).createLiveGroup(groupInfo, new BIMResultCallback<BIMConversation>() {
    @Override
    public void onSuccess(BIMConversation conversation) {
    }

    @Override
    public void onFailed(BIMErrorCode code) {
    }
});
java

BIMGroupInfo *groupInfo = [[BIMGroupInfo alloc] init];
    groupInfo.name = name;
    groupInfo.desc = desc;
    groupInfo.avatarURL = avatarURL;
    groupInfo.notice = notice;
    [[BIMClient sharedInstance] createLiveGroup:groupInfo completion:^(BIMConversation * _Nonnull conversation, BIMError * _Nullable error) {
            
    }];
objectivec

import { im_proto } from '@volcengine/im-web-sdk';
const { ConversationType } = im_proto;

const {payload: conversation} = await bytedIMInstance.createConversation({
  participants: [],
  type: ConversationType.MASS_CHAT,
  name,
})
TypeScript

当前客户端仅支持加入一个直播群，如需加入其他直播群需先退出前一个加入的直播群，加入直播群时需同时设置当前群的消息监听，事件监听和会话信息变更监听。直播群进入成功后监听生效，仅接受当前直播群消息、事件、会话变更回调，退出后所有监听失效。

/**
 * @param conversationShortId      直播群 shortId。
 * @param messageListener          直播群首发消息回调。
 * @param memberEventListener      直播群成员事件回调监听方。
 * @param conversationListListener 直播群会话更新回调。
 * @param callback                 结果回调。
 * @brief 加入直播群，加入直播群后可以收发当前群的信息，直播群不提供本地存储。
 */
BIMClient.getInstance().getService(BIMLiveExpandService.class).joinLiveGroup(conversationShortId, messageListener, memberEventListener, conversationListListener, new BIMResultCallback<BIMConversation>() {

    @Override
    public void onSuccess(BIMConversation conversation) {
 
    }

    public void onFailed(BIMErrorCode code) {

    }
});
java

[[BIMClient sharedInstance] joinLiveGroup:conversationID completion:^(BIMConversation * _Nonnull conversation, BIMError * _Nullable error) {
            
}];
objectivec

bytedIMInstance.joinLiveGroup({
  conversation,
});
TypeScript

离开直播群后，所有直播群监听将不会收到此直播群的回调，如需切换直播群可先退出当前直播群，再加入其他直播群。

BIMClient.getInstance().getService(BIMLiveExpandService.class).leaveLiveGroup(conversationShortId, new BIMSimpleCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onFailed(BIMErrorCode code) {

    }
});
java

[[BIMClient sharedInstance] leaveLiveGroup:conversationShortId completion:^(BIMConversation * _Nonnull conversation, BIMError * _Nullable error) {
            
    }];
objectivec

bytedIMInstance.leaveLiveGroup({
  conversation,
});
TypeScript

直播群支持发送文本消息，自定义消息，发送文消息示例代码如下。

BIMMessage msg = BIMClient.getInstance().createTextMessage(text);
BIMClient.getInstance().getService(BIMLiveExpandService.class).sendLiveGroupMessage(msg, bimConversation, new BIMSendCallback() {

    @Override
    public void onSuccess(BIMMessage bimMessage) {
     
    }

    @Override
    public void onError(BIMMessage bimMessage, BIMErrorCode code) {
    }
});
java

[[BIMClient sharedInstance] sendLiveGroupMessage:message conversation:conversationID completion:^(BIMMessage * _Nullable message, BIMError * _Nullable error) {
            
    }];
objectivec

const message = await bytedIMInstance.createTextMessage({
      conversation: conversation,
      content: JSON.stringify({ text: "hello" }),
});
const resp = await bytedIMInstance.sendMessage({ message }); 
TypeScript

直播群接收到的消息通过加入直播群设置的消息监听 onReceiveMessage 返回。
建议在加入直播群前（例如 SDK 实例 init 前）执行订阅操作。

/**
 * @type callback
 * @brief 消息监听方。
 */
public interface BIMLiveMessageListener {
    /**
     * @type callback
     * @brief 收到新消息。
     * @param message 消息体。
     */
    void onReceiveMessage(BIMMessage message);
    /**
     * @type callback
     * @brief 发送消息入库完成。
     * @param message 消息体。
     */
    void onSendMessage(BIMMessage message);
    /**
     * @type callback
     * @brief 收到的消息被删除。
     * @param message 消息体。
     */
    void onDeleteMessage(BIMMessage message);
    /**
     * @type callback
     * @brief 收到的消息被修改。（内容+扩展）
     * @param message 消息体。
     */
    void onUpdateMessage(BIMMessage message);
}
java

[[BIMClient sharedInstance] addMessageListener:<#(nonnull id<BIMLiveMessageListener>)#>];

/// 收到新消息
- (void)onReceiveMessage:(BIMMessage *)message {
    
}

/// 收到消息被删除
- (void)onDeleteMessage:(NSString *)msgID {

}

/// 消息被修改（内容+扩展）
- (void)onUpdateMessage:(BIMMessage *)message {
    
}

/// 发送消息请求前调用。
- (void)onSendMessage:(BIMMessage *)message {
    
}
objectivec

import { IMEvent, im_proto } from '@volcengine/im-web-sdk';
const { ConversationType } = im_proto;

// 订阅事件
const upsertHandle = bytedIMInstance.event.subscribe.(IMEvent.MessageUpsert, msg => {
  if (msg.conversationType === ConversationType.MASS_CHAT) {
     // 处理消息
  }
});

// 退订事件
bytedIMInstance.event.unsubscribe(IMEvent.MessageUpsert, upsertHandle);
TypeScript

直播群可以通过设置消息优先级保证重要消息到达率，服务端消息频控如下表所示，超出频控限制而被拦截的消息不会返回错误，不会下推到客户端。

/**
 * @param message      发送的消息
 * @param conversation 会话信息
 * @param priority     设置消息优先级
 * @param callback     结果回调。
 * @brief 发送直播群消息。
 */
public void sendLiveGroupMessage(final BIMMessage message, BIMConversation conversation, BIMMessagePriority priority, final BIMSendCallback callback)
java

/**
 * @brief 发送直播群消息。
 * @param message 消息体。
 * @param shortId 会话 shortId。
 * @param priority     设置消息优先级
 * @param completion 完成回调
 */
[[BIMClient sharedInstance] sendLiveGroupMessage:message conversation:conversationID priority:priority completion:^(BIMMessage * _Nullable message, BIMError * _Nullable error) {
    
}];
objectivec

import { im_proto } from '@volcengine/im-web-sdk';
const { MessagePriority } = im_proto;
const message = await bytedIMInstance.createTextMessage({
    conversation: conversation,
    content: JSON.stringify({ text: "hello" }),
});
// 以低优先级发送
const resp = await bytedIMInstance.sendMessage({ 
    message,
    priority: MessagePriority.LOW
});
TypeScript

直播群还支持如下功能，详情参看 API 文档。

• 获取在线成员列表

• 获取直播群列表

• 设置直播群进群黑名单

• 设置直播群禁言

• 设置直播群信息

• 转让群主

• 直播群消息携带额外数据

• 解散直播群

• 踢出在线群成员