@tencent-rtc/mcp 1.6.8 → 1.7.1

package/resource/knowledge/callkit/best-practice/common/callkit-get-roomid.md

@@ -0,0 +1,78 @@
+---
+title: "How to get the roomID during a TUICallKit Call（获取 TUICallKit 房间号）"
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, roomID, room ID, ON_CALL_BEGIN, ON_CALL_END, callengine, get room ID, call room ID, Roomid, onCallBegin]
+version_range: ">=4.0.0"
+---
+
+# How to Get the Room ID During a TUICallKit Call
+
+## 1. Key Takeaways
+
+- To get the call room ID: listen to TUICallEngine events (`ON_CALL_BEGIN`, `ON_CALL_END`, etc.) and read `event.roomID`, which is the current call's room ID.
+- First obtain the TUICallEngine instance via `TUICallKitAPI.getTUICallEngineInstance()`, then call `on()` to listen to events.
+- The API is the same across React, Vue, and mini programs; only the package name differs.
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `TUICallEvent.ON_CALL_BEGIN` | Call established event | Triggered when the call connects; carries `roomID` |
+| `TUICallEvent.ON_CALL_END` | Call ended event | Triggered when the call ends; carries `roomID` |
+| `TUICallKitAPI.getTUICallEngineInstance()` | Get the TUICallEngine instance | Obtains the underlying engine instance from TUICallKit |
+| `engine.on(event, handler)` | Listen to engine events | Registers event callbacks via the engine instance |
+| `event.roomID` | Call room ID | The room ID field in the event parameters |
+
+## 3. Mechanism & Sequence
+
+TUICallKit initializes -> call connects (`ON_CALL_BEGIN`) -> call in progress -> call ends (`ON_CALL_END`). Call-related events such as `ON_CALL_BEGIN` and `ON_CALL_END` all carry `roomID`; simply read it in the callback.
+
+## 4. Standard Usage
+
+1. Get the TUICallEngine instance via `TUICallKitAPI.getTUICallEngineInstance()`.
+2. Call `engine.on()` to listen to `TUICallEvent.ON_CALL_BEGIN` or `ON_CALL_END`.
+3. Read `event.roomID` in the callback to obtain the room ID.
+
+```javascript
+// Web: @trtc/call-engine-lite-js
+// 小程序: @trtc/call-engine-lite-wx  （API 一致，仅包名不同）
+import { TUICallEvent } from "@trtc/call-engine-lite-js";
+
+const handleOnCallBegin = function(event) {
+  // event.roomID 即为当前通话的房间号
+  console.log('通话建立，房间号：', event.roomID);
+};
+
+TUICallKitAPI.getTUICallEngineInstance().on(
+  TUICallEvent.ON_CALL_BEGIN,
+  handleOnCallBegin
+);
+```
+
+## 5. Expected Results
+
+- After the call is established, the `ON_CALL_BEGIN` callback fires and `event.roomID` returns a valid room ID.
+- After the call ends, the `ON_CALL_END` callback fires and `event.roomID` can also be read.
+- The `roomID` value remains constant throughout the call.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Calling `getTUICallEngineInstance()` before TUICallKit initialization completes (ensure initialization is done first).
+- Pitfall 2: Assuming `roomID` changes during the call (the room ID is fixed for a given call).
+
+## 7. Problem Definition (retrieval hint)
+
+Web TUICallKit React/Vue/mini program users need to get the current call's room ID for logging or associating with other services.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to get the room ID in TUICallKit?
+- How to obtain the roomID when a call is established?
+- How to listen to the `ON_CALL_BEGIN` event?
+- How to get the call room ID in TUICallKit React?
+- How to get the roomID in mini program TUICallKit?
+- How to get the call room ID / Roomid?
+- How to get the room ID in Web TUICallKit?
+- How to obtain the call room ID?

package/resource/knowledge/callkit/best-practice/common/callkit-limitations.md

@@ -0,0 +1,37 @@
+---
+title: "TUICallKit Limitations（TUICallKit：离线推送、支付宝、抖音、企微以及桌面版微信小程序）"
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, limitation, unsupported, offline push, Alipay, Douyin mini program, WeCom, desktop, compatibility]
+version_range: ">=2.0.0"
+---
+
+# TUICallKit Limitations
+
+## 1. Key Takeaways
+
+| Question | Answer |
+|---|---|
+| Can Web TUICallKit receive offline push messages? | No. Web TUICallKit does not support receiving offline push messages. |
+| Can WeChat Mini Program TUICallKit run on Alipay or Douyin mini programs? | No. It only supports running on WeChat Mini Programs. |
+| Can WeChat Mini Program TUICallKit run in WeCom (Enterprise WeChat)? | No. It only supports running on WeChat Mini Programs. |
+| Can WeChat Mini Program TUICallKit run in the PC desktop WeChat client? | No. It only supports running on WeChat Mini Programs. |
+| Can WeChat Mini Program TUICallKit receive offline push messages? | No. WeChat Mini Program TUICallKit does not support receiving offline push messages. |
+
+## 3. Mechanism & Sequence
+
+The capability boundaries of TUICallKit on each platform are determined by underlying platform restrictions. WeChat Mini Programs rely on WeChat native capabilities and cannot run cross-platform; the Web platform is limited by browser autoplay policies and offline push mechanisms.
+
+## 7. Problem Definition (retrieval hint)
+
+Users inquire about TUICallKit capability boundaries across different platforms and scenarios, confirming whether offline push, cross-platform execution, etc. are supported.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Does TUICallKit support offline push?
+- Can WeChat Mini Program TUICallKit run on Alipay?
+- Can TUICallKit mini program run in WeCom?
+- Does TUICallKit WeChat Mini Program support the PC WeChat client?
+- Does TUICallKit Web have offline message notifications?
+- Does TUICallKit mini program only support WeChat?

package/resource/knowledge/callkit/best-practice/common/callkit-user-register-and-kicked.md

@@ -0,0 +1,98 @@
+---
+title: "TUICallKit user registration and Multi-Instance Kick-Out Explained（TUICallKit 用户注册 / 多实例登录）"
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, user registration, init, userSig, auto-create user, multi-instance login, kicked out, KICKED_OUT, troubleshooting, same browser, multi-instance, web multi-instance]
+version_range: ">=4.0.0"
+---
+
+# TUICallKit User Registration and Multi-Instance Kick-Out Explained
+
+## 1. Key Takeaways
+
+### User Registration
+
+- TUICallKit **does not have a dedicated frontend registration API**. User registration is completed through the `init` API: passing `userID` and `userSig` completes authentication and login.
+- When a `userID` and `userSig` issued by the backend are used to log in to TUICallKit for the first time, the system automatically creates the user if that `userID` does not yet exist in Tencent Cloud IM.
+- Alternatively, users can be batch-imported via the IM Console, and then the imported `userID` with its corresponding `userSig` can be used to log in.
+
+### Multi-Instance Kick-Out
+
+- When the same `userID` is logged in simultaneously across different browser tabs or devices, the earlier session is kicked offline (`KICKED_OUT`) by default, because the Chat SDK Web allows only one instance online per user by default.
+- After enabling **Web Multi-Instance Login** in the Chat Console, the same `userID` can be online across multiple tabs or devices simultaneously without being kicked.
+- Different `userID`s logged in within the same browser are not affected by this restriction and will not kick each other offline.
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `init` | Initialize and register a user | Pass `SDKAppID`, `userID`, `userSig` to complete authentication |
+| `userID` | User identifier | Issued or defined by the business backend; auto-creates the user on first login |
+| `userSig` | User signature | Issued by the business backend for authentication |
+| `KICKED_OUT` | Kicked offline event | Triggered during same-account / multi-instance login |
+| Web Multi-Instance Login | Console configuration | Once enabled, the same browser can have multiple sessions online simultaneously |
+
+## 3. Mechanism & Sequence
+
+### User Registration Flow
+
+Backend generates `userID` + `userSig` -> frontend calls `init({ SDKAppID, userID, userSig })` -> TUICallKit logs in via the Chat SDK -> if the user does not exist, it is auto-created -> login succeeds.
+
+### Multi-Instance Kick-Out Mechanism
+
+Same `userID` logs in on tab A -> same browser opens tab B and logs in with the same `userID` -> Chat backend detects a multi-instance login -> kicks tab A offline -> tab A receives the `KICKED_OUT` event.
+
+## 4. Standard Usage
+
+### User Registration and Initialization
+
+```javascript
+// React: @trtc/calls-uikit-react
+// Vue 3: @trtc/calls-uikit-vue
+// Vue 2.7: @trtc/calls-uikit-vue2
+// Vue 2.6: @trtc/calls-uikit-vue2.6
+// uniapp 小程序: @trtc/calls-uikit-wx-uniapp
+// 微信原生小程序: @trtc/calls-uikit-wx  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+TUICallKitAPI.init({
+  SDKAppID: 0,         // 控制台获取的 SDKAppID
+  userID: 'user_xxx',  // 业务后端签发的用户 ID
+  userSig: 'xxx',      // 业务后端签发的用户签名
+});
+```
+
+### Enabling Web Multi-Instance Login (Resolving Kick-Out)
+
+1. Log in to the Tencent Cloud IM Console.
+2. Navigate to the target application's feature configuration page.
+3. Enable the **Web Multi-Instance Login** toggle.
+4. Save. The change takes effect immediately without restarting the client.
+
+## 5. Expected Results
+
+- After calling `init`, login succeeds with no errors.
+- With Web Multi-Instance enabled in the console, the same `userID` can be online across multiple tabs or devices simultaneously.
+- Without the feature enabled, logging in with the same `userID` on a new tab causes the old tab to receive the `KICKED_OUT` event.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming TUICallKit has a dedicated frontend registration API (registration and login are actually done through `init`).
+- Pitfall 2: Treating kick-out as a TUICallKit bug (it is actually the Chat SDK's multi-device login restriction).
+- Pitfall 3: Assuming different origins also cause kick-out (different origins are treated as different instances and are unaffected).
+- Pitfall 4: Assuming different `userID`s in the same browser kick each other out (the multi-instance restriction applies to the same `userID`; different `userID`s are independent).
+- Pitfall 5: Thinking `KICKED_OUT` can only be resolved by closing other logins (enabling Web Multi-Instance Login avoids it).
+
+## 7. Problem Definition (retrieval hint)
+
+Users ask about TUICallKit Web user registration (whether there is a dedicated registration API, whether users are auto-created), and the cause and solution for multi-account kick-out within the same browser.
+
+## 8. Alternative Queries (retrieval recall)
+
+- What is the TUICallKit user registration API?
+- Does first-time login auto-create a user?
+- What to do when two accounts in the same browser get kicked out?
+- How to troubleshoot `KICKED_OUT`?
+- Does logging in from a different domain cause kick-out?
+- How to let multiple users log in on the same page simultaneously?

package/resource/knowledge/chat/best-practice/common/avchatroom-message-loss-diagnosis.md

@@ -0,0 +1,65 @@
+---
+title: "Web/Mini Program Chat SDK: AVChatRoom Message Loss Diagnosis and Mitigation（直播群消息丢失）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [AVChatRoom, message loss, avchatroom, MESSAGE_RECEIVED, long polling, MsgPriority, priority, restapi, rate limit, 40 messages per second]
+version_range: ">=3.0.0"
+---
+
+# Web/Mini Program Chat SDK: AVChatRoom Message Loss Diagnosis and Mitigation
+
+## 1. Key Takeaways
+
+- Scenario 1 (messages lost during batch sending): The root cause is incorrect consumption logic of the `MESSAGE_RECEIVED` callback on the business side. This callback may return multiple messages at once; you must read the full list `event.data`.
+- Scenario 2 (important messages not received during high-frequency chat): The root cause is triggering the backend group message rate limit. The default is `40` messages/second per group; messages exceeding this limit are discarded. You can increase the retention probability of important messages by setting message priority.
+- Scenario 3 (messages lost after unstable network or long background period): This is expected behavior for avchatroom. When the app resumes after more than `2` minutes in the background, it cannot pull historical messages beyond the cache window.
+- Avchatroom messages are not stored in roaming. The backend caches messages for only `2` minutes with a maximum of `2000` messages by default; messages beyond the window or limit cannot be recovered via long polling.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `EVENT.MESSAGE_RECEIVED` | Message receive callback | A single callback may return multiple messages; the business must iterate over all items in `event.data` |
+| `priority` (SDK) | SDK message sending priority | Can be set in `createXXXMessage`; higher priority messages are less likely to be discarded when the rate limit is exceeded |
+| `MsgPriority` (REST API) | REST API message sending priority | Set priority in the message body to ensure critical notifications in high-concurrency scenarios |
+| Group rate limit (default `40` msg/s) | Backend flow control threshold | Messages exceeding the threshold are discarded; long polling cannot retrieve discarded messages |
+| avchatroom cache window (`2` min / `2000` msgs) | Temporary cache boundary | Messages beyond the time or count limit are purged from the cache |
+
+## 3. Mechanism & Sequence
+
+Business sends message (SDK/REST API) -> AVChatRoom backend applies group rate limit (default `40` msg/s) -> Client receives messages via long polling and triggers `MESSAGE_RECEIVED` -> Business consumes the callback list.
+When the app resumes after a long background period (over `2` minutes): WebSocket reconnects -> long polling resumes -> only messages within the cache window (`2` minutes and at most `2000` messages) can be pulled.
+
+## 4. Standard Usage
+
+1. **Fix receive logic (Scenario 1)**: Iterate over all items in `event.data` within the `MESSAGE_RECEIVED` callback. Never process only `event.data[0]`.
+2. **Ensure important message delivery (Scenario 2)**: Set high priority for critical messages such as lottery draws or product listing/delisting notifications.
+   - SDK sending: Set `priority` in `createXXXMessage`.
+   - REST API sending: Set `MsgPriority` in the message body.
+3. **Control sending rate (Scenario 2)**: Implement rate limiting or message merging on the business side to avoid continuously exceeding `40` messages/second per group.
+4. **Handle background recovery expectations (Scenario 3)**: Treat "possible loss of avchatroom history after a long background period" as an expected product behavior, and use business-level fallback mechanisms (e.g., critical state re-pull API) to recover.
+
+## 5. Expected Results
+
+- During batch message stress testing, every item in `event.data` from the `MESSAGE_RECEIVED` callback is consumed, with no "only first message received" issue.
+- When the sending rate exceeds `40` msg/s, low-priority messages are discarded first, and the delivery rate of high-priority critical notifications increases.
+- Both REST API and SDK sending paths have the priority field (`MsgPriority` / `priority`) configured.
+- After the app resumes from more than `2` minutes in the background, the business side can recover critical state through fallback mechanisms.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Treating `MESSAGE_RECEIVED` as a single-message callback and only processing `event.data[0]`.
+- Pitfall 2: Not setting message priority in high-concurrency avchatroom, causing critical messages to compete at the same level as spam messages.
+- Pitfall 3: Using a avchatroom as if it were a roaming group, expecting all historical messages to be available after a long background period.
+
+## 7. Problem Definition (retrieval hint)
+
+In the Web Chat SDK AVChatRoom scenario, "message loss" is observed. The business wants to ensure that important messages such as lottery draws and product listing/delisting notifications are not lost.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Why does AVChatRoom lose messages?
+- How to ensure product delisting messages are always delivered during high-frequency chat in a avchatroom?
+- How to handle multiple messages returned in a single `MESSAGE_RECEIVED` callback?
+- Why can't previously sent messages be pulled after reconnecting from a long background period in a avchatroom?

package/resource/knowledge/chat/best-practice/common/group-conversation-cleanup-on-system-notice.md

@@ -0,0 +1,62 @@
+---
+title: "Web/Mini Program Chat SDK: Removing Residual Conversations After Leaving or Dismissing a Group（退群 / 群组解散 / 被踢出群 / 删除会话列表中已退出的群组）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [quitGroup, dismissGroup, deleteConversation, TIMGroupSystemNoticeElem, operationType, conversation list, leave group, dismiss group]
+version_range: ">=3.0.0"
+---
+
+# Web/Mini Program Chat SDK: Removing Residual Conversations After Leaving or Dismissing a Group
+
+## 1. Key Takeaways
+
+- The conversation remaining after `quitGroup` / `dismissGroup` is an intentional SDK UX design: while the login session is valid, the group conversation is retained so users can still view message history.
+- To completely remove it from the conversation list, you must actively call `deleteConversation` after receiving the group system notice (`TIMGroupSystemNoticeElem`).
+- The deletion trigger condition is determined by `message.payload.operationType`: `4` (kicked from group), `5` (group dismissed), `8` (user actively left group).
+- Relying solely on the return result of `quitGroup` / `dismissGroup` does not automatically delete the conversation list entry.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `TIMGroupSystemNoticeElem` | Group system notice type | Identifies system events such as member changes, dismissal, and leaving |
+| `message.payload.operationType` | Notice action code | `4` kicked out, `5` group dismissed, `8` actively left |
+| `deleteConversation` | Delete conversation API | Called when the trigger condition is met to remove the corresponding group conversation from the conversation list |
+| `quitGroup` / `dismissGroup` | Group management actions | Perform leave/dismiss; they do not handle conversation list cleanup |
+
+## 3. Mechanism & Sequence
+
+Business calls `quitGroup` or `dismissGroup` -> SDK retains the corresponding group conversation (while login session is valid) -> Receives `TIMGroupSystemNoticeElem` -> Business checks `operationType` to determine whether to trigger deletion -> When matching `4/5/8`, calls `deleteConversation` -> Conversation list removes the group conversation.
+
+## 4. Standard Usage
+
+1. Without UI integration: Listen to `MESSAGE_RECEIVED` directly via `chat.on` and handle group system notices in the callback.
+2. With UI integration: First obtain the `chat` instance from `TUILogin.getContext()`, then listen to `MESSAGE_RECEIVED` via `chat.on` to receive system notices.
+3. Filter messages of type `TIMGroupSystemNoticeElem` in the callback.
+4. Read `message.payload.operationType`; only enter the deletion branch for values `4`, `5`, or `8`.
+5. Call `deleteConversation` with the group conversation ID, and refresh the conversation list state after success to avoid local cache residuals.
+
+## 5. Expected Results
+
+- After calling `quitGroup`, the `operationType=8` notice is received and `deleteConversation` is triggered successfully.
+- After calling `dismissGroup`, the `operationType=5` notice is received and the group conversation is removed successfully.
+- When kicked by an admin, the `operationType=4` notice triggers automatic conversation cleanup.
+- After refreshing the conversation list, the target group conversation no longer appears and is not re-displayed due to system notice echoing.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming `quitGroup` / `dismissGroup` automatically deletes the conversation list entry.
+- Pitfall 2: Ignoring the group system notice without reading `operationType`.
+- Pitfall 3: Only performing local UI deletion without calling `deleteConversation`, causing the conversation to reappear.
+
+## 7. Problem Definition (retrieval hint)
+
+After calling `quitGroup` or `dismissGroup` in the Web Chat SDK, the group conversation still exists in the conversation list; after receiving the system message "You have left this group", the conversation reappears in the list. The business needs to completely remove the group conversation after leaving or dismissing the group.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Why is the group conversation still in the conversation list after calling `quitGroup`?
+- Why does the conversation reappear after `dismissGroup`?
+- How to delete the conversation after receiving "You have left this group"?
+- How to link group system notices with `deleteConversation`?

package/resource/knowledge/chat/best-practice/common/image-message-url-lifecycle.md

@@ -0,0 +1,59 @@
+---
+title: "Chat SDK: Image Message URL Lifecycle (blob vs. imageUrl)（图片消息 blob 地址 / 服务端 url 更新时机 / imageInfoArray / 图片消息 url）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [sendMessage, createImageMessage, imageInfoArray, imageUrl, url, blob, https, image message, upload progress, lifecycle]
+version_range: ">=3.0.0"
+---
+
+# Chat SDK: Image Message URL Lifecycle (blob vs. imageUrl)
+
+## 1. Key Takeaways
+
+- `imageInfoArray[x].url` is primarily used for local preview; it remains a `blob:` in-memory URL even after the message is sent successfully.
+- When you need a cloud-accessible URL, read `imageInfoArray[x].imageUrl` from the successfully sent message.
+- After refreshing and re-logging in, when pulling roaming messages, `imageInfoArray[x].url` is the server-side URL.
+- To get upload progress, pass an `onProgress` callback when calling `createImageMessage`.
+
+## 2. Field / API Reference
+
+| Field / Capability | Phase | Semantics |
+|---|---|---|
+| `imageInfoArray[x].url` | During/after sending | Local preview address; may be `blob:`; not guaranteed to auto-update to a cloud URL |
+| `imageInfoArray[x].imageUrl` | After successful send | Server-accessible address; use as the externally accessible URL |
+| `onProgress` | During upload | File upload progress callback for displaying upload progress |
+
+## 3. Mechanism & Sequence
+
+`createImageMessage` -> `sendMessage` -> Internal upload flow -> Upload succeeds and message is sent to IM backend -> Read `imageInfoArray[x].imageUrl` from the returned message -> After refreshing and re-logging in, pulling roaming messages yields `imageInfoArray[x].url` as the server-side URL.
+
+## 4. Standard Usage
+
+1. Call `createImageMessage` to create an image message (pass `onProgress` if progress is needed).
+2. Call `sendMessage` to send the message.
+3. After successful sending, read `imageInfoArray[x].imageUrl` from the returned message as the cloud URL.
+4. Correct approach for rendering images on the frontend: read `imageInfoArray[x].url` when rendering the message; using the `blob` address during sending enables faster image rendering.
+
+## 5. Expected Results
+
+- After sending, inspect the same message:
+  - `imageInfoArray[x].url` is still `blob:`;
+  - `imageInfoArray[x].imageUrl` is a server-accessible address.
+- After refreshing and re-logging in, pulling history messages yields `imageInfoArray[x].url` as the server-side URL.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming that `url` will automatically change to a cloud link after upload.
+
+## 7. Problem Definition (retrieval hint)
+
+After sending an image message, the user observes that `imageInfoArray[x].url` is still a `blob:` local URL and expects it to automatically become a Tencent Cloud `https` URL. The user also wants to know which field to read as the final accessible address after upload is complete.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Why is `url` still `blob:` after sending an image message?
+- Which field should I use to get the cloud `https` image URL?
+- How to get the final image URL after `sendMessage` succeeds?
+- What is the difference between `imageInfoArray[x].url` and `imageInfoArray[x].imageUrl`?
+- Why does the image URL in history messages change after refreshing?

package/resource/knowledge/chat/best-practice/common/login-repeat-2025-diagnosis.md

@@ -0,0 +1,61 @@
+---
+title: "Web Chat SDK: login Returns 2025 (Repeat Login) Diagnosis and Fix（重复登录 / repeatLogin）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [login, 2025, repeat login, repeatLogin, web, miniprogram, concurrent calls, debounce]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK: login Returns 2025 (Repeat Login) Diagnosis and Fix
+
+## 1. Key Takeaways
+
+- The direct cause of `2025` is that the business side calls `login` consecutively in a short time while the SDK has not yet received the backend response for the first login request.
+- Within approximately `15s` after the first `login` is initiated, if the previous login has not received a response, the SDK directly blocks subsequent `login` calls and returns `2025`.
+- If the SDK has already received the login response and the same `userID` calls `login` again, it does not trigger the `2025` blocking branch; instead it returns `imResponse.data.repeatLogin = true` in `login.then`.
+- The solution is to fix the `login` call logic on the business side: ensure only one in-flight `login` request exists for the same session.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| Error code `2025` | Repeat login blocking signal | When a previous `login` has not received a response, subsequent calls within a short period are directly blocked by the SDK |
+| `imResponse.data.repeatLogin` | Repeat login flag | When the SDK has received a response and the same `userID` logs in again, this returns `true` in `then` |
+| `login` in-flight state | Key state for concurrency control | The business side must ensure only one `login` is executing at a time |
+
+## 3. Mechanism & Sequence
+
+First `login` call -> SDK sends login request -> Backend response not yet received -> Business side calls `login` again within ~`15s` -> SDK directly blocks and returns `2025`.
+First `login` call -> SDK has received backend response -> Business side calls `login` again with the same `userID` -> `imResponse.data.repeatLogin = true` is returned in `login.then`.
+
+## 4. Standard Usage
+
+1. Implement single-flight login on the business side: for the same `userID`, prohibit duplicate calls before the previous `login` completes.
+2. Add a state machine (`idle`/`logging_in`/`logged_in`) or Promise reuse for `login`, reusing the in-flight login result.
+3. Upon receiving `2025`, do not retry immediately; wait for the current in-flight login to complete, then decide the next action based on the result.
+4. Check `imResponse.data.repeatLogin` in `login.then` and handle it as an "already logged in" branch without re-initializing the session.
+
+## 5. Expected Results
+
+- When login is triggered consecutively for the same `userID`, the business side only sends one real `login` request.
+- Under stress testing with rapid login button clicks, `2025` no longer occurs.
+- When `login` is called again after a response has been received, `repeatLogin` is consistently observed in `then` and the expected branch is followed.
+- Login state initialization logic executes only once, with no duplicate conversation pulls or duplicate listeners.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Immediately calling `login` again upon receiving `2025`, creating a blocking loop.
+- Pitfall 2: Treating `2025` and `repeatLogin=true` as the same-phase error.
+- Pitfall 3: Not implementing idempotency protection in `onShow`, route changes, or reconnection callbacks, leading to concurrent login calls.
+
+## 7. Problem Definition (retrieval hint)
+
+When calling `login` in the Web Chat SDK, triggering the login request repeatedly in a short time returns `2025`. The business side needs to understand: under what conditions `2025` is triggered, and how it differs from `imResponse.data.repeatLogin = true`.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Why does the Web IM SDK `login` return 2025?
+- What does `login` returning 2025 mean?
+- Under what circumstances does the repeat login error code 2025 occur?
+- What is the difference between `repeatLogin=true` and `2025`?

package/resource/knowledge/chat/best-practice/common/message-read-report-and-receipt.md

@@ -0,0 +1,64 @@
+---
+title: "Web Chat SDK: Conversation Read Report and Message Read Receipt (setMessageRead vs. sendMessageReadReceipt)（已读上报 setMessageRead / 已读回执 sendMessageReadReceipt）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [setMessageRead, sendMessageReadReceipt, read receipt, MESSAGE_READ_BY_PEER, MESSAGE_READ_RECEIPT_RECEIVED, needReadReceipt, group message read]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK: Conversation Read Report and Message Read Receipt (setMessageRead vs. sendMessageReadReceipt)
+
+## 1. Key Takeaways
+
+- The recommended flow for automatically sending message-level read receipts upon entering a conversation is: first pull roaming messages via `getMessageList`, then call `sendMessageReadReceipt` to report the corresponding messages as read.
+- `setMessageRead` is a conversation-level read report: a successful call clears the unread count of the current conversation; in one-to-one chat scenarios, the peer can update message read status via `MESSAGE_READ_BY_PEER`.
+- `sendMessageReadReceipt` is a message-level read receipt: it does not affect the conversation unread count, only the read/unread status of individual messages; for group messages, this capability is required to implement message-level read status.
+- The message read receipt capability has usage restrictions: not available on Trial/Standard plans; `needReadReceipt=true` must be set when creating the message; group read receipts require a group size limit of `200` and the group message read receipt switch must be enabled in the console (Console > Feature Configuration > Group Configuration > Group Message Read Receipt).
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `setMessageRead` | Conversation-level read report | Clears the current conversation's unread count; in one-to-one chat, can trigger `MESSAGE_READ_BY_PEER` on the peer side |
+| `sendMessageReadReceipt` | Message-level read receipt | Does not clear conversation unread count; only updates message read/unread status |
+| `needReadReceipt` | Message read receipt switch | Must be set to `true` when creating a message to enable message-level receipts |
+| `MESSAGE_READ_BY_PEER` | One-to-one chat peer read event | Used to update one-to-one chat message read status |
+| `MESSAGE_READ_RECEIPT_RECEIVED` | Message receipt received event | Used to process received message read receipt updates |
+
+## 3. Mechanism & Sequence
+
+Enter conversation -> Call `getMessageList` to pull roaming messages -> Pass the message list to `sendMessageReadReceipt` (SDK internally filters and processes) -> SDK dispatches read receipt event (e.g., `MESSAGE_READ_RECEIPT_RECEIVED`) -> Business updates message read/unread display.
+If `setMessageRead` is called: conversation unread count is cleared; in one-to-one chat, the peer can receive `MESSAGE_READ_BY_PEER`.
+
+## 4. Standard Usage
+
+1. Upon entering a conversation, first call `getMessageList` to pull the message list.
+2. Pass the message list returned by `getMessageList` directly to `sendMessageReadReceipt`; the SDK internally filters and completes message-level read reporting.
+3. Only call `setMessageRead` when you need to handle conversation unread count; do not use it as a substitute for group message read receipts.
+4. Set `needReadReceipt = true` when creating messages that require receipts.
+5. Subscribe to and handle `MESSAGE_READ_BY_PEER` and `MESSAGE_READ_RECEIPT_RECEIVED` to synchronously update message read status.
+
+## 5. Expected Results
+
+- After entering a group chat, pulled messages successfully trigger `sendMessageReadReceipt`.
+- After calling `sendMessageReadReceipt`, the conversation unread count is not cleared, but message read status is updated.
+- After calling `setMessageRead`, the conversation unread count is cleared, and the one-to-one chat peer can observe `MESSAGE_READ_BY_PEER`.
+- In the group read scenario, the correct plan is activated, the console switch is enabled, and the group size does not exceed `200`.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Using `setMessageRead` instead of `sendMessageReadReceipt` to implement group message read status.
+- Pitfall 2: Expecting to receive message-level read receipts without setting `needReadReceipt=true`.
+- Pitfall 3: Going live with group read capability without activating the Premium plan or enabling the group message read receipt switch.
+
+## 7. Problem Definition (retrieval hint)
+
+After entering a group chat conversation on the Web, how to automatically send read receipts to message senders? What is the difference between `setMessageRead` and `sendMessageReadReceipt`?
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to automatically report read status after entering a conversation?
+- Which API should be used for group chat read/unread display?
+- What is the difference between `setMessageRead` and `sendMessageReadReceipt`?
+- Why does message read status not change as expected after calling `setMessageRead`?

package/resource/knowledge/chat/best-practice/common/message-receive-event.md

@@ -0,0 +1,65 @@
+---
+title: "Web Chat SDK: MESSAGE_RECEIVED Event and Group Tip Message Handling（MESSAGE_RECEIVED / 群提示消息TIMGroupTipElem /  接收消息 / 自己发的消息上屏）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [MESSAGE_RECEIVED, TIMGroupTipElem, TIMGroupSystemNoticeElem, message receive, self-sent message, event.data]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK: MESSAGE_RECEIVED Event and Group Tip Message Handling
+
+## 1. Key Takeaways
+
+- The Web Chat SDK delivers all message notifications to the business side through the unified `MESSAGE_RECEIVED` event.
+- By iterating over `event.data` in the callback, you can distinguish between normal messages, group tip messages (`TIMGroupTipElem`), and group system notices (`TIMGroupSystemNoticeElem`) using the `type` field.
+- Messages sent by the current instance are not delivered back to itself via `MESSAGE_RECEIVED`; self-sent messages should be added to the on-screen message list immediately after creation.
+- In multi-instance or multi-device login scenarios, messages sent by other instances can be received via `MESSAGE_RECEIVED`.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `EVENT.MESSAGE_RECEIVED` | Unified receive entry | All received messages are delivered to the business side through this event |
+| `event.data` | Message list payload | A single callback may contain multiple messages; all must be iterated and processed |
+| `message.type` | Message classification field | Used to identify normal messages, `TIMGroupTipElem`, and `TIMGroupSystemNoticeElem` |
+| Self-sent message rendering | UI timing control | Messages sent by the current instance should be rendered on screen immediately after creation, not relying on `MESSAGE_RECEIVED` |
+
+## 3. Mechanism & Sequence
+
+Business subscribes to `MESSAGE_RECEIVED` -> SDK delivers message list `event.data` -> Business iterates the list and routes by `type`.
+Current instance sends a message: creates message and immediately renders locally -> calls send API -> does not deliver back via `MESSAGE_RECEIVED`.
+Other instances/devices send a message: current device receives it via `MESSAGE_RECEIVED` and processes by type.
+
+## 4. Standard Usage
+
+1. Subscribe to `EVENT.MESSAGE_RECEIVED`; read the full `event.data` list in the callback.
+2. Route each message by `type`: normal messages, `TIMGroupTipElem`, and `TIMGroupSystemNoticeElem` go to different business handlers.
+3. When sending a message yourself, add it to the local message list immediately after `createXXXMessage` to ensure timely on-screen display.
+4. Maintain clear responsibility boundaries between send callbacks and receive callbacks: the send path handles local state, the receive path handles messages from other devices/instances.
+
+## 5. Expected Results
+
+- After a group tip event triggers, `TIMGroupTipElem` is correctly identified in `MESSAGE_RECEIVED` and the correct handling logic is executed.
+- Group system notices are correctly identified as `TIMGroupSystemNoticeElem` in the callback and properly routed.
+- When the current instance sends a message, it is rendered locally immediately without waiting for `MESSAGE_RECEIVED`.
+- In multi-device login scenarios, messages sent from other devices are received normally via `MESSAGE_RECEIVED`.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Treating `MESSAGE_RECEIVED` as a single-message callback and only processing `event.data[0]`.
+- Pitfall 2: Expecting messages sent by the current instance to be delivered back via `MESSAGE_RECEIVED` before rendering on screen.
+- Pitfall 3: Not classifying by `type`, causing group tip messages and normal text messages to share the same handling logic.
+
+## 7. Problem Definition (retrieval hint)
+
+In the Web Chat SDK scenario, the business side needs to clarify two things:
+1) How to receive and identify group tip messages `TIMGroupTipElem`;
+2) Whether `MESSAGE_RECEIVED` delivers messages sent by the current instance itself.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How does the Web SDK receive group tip messages `TIMGroupTipElem`?
+- How to distinguish between normal messages and group system messages in the `MESSAGE_RECEIVED` callback?
+- Why are self-sent messages not received via `MESSAGE_RECEIVED`?
+- In multi-device login, can messages sent from other devices be received via `MESSAGE_RECEIVED`?