Chat Messages

I. Feature Overview

聊天室模块(chat) provides a chat API for developers to integrate chat functionality.

2. Chat Room Status Information

2.1 Retrieving Chat Room Information

All states related to users and chat rooms are stored in the chat room module, and the chat room state information is obtained through getChatInfo.

Api Method: getChatInfo(): ChatModuleInfo

Return Value Description: Chat room status information, ChatModuleInfo type. Detailed type description is as follows:

Example:

const chatInfo = watchCore.chat.getChatInfo();
console.log('房间是否被关闭', chatInfo.chatRoomIsClosed);
console.log('当前用户是否被禁言', chatInfo.isShield);

III. Source of Chat Messages

The chat message types obtained through the chat room message event ChatEvents.ChatMessage, chat history API getChatHistory, etc., are all types under the ChatMsgType namespace.

All message data has a corresponding message source msgSource field, which is an ChatMsgSource enum. Developers can display the corresponding message style based on this field.

Enum: ChatMsgSource

4. Sending Chat Messages

4.1 Sending Text Messages

Used for audience members to send chat messages. Calling this will trigger the ChatEvents.ChatMessage chat message event.

Api Method: sendSpeakMsg(options: SendSpeakMsgOptions): Promise<ChatMsgSpeakType>

Parameter Description:

• options: Speech parameters, type SendSpeakMsgOptions, required. Detailed type description is as follows:

Return Value Description: The message object after being sent to the server, of type Promise<ChatMsgSpeakType>. The detailed type description is as follows:

Example:

import { ChatMsgQuoteOriginType, ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';
// 发送的文本
const content = '今天天气真好[呲牙][酷]';
// 被回复的消息
const currentQuoteMsg: ChatMsgSpeakType | undefined = undefined;
// 发送消息
watchCore.chat.sendSpeakMsg({
  content,
  quoteMsg: currentQuoteMsg,
});

4.2 Sending Image Messages

Used for sending image messages from the audience. During the call, the ChatEvents.ChatMessage chat message event will be triggered.

Api Method: sendImageMsg(options: SendImageMsgOptions): Promise<ChatMsgImageType>

Parameter Description:

• options: Image sending parameters, SendImageMsgOptions type, required. Detailed type description is as follows:

Return Value Description: The message object after being sent to the server, of type Promise<ChatMsgImageType>, with detailed type description as follows:

Example:

import { uuidV4 } from '@polyv/utils/es/string';
// 图片 id
const imageId = uuidV4();
// 图片地址
const imageUrl = '发送到图片地址，需要带有协议';
// 图片地址
const size = { width: 200, height: 100 };
// 发送图片消息
watchCore.chat.sendImageMsg({ imageId, imageUrl, size });

4.3 Sending Emoticon Image Messages

After obtaining the emoji image list via the getEmotionImages method, send emoji image messages using id and url of the list items. During the call, the ChatEvents.ChatMessage chat message event will be triggered.

Developers can obtain the list of emoji images via getEmotionImages.

Api Method: sendEmotionImageMsg(options: SendEmotionImageMsgOptions): Promise<ChatMsgEmotionType>

Parameter Description:

• options: Parameters for sending emoji images, type SendEmotionImageMsgOptions, required. Detailed type description is as follows:

Return Value Description: The message object after being sent to the server, of type Promise<ChatMsgEmotionType>. The detailed type description is as follows:

Example:

// 获取表情图片列表
const emotionImages = await watchCore.chat.getEmotionImages();
// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({ emotionId: item.id, emotionUrl: item.url });

4.4 Sending System Messages

Used to send system messages to the chat area. Note that this message is not sent to the server. Calling this will trigger the ChatEvents.ChatMessage chat message event.

Api Method: sendSystemMsg(content: string): void

Parameter Description:

• content: Message content, string type, required.

Example:

watchCore.chat.sendSystemMsg('聊天室已关闭');

V. Listening to Chat Message Events

When there are audience interactions such as speaking or tipping that involve chat message operations, the chat room module will trigger the ChatEvents.ChatMessage event. Developers can listen to this event to render chat messages.

Since local messages trigger the ChatEvents.ChatMessage event callback before being sent to the server, the message ID at this point, i.e., chatMsg.id, is a locally generated ID. After the server callback, message data is replaced via ChatEvents.ReplaceChatMessage (including modifications for violations such as inappropriate images, all handled through this event).

import { ChatEvents, ChatMsgType } from '@polyv/live-watch-miniprogram-sdk';

// 聊天消息列表
const chatMsgList: ChatMsgType[] = [];

// 聊天消息事件
watchCore.chat.eventEmitter.on(ChatEvents.ChatMessage, (data) => {
  // 插入到聊天消息列表
  chatMsgList.push(data.chatMsg);
  // 渲染聊天消息...
});

// 替换聊天消息数据事件
watchCore.chat.eventEmitter.on(ChatEvents.ReplaceChatMessage, (data) => {
  // 需要被替换的消息 id
  const replaceId = data.id;
  // 新的消息对象
  const chatMsg = data.chatMsg;

  const index = chatMsgList.findIndex((item) => item.id === replaceId);
  if (index !== -1) {
    chatMsgList[index] = chatMsg;
  }
  // 将视图的消息节点替换...
});

6. Retrieving Chat History

6.1 Retrieving Chat History Messages

Obtain the chat history messages under the channel using the getChatHistory method.

Api Method: getChatHistory(options?: GetChatHistoryOptions): Promise<ChatMsgType[]>

Parameter Description:

• options: Get options, type GetChatHistoryOptions, optional, default {}, detailed type description as follows

Return Value Description: Promise<ChatMsgType[]> type

Example:

// 获取 0 ～ 19 条消息
const historyData = await watchCore.chat.getChatHistory({
  start: 0,
  end: 19,
});
// 返回数据示例，类型为：ChatMsgType[]
[{
  id: '5191c230-c6c4-11ed-8c31-23e8ced55946',
  time: 1679278200247,
  msgSource: 'speak',
  content: '今天天气真好[呲牙][酷]',
  user: {
    userId: '18012345678',
    nick: '小明',
    pic: '头像地址',
  },
}]

VII. Pinning Messages/Comments

7.1 Retrieving Chat Room Information

All states related to users and chat rooms are stored in the chat room module, and the chat room state information is obtained through getChatInfo.

Api Method: getChatInfo(): ChatModuleInfo

Return Value Description: Chat room status information, ChatModuleInfo type. Detailed type description is as follows:

Example:

const chatInfo = watchCore.chat.getChatInfo();
console.log('房间是否被关闭', chatInfo.chatRoomIsClosed);
console.log('当前用户是否被禁言', chatInfo.isShield);

7.2 Get Chat Room Settings

Used to retrieve the chat room settings information from the admin backend.

Api Method: getChatSetting(): ChatSetting

Return Value Description: Chat room settings information, ChatSetting type. Detailed type description is as follows:

Example:

const setting = watchCore.chat.getChatSetting();
console.log('观看页聊天室开关', setting.watchChatEnabled);
console.log('是否显示翻译功能', setting.chatTranslateEnabled);

7.3 Retrieving Chat History Messages

Obtain the chat history messages under the channel using the getChatHistory method.

Api Method: getChatHistory(options?: GetChatHistoryOptions): Promise<ChatMsgType[]>

Parameter Description:

• options: Get options, type GetChatHistoryOptions, optional, default {}, detailed type description as follows

Return Value Description: Promise<ChatMsgType[]> type

Example:

// 获取 0 ～ 19 条消息
const historyData = await watchCore.chat.getChatHistory({
  start: 0,
  end: 19,
});
// 返回数据示例，类型为：ChatMsgType[]
[{
  id: '5191c230-c6c4-11ed-8c31-23e8ced55946',
  time: 1679278200247,
  msgSource: 'speak',
  content: '今天天气真好[呲牙][酷]',
  user: {
    userId: '18012345678',
    nick: '小明',
    pic: '头像地址',
  },
}]

7.4 Getting Real-Time Like Count

After receiving a user like event, you can use this method to obtain the real-time like count. Monitor changes in the like count through the ChatEvents.ChatLikeCountChange event.

Api Method: getRealtimeLikes(): number

Example:

const realtimeLikes = watchCore.chat.getRealtimeLikes();
console.log('实时点赞数：', realtimeLikes);

7.5 Sending Like Count

Api Method: sendLike(times: number): Promise<number>

Parameter Description:

• times: Number of likes, number type, required.

Return Value Description: Promise<number> type

7.6 Get Emoticon Image List

Use getEmotionImages to retrieve the title image list. After obtaining the list, use id and url to call ChatModule.sendEmotionImageMsg to send an emoji image message.

Api Method: getEmotionImages(): Promise<EmotionImageData[]>

Return Value Description: Promise<EmotionImageData[]> type

Example:

const emotionImages = await watchCore.chat.getEmotionImages();
// 表情图片列表数据示例：
[{ id: '0', title: '收到', url: 'https://s2.videocc.net/default-img/img-emotion/v1/shoudao.png' }]

// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({
  emotionId: item.id,
  emotionUrl: item.url,
});

7.7 Sending Text Messages

Used for audience members to send chat messages. Calling this will trigger the ChatEvents.ChatMessage chat message event.

Api Method: sendSpeakMsg(options: SendSpeakMsgOptions): Promise<ChatMsgSpeakType>

Parameter Description:

• options: Speech parameters, SendSpeakMsgOptions type, required. Detailed type description is as follows:

Return Value Description: The message object after being sent to the server, of type Promise<ChatMsgSpeakType>. The detailed type description is as follows:

Example:

import { ChatMsgQuoteOriginType, ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';
// 发送的文本
const content = '今天天气真好[呲牙][酷]';
// 被回复的消息
const currentQuoteMsg: ChatMsgSpeakType | undefined = undefined;
// 发送消息
watchCore.chat.sendSpeakMsg({
  content,
  quoteMsg: currentQuoteMsg,
});

7.8 Sending Image Messages

Used for sending image messages from the audience. During the call, the ChatEvents.ChatMessage chat message event will be triggered.

Api Method: sendImageMsg(options: SendImageMsgOptions): Promise<ChatMsgImageType>

Parameter Description:

• options: Image sending parameters, SendImageMsgOptions type, required. Detailed type description is as follows:

Return Value Description: The message object after being sent to the server, of type Promise<ChatMsgImageType>. The detailed type description is as follows:

Example:

import { uuidV4 } from '@polyv/utils/es/string';
// 图片 id
const imageId = uuidV4();
// 图片地址
const imageUrl = '发送到图片地址，需要带有协议';
// 图片地址
const size = { width: 200, height: 100 };
// 发送图片消息
watchCore.chat.sendImageMsg({ imageId, imageUrl, size });

7.9 Sending Emoticon Image Messages

After obtaining the emoji image list via the getEmotionImages method, send emoji image messages using id and url of the list items. During the call, the ChatEvents.ChatMessage chat message event will be triggered.

Developers can obtain the list of emoji images via getEmotionImages.

Api Method: sendEmotionImageMsg(options: SendEmotionImageMsgOptions): Promise<ChatMsgEmotionType>

Parameter Description:

• options: Parameters for sending emoji images, type SendEmotionImageMsgOptions, required. Detailed type description is as follows:

Return Value Description: The message object after being sent to the server, of type Promise<ChatMsgEmotionType>. The detailed type description is as follows:

Example:

// 获取表情图片列表
const emotionImages = await watchCore.chat.getEmotionImages();
// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({ emotionId: item.id, emotionUrl: item.url });

7.10 Sending System Messages

Used to send system messages to the chat area. Note that this message is not sent to the server; calling it will trigger the ChatEvents.ChatMessage chat message event.

Api Method: sendSystemMsg(content: string): void

Parameter Description:

• content: Message content, string type, required.

Example:

watchCore.chat.sendSystemMsg('聊天室已关闭');

7.11 Retrieving the Full Text of an Overly Long Message

Instructors can send text messages exceeding 2,000 characters, which are considered extra-long text messages (determined by chatMsg.isOverLength === true). chat only returns the first 500 characters of the message string. To display the full message text, you can call this method to retrieve it.

Api Method: getFullMessage(id: string): Promise<string>

Parameter Description:

• id: Message ID, string type, required

Return Value Description: Promise<string> type

Example:

import { ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';

async function getFullMessageText(chatMsg: ChatMsgSpeakType): Promise<string> {
  if (!chatMsg.isOverLength) {
    throw new Error('该消息非超长文本');
  }

  const result = await watchCore.chat.getFullMessage(chatMsg.id);
  console.log('完整的文本', result);
  return result;
}

7.12 Get Real-Time Online User Count in Chat Room

Obtain the real-time online user count via getOnlineUserCount, and listen for changes in the chat room online user count through the ChatEvents.OnlineUserCountChange event.

Api Method: getOnlineUserCount(): number

Return Value Description: Real-time online user count

Example:

const onlineUserCount = watchCore.chat.getOnlineUserCount();
console.log('当前聊天室在线人数：', onlineUserCount);

// 监听人数改变
watchCore.chat.eventEmitter.on(ChatEvents.OnlineUserCountChange, (data) => {
  console.log('在线人数改变：', data.onlineUserCount);
});

7.13 Converting Speech Content

Convert the emojis and links in the audience's speech into HTML elements using parseSpeakContent.

Conversion order: parseLink > removeEmotion > parseEmotion > parseLineBreak

Api Method: parseSpeakContent(content: string, options?: ParseOptions): string

Parameter Description:

• content: The content of the speech, of type string, required.

• options: Conversion options, type ParseOptions, optional, detailed type description as follows

Return Value Description: Converted HTML characters

Example:

// 转换链接
watchCore.chat.parseSpeakContent('这是我们的官网地址：https://www.polyv.net/', { parseLink: true });
// 转换后的字符串：这是我们的官网地址：<a target="_blank" rel="noopener" href="https://www.polyv.net/">https://www.polyv.net/</a>

// 移除表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { removeEmotion: true });
// 转换后的字符串：今天天气真好

// 转换表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { parseEmotion: true });
// 转换后的字符串：今天天气真好<img src="黄脸表情图片地址" alt="呲牙" class="plv-emotion-img" />

// 将换行符转成 <br />
watchCore.chat.parseSpeakContent('这是一段文字\n这是另一段文字', { parseLineBreak: true });
// 转换后的字符串：这是一段文字<br />这是另一段文字

7.14 Get Emoji List Data

Api Method: getEmotionFaceList(): EmotionListItem[]

Return Value Description: EmotionListItem[] type

7.15 Splitting Text and Emojis in Chat Messages

Api Method: splitTextAndEmotion(content: string): TextSplitResultItem[]

Parameter Description:

• content: Speech content, type string, required

Return Value Description: TextSplitResultItem[] type

8. Miscellaneous

8.1 Get Emoticon Image List

Use getEmotionImages to retrieve the title image list. After obtaining the list, use id and url to call ChatModule.sendEmotionImageMsg to send an emoji image message.

Api Method: getEmotionImages(): Promise<EmotionImageData[]>

Return Value Description: Promise<EmotionImageData[]> type

Example:

const emotionImages = await watchCore.chat.getEmotionImages();
// 表情图片列表数据示例：
[{ id: '0', title: '收到', url: 'https://s2.videocc.net/default-img/img-emotion/v1/shoudao.png' }]

// 发送表情图片
const item = emotionImages[2];
watchCore.chat.sendEmotionImageMsg({
  emotionId: item.id,
  emotionUrl: item.url,
});

8.2 Retrieving the Full Text of an Overly Long Message

Instructors can send text messages exceeding 2,000 characters, which are considered extra-long text messages (determined by chatMsg.isOverLength === true). chat only returns the first 500 characters of the message string. To display the full message text, you can call this method to retrieve it.

Api Method: getFullMessage(id: string): Promise<string>

Parameter Description:

• id: Message ID, string type, required.

Return Value Description: Promise<string> type

Example:

import { ChatMsgSpeakType } from '@polyv/live-watch-miniprogram-sdk';

async function getFullMessageText(chatMsg: ChatMsgSpeakType): Promise<string> {
  if (!chatMsg.isOverLength) {
    throw new Error('该消息非超长文本');
  }

  const result = await watchCore.chat.getFullMessage(chatMsg.id);
  console.log('完整的文本', result);
  return result;
}

8.3 Get Chat Room Settings

Used to retrieve the chat room settings information of the admin backend.

Api Method: getChatSetting(): ChatSetting

Return Value Description: Chat room settings information, type ChatSetting, detailed type description is as follows

Example:

const setting = watchCore.chat.getChatSetting();
console.log('观看页聊天室开关', setting.watchChatEnabled);
console.log('是否显示翻译功能', setting.chatTranslateEnabled);

8.4 Converting Speech Content

Convert the emojis and links in the audience's speech into HTML elements using parseSpeakContent.

Conversion order: parseLink > removeEmotion > parseEmotion > parseLineBreak

Api Method: parseSpeakContent(content: string, options?: ParseOptions): string

Parameter Description:

• content: The content of the speech, type string, required.

• options: Conversion options, type ParseOptions, optional, detailed type description as follows

Return Value Description: Converted HTML characters

Example:

// 转换链接
watchCore.chat.parseSpeakContent('这是我们的官网地址：https://www.polyv.net/', { parseLink: true });
// 转换后的字符串：这是我们的官网地址：<a target="_blank" rel="noopener" href="https://www.polyv.net/">https://www.polyv.net/</a>

// 移除表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { removeEmotion: true });
// 转换后的字符串：今天天气真好

// 转换表情
watchCore.chat.parseSpeakContent('今天天气真好[呲牙]', { parseEmotion: true });
// 转换后的字符串：今天天气真好<img src="黄脸表情图片地址" alt="呲牙" class="plv-emotion-img" />

// 将换行符转成 <br />
watchCore.chat.parseSpeakContent('这是一段文字\n这是另一段文字', { parseLineBreak: true });
// 转换后的字符串：这是一段文字<br />这是另一段文字

8.5 Getting the Real-Time Online User Count of a Chat Room

Obtain the real-time online user count via getOnlineUserCount, and listen for changes in the chat room's online user count through the ChatEvents.OnlineUserCountChange event.

Api Method: getOnlineUserCount(): number

Return Value Description: Real-time online user count

Example:

const onlineUserCount = watchCore.chat.getOnlineUserCount();
console.log('当前聊天室在线人数：', onlineUserCount);

// 监听人数改变
watchCore.chat.eventEmitter.on(ChatEvents.OnlineUserCountChange, (data) => {
  console.log('在线人数改变：', data.onlineUserCount);
});