Instant Messaging API

Chat messaging, history, revocation, and read status management.

API Reference

fetchHistoryMessages()

Fetch history messages incrementally (SDK maintains an internal cursor; no duplicate messages returned).

Parameter	Type	Description
count?	number	Number of messages to fetch (default 20)

Returns: Promise<TResult<Message[]>>

Example:

// 增量加载模式：滚动到顶部时继续拉取 / Incremental loading: fetch more on scroll-to-top
const first = await classroom.fetchHistoryMessages(20);
// ... 用户滚动到顶部 / user scrolls to top ...
const more = await classroom.fetchHistoryMessages(20);
if (more.ok && more.data.length === 0) {
  // 已无更多历史消息 / No more history messages
}

---

markAllMessagesAsRead()

Mark all messages as read, resetting the unread count to zero.

Synchronously updates state.messageUnreadCount$ to 0.

Returns: void

Example:

// 用户切换到聊天面板时调用 / Call when user switches to chat panel
onActivateChatPanel(() => classroom.markAllMessagesAsRead());

---

markMessageAsRead()

Mark messages up to (and including) the specified seq as read.

Use to incrementally update read state when the chat list scrolls past a message.

Parameter	Type	Description
seq	number	Message sequence number (Message.seq)

Returns: void

Example:

// 滚动到底部时标记最新消息已读 / Mark latest as read when scrolled to bottom
onScrollToBottom(() => {
  const last = classroom.state.messageList$.get().at(-1);
  if (last) classroom.markMessageAsRead(last.seq);
});

---

revokeMessage()

Revoke a message by message ID (only revokes the caller's own messages).

For teacher/assistant to revoke others' messages, use revokeClassMessage(messageSeq) (revoke by IM seq, teacher/assistant permission).

Parameter	Type	Description
messageId	string	Message ID (the id field on Message, string)

Returns: Promise<TResult>

Example:

// 撤回自己的消息 / Revoke one's own message
await classroom.revokeMessage(message.id);

// 老师撤回他人消息 / Teacher revoking another's message
await classroom.revokeClassMessage(message.seq);

---

sendCustomMessage()

Send a custom message to the group chat (content is serialized as JSON; for business-specific extensions).

Recipients receive the raw payload via TEvent.RECV_CUSTOM_IM_MSG; the protocol structure is up to your business (e.g., reaction effects, interactive commands).

Parameter	Type	Description
data	object	Custom message data object, will be JSON.stringify'd

Returns: Promise<TResult>

Example:

// 发送 / Send
await classroom.sendCustomMessage({ type: 'reaction', emoji: '👏' });

// 接收 / Receive
classroom.on(TEvent.RECV_CUSTOM_IM_MSG, ({ data, fromUserId }) => {
  const payload = JSON.parse(data); // { type: 'reaction', emoji: '👏' }
  if (payload.type === 'reaction') showReactionAnimation(payload.emoji);
});

---

sendDirectedMessage()

Send a directed private message visible only to the specified user; excluded from the group chat list.

The recipient sees it in state.messageList$ (with a toUserId field); other members do not.

Parameter	Type	Description
toUserId	string	Target user ID
text	string	Message text

Returns: Promise<TResult>

Example:

// 老师私下提示某位学生 / Teacher privately reminds a student
await classroom.sendDirectedMessage('student_001', '请准备回答下一个问题');

---

sendFileMessage()

Send a file message to the group chat (any file format supported).

Difference from uploadCourseware(): this only sends the file link to chat — no courseware library entry and no server-side transcoding.

Parameter	Type	Description
file	File	File object to send

Returns: Promise<TResult>

Example:

const result = await classroom.sendFileMessage(file);
if (!result.ok) toast.error(result.message);

---

sendImageMessage()

Send an image message to the group chat (supports jpg/png/gif and other common formats).

The SDK internally handles COS upload + thumbnail generation + group broadcast; upload progress is not exposed.

Parameter	Type	Description
file	File	Image File object (typically from <input type="file"> or a drag event)

Returns: Promise<TResult>

Example:

// 通过 input 上传 / Upload via input
const file = (document.querySelector('input[type=file]') as HTMLInputElement).files![0];
const result = await classroom.sendImageMessage(file);
if (!result.ok) toast.error(result.message);

---

sendTextMessage()

Send a text message to the group chat, visible to all classroom participants.

Parameter	Type	Description
text	string	Text content to send

Returns: Promise<TResult>

Example:

const result = await classroom.sendTextMessage('大家好！');
if (!result.ok) toast.error(result.message);

---