聊天訊息

一、功能概述

聊天室模块(chat) 提供聊天功能 API，供開發者整合聊天功能。

二、取得 Socket 實例

2.1 取得聊天室 socket 實例

Api 方法： getSocket(check?: false): undefined | Socket

參數說明：

• check：無需檢查 socket 是否存在，false 類型，可選傳遞

回傳值說明： undefined | Socket 類型

三、聊天室狀態資訊

3.1 取得聊天室資訊

與使用者、聊天室相關的狀態均儲存在聊天室模組中，並透過 getChatInfo 取得聊天室狀態資訊。

Api 方法： getChatInfo(): ChatModuleInfo

回傳值說明： 聊天室狀態資訊，ChatModuleInfo 類型，詳細類型說明如下

範例：

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

四、聊天訊息來源

透過聊天室訊息事件 ChatEvents.ChatMessage、聊天歷史記錄 API getChatHistory 等取得的聊天訊息類型皆為 ChatMsgSource 類型。 所有訊息資料都有對應的訊息來源 msgSource 欄位，該欄位為 ChatMsgSource 列舉，開發者可根據該欄位顯示對應的訊息樣式。

Enum 列舉： ChatMsgSource

五、發送聊天訊息

5.1 發送文字訊息

用於觀眾進行聊天發言，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendSpeakMsg(options: SendSpeakMsgOptions): Promise<ChatMsgSpeakType>

參數說明：

• options：發言參數，SendSpeakMsgOptions 類型，必傳，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgSpeakType> 類型，詳細類型說明如下

範例：

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

5.2 發送圖片訊息

用於觀眾發送圖片訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendImageMsg(options: SendImageMsgOptions): Promise<ChatMsgImageType>

參數說明：

• options：傳送圖片參數，SendImageMsgOptions 類型，必填，詳細類型說明如下

回傳值說明： 發送到伺服器後的圖片訊息物件，Promise<ChatMsgImageType> 類型，詳細類型說明如下

範例：

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

5.3 發送表情圖片訊息

透過 getEmotionImages 方法取得表情圖片列表後，透過列表項的 id、url 發送表情圖片訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

開發者可透過 getEmotionImages 取得表情圖片列表。

Api 方法： sendEmotionImageMsg(options: SendEmotionImageMsgOptions): Promise<ChatMsgEmotionType>

參數說明：

• options：發送表情圖片參數，SendEmotionImageMsgOptions 類型，必填，詳細類型說明如下

回傳值說明： 發送到伺服器後的消息物件，Promise<ChatMsgEmotionType> 類型，詳細類型說明如下

範例：

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

5.4 發送系統訊息

用於發送系統訊息到聊天區，請注意該訊息並不會發送到伺服器端，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

Api 方法： sendSystemMsg(content: string, type?: string): void

參數說明：

• content：訊息內容，string 類型，必填

• type：string 類型，選填

範例：

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

5.5 發送自訂訊息（客戶端）

用於發送自訂訊息（客戶端），呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件，該事件回傳的資料中會對應 ChatMsgSource.CustomMessage 的聊天訊息資料

Api 方法： sendCustomMessage(options: SendCustomMessageOptions<T>): Promise<string>

從 v0.10.0 版本開始支援

參數說明：

• options：自訂訊息選項，SendCustomMessageOptions<T> 類型，必填，詳細類型說明如下

回傳值說明： 發送成功的自訂訊息 ID，Promise<string> 類型

範例：

watchCore.chat.sendCustomMessage({ data: { test: '测试' } });

5.6 插入本地贊助訊息

用於觀眾優先發送本地打賞訊息，呼叫過程中會觸發 ChatEvents.ChatMessage 聊天訊息事件。

注意，插入本地打賞訊息必定為當前觀眾。

Api 方法： insertLocalRewardChatMsg(options: InsertLocalRewardChatMsgOptions): void

從 v0.11.0 版本開始支援

參數說明：

• options：打賞訊息選項，InsertLocalRewardChatMsgOptions 類型，必填

5.7 根據 id 移除聊天訊息

Api 方法： removeChatMsg(id: string): void

從 v1.2.0 版本開始支援

參數說明：

• id：string 類型，必填

5.8 根據 id，替換對應的聊天內容

Api 方法： replaceChatMsg(id: string, chatMsg: ChatMsgType): void

從 v1.2.0 版本開始支援

參數說明：

• id：string 類型，必填

• chatMsg：ChatMsgType 類型，必填

六、監聽聊天訊息事件

當有觀眾發言、打賞等涉及聊天訊息操作時，聊天室模組會回呼 ChatEvents.ChatMessage 事件，開發者可透過監聽該事件進行聊天訊息的渲染。

由於本地發送訊息時，在發送至伺服器端前就會回呼 ChatEvents.ChatMessage 事件，此時回呼的訊息 id 即 chatMsg.id 為本地建立的 id，伺服器端回呼後，透過 ChatEvents.ReplaceChatMessage 進行訊息資料替換（包括圖片違規等均透過該事件修改訊息資料）。

import { ChatEvents, ChatMsgType } from "@polyv/live-watch-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;
  }
  // 将视图的消息节点替换...
});

七、取得聊天歷史記錄

7.1 設定聊天歷史訊息是否加密

僅 getChatHistoryByTime 方法支援加密回傳

Api 方法： setChatHistoryEncrypt(chatHistoryEncrypt: boolean): void

從 v2.9.0 版本開始支援

參數說明：

• chatHistoryEncrypt：聊天歷史訊息是否加密，boolean 類型，必填

7.2 取得聊天歷史訊息

Api 方法： getChatHistory(options?: GetChatHistoryOptions): Promise<ChatMsgType[]>

從 v2.16.0 開始棄用 透過 getChatHistory 方法取得頻道下的聊天歷史訊息。

參數說明：

• options：獲取選項，GetChatHistoryOptions 類型，選填，預設 {}，詳細類型說明如下

回傳值說明： Promise<ChatMsgType[]> 類型

範例：

// 获取 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.3 根據場次號碼分頁取得聊天歷史訊息

透過 getChatHistoryBySessionId 方法取得直播場次中的聊天歷史記錄

Api 方法： getChatHistoryBySessionId(options: GetChatHistoryBySessionIdOptions): Promise<PageContent<ChatMsgType>>

參數說明：

• options：獲取選項，GetChatHistoryBySessionIdOptions 類型，必填，詳細類型說明如下

回傳值說明： Promise<PageContent<ChatMsgType>> 類型

範例：

// 指定的场次号
const sessionId = 'gksk8f2itb';
const result = await watchCore.chat.getChatHistoryBySessionId({
  sessionId,
});
console.log('当前页', result.pageNumber);
console.log('每页数量', result.pageSize);
console.log('总条目数', result.totalItems);
console.log('总页数', result.totalPages);
console.log('消息列表', result.contents); // ChatMsgType[]

7.4 根據時間戳記取得聊天歷史訊息

Api 方法： getChatHistoryByTime(options: GetChatHistoryByTimeOptions): Promise<ChatMsgType[]>

從 v0.9.0 版本開始支援

參數說明：

• options：請求選項，GetChatHistoryByTimeOptions 類型，必填，詳細類型說明如下

回傳值說明： 訊息列表，Promise<ChatMsgType[]> 類型

八、訊息/留言上牆

8.1 取得評論上牆資料

Api 方法： getSpeakTopInfo(): undefined | ChatMsgSpeakTopType

從 v1.5.0 版本開始支援

回傳值說明： undefined | ChatMsgSpeakTopType 類型

8.2 設定評論上牆資料

Api 方法： setSpeakTop(data: ChatMsgSpeakTopType | SliceIdSpeakTop): void

從 v1.5.0 版本開始支援

參數說明：

• data：ChatMsgSpeakTopType | SliceIdSpeakTop 類型，必填

8.3 取消留言上牆

Api 方法： cancelSpeakTop(): void

從 v1.5.0 版本開始支援

九、訊息/檔案

9.1 取得頻道檔案列表

Api 方法： getChannelFileList(params: GetChannelFileListParams): Promise<GetChannelFileListResponse>

從 v2.6.0 版本開始支援

參數說明：

• params：GetChannelFileListParams 類型，必填，詳細類型說明如下

回傳值說明： Promise<GetChannelFileListResponse> 類型，詳細類型說明如下

十、其他

10.1 取得超長訊息的完整文字

講師可發送超過 2000 字的文字訊息，該訊息為超長文字訊息（透過 chatMsg.isOverLength === true 判斷），chat 提供的訊息文字只會回傳前 1000 字的訊息字串，如需顯示完整的訊息文字，可呼叫該方法取得。

Api 方法： getFullMessage(id: string, chatMsg?: ChatMsgSpeakType): Promise<string>

參數說明：

• id：聊天訊息 id，string 類型，必填

• chatMsg：聊天訊息，在未超過伺服器端聊天文字長度或請求異常時，會使用聊天訊息內容回傳 [v0.11.0 新增]，ChatMsgSpeakType 類型，選填，詳細類型說明如下

回傳值說明： Promise<string> 類型

範例：

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

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

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

10.2 取得聊天室設定

從 v1.2.0 開始可以透過 PlvChatModule.generateDefaultChatSetting() 來取得預設配置

用於獲取管理後台的聊天室設定資訊。

Api 方法： getChatSetting(): ChatSetting

回傳值說明： 聊天室設定資訊，ChatSetting 類型，詳細類型說明如下

範例：

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

10.3 轉換發言內容

透過 parseSpeakContent 將觀眾發言中的表情、連結轉換為 HTML 元素。

轉換順序：parseLink > removeEmotion > parseEmotion > parseLineBreak

Api 方法： parseSpeakContent(content: string, options?: ParseOptions): string

參數說明：

• content：發言內容，string 類型，必傳

• options：轉換選項，ParseOptions 類型，選填，詳細類型說明如下

回傳值說明： 轉換後的 HTML 字元

範例：

// 转换链接
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" title="呲牙" />

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