@tencent-rtc/mcp 1.6.7 → 1.7.0

package/resource/knowledge/callkit/faq/android.md

@@ -1,19 +1,19 @@
 ### The error message "The package you purchased does not support this ability"?
 
-If you encounter the above error message, it is because the audio and video call capability package of your current application has expired or has not been activated. You can refer to the service activation guide to claim or activate the audio and video call capability, and then continue to use the TUICallKit component.
+If you encounter the above error message, it is because the audio and video call capability package of your current application has expired or has not been activated. You can .
 
 ### When the application is offline, Will it can pop up the call view?
 
 During a one-to-one call, if you come online within the timeout period, an incoming call view will be triggered;  For group calls, if you come online within the timeout period, the last 20 unprocessed group messages will be pulled up, and if a call invitation exists, it will trigger an incoming call. The display strategy for incoming calls see: Incoming call display policy for the callee.
 
 ### When the application is in the background, Will it can pop up the call view?
-1. TUICallKit has two different display policy for the callee, see below: Incoming call display policy for the callee.
+1. TUICallKit has two different display policy for the callee.
 
 2. Before version 2.3 of TUICallKit, to automatically bring the application from the background to the foreground, it was necessary to check whether the app had enabled the "Background self-start" or "Floating window" permission.
 
    Different manufacturers, or even the same manufacturer with different Android versions, offer varying permissions and permission names for applications. For instance, Xiaomi 6 requires only the "Background pop-ups" permissions , while Redmi needs both the "Background pop-ups"  and "Display over other applications" permissions.
 
-   How to enable permissions, see below: Relevant permissions enabled.
+ How to enable permissions.
 
 3. If you encounter the following scenarios where the call interface cannot be pulled up, the reason is that changes in the application's launch stack caused the CallKitActivity interface to be obscured or removed.
 
@@ -23,7 +23,7 @@ During a one-to-one call, if you come online within the timeout period, an incom
 
    Scenario Three: When the app is in the background and an offline push notification is received, not clicking the push notification but entering the app via the desktop icon will either fail to bring up the CallKitActivity or cause the CallKitActivityto flash momentarily.
 
-   In the above scenarios, you need to add the following code to the default Activity of your app. Each app's default Activity may differ. Refer to the AndroidManifest.xml configuration for more details. Taking the launch page SplashActivity for most applications as an example:
+ In the above scenarios, you need to add the following code to the default Activity of your app. Each app's default Activity may differ. .xml configuration for more details. Taking the launch page SplashActivity for most applications as an example:
 
 【Code】
 ``` java
@@ -40,10 +40,6 @@ if (!isTaskRoot() && getIntent() != null && getIntent().hasCategory(Intent.CATEG
 
 To make TUICallKit adaptable to different business needs, add product features, and improve user experience, TUICallKit **version 2.3 and above** (Release Log) optimized the call page display pop-up strategy after receiving a call, as detailed below:
 
-|Full screen display of incoming call|Banner display of incoming call|
-|---------|---------|
-|||
-
 1. If you want the callee to pull up the full-screen call view when receiving a call, you can integrate the [tuicallkit-kt](https://github.com/Tencent-RTC/TUICallKit/tree/main/Android/tuicallkit-kt) code. By default, the incoming call display strategy for the callee is as follows:
 
 2. If you prefer to show a banner when receiving a call and then pull up the full-screen  as needed, you can enable this feature by calling the following interface.
@@ -52,8 +48,6 @@ To make TUICallKit adaptable to different business needs, add product features,
      TUICallKit.createInstance(context).enableIncomingBanner(true);
    ```
 
-   Once enabled, the callee's incoming call strategy is as shown below, as long as the **floating window permission** is enabled, the call banner will be displayed as much as possible.
-
    > **Note:**
    >
    > For information on how to enable related permissions, see below: Relevant permissions enabled.
@@ -69,10 +63,6 @@ To ensure a good calling experience, it is recommended to enable "notification"
 
 After the application is installed, you can long-press the application Icon, select "Application Information", then enable "notification" permission, "Display over other applications" and "Background pop-ups" permissions. Alternatively, you can go to `Mobile Phone > System Settings > Application Management > Application` to manually enable these permissions.
 
-|Pixel 4a|VIVO|
-|---------|---------|
-|||
-
 【Code guidance】
 - **Notification permissions**: For showcasing push notifications: please refer to [Notification runtime permissions](https://developer.android.com/develop/ui/views/notifications/notification-permission) and [Request runtime permissions](https://developer.android.com/training/permissions/requesting#request-permission) and implement according to business needs.
 

package/resource/knowledge/callkit/faq/common.md

@@ -16,8 +16,6 @@ After the call is connected, you can obtain the call room number (RoomId) throug
 
 ### Encounter error code "-3301" with the message "Services are not available in your region" after entering the room
 
-If you receive this error code, [contact us](https://trtc.io/contact) for support.
-
 ### In the TUIChat + TUICallKit Integrated Scenarios, after Upgrading the TUICallKit Version, New Version Calls Old Version and Old Version Is Unable to Receive Call Issues
 
 Starting from TUICallKit version 3.1, in the TUIChat + TUICallKit integrated scenarios, initiating a call through the call button in TUIChat by default uses the new calls API. Therefore, if your business has already gone live, you can use the advanced API to switch the call interface to call or groupCall to maintain interconnectivity with users of the online edition.

package/resource/knowledge/callkit/faq/error-code.md

@@ -28,7 +28,6 @@ Video and audio calls use Tencent Cloud's Chat SDK as the basic service for comm
 |8010|The signaling request ID is invalid or has been processed.|
 
 > **Note：**
->
 > More Chat SDK error codes are available at：[Chat Error Code](https://www.tencentcloud.com/document/product/1047/34348)
 >
 
@@ -46,10 +45,9 @@ Video and audio calls use Tencent Cloud's Chat SDK as the basic service for call
 |ERR_MIC_NOT_AUTHORIZED|-1317|No permission to access to the mic. This usually occurs on mobile devices and may be because the user denied access.|
 |ERR_MIC_SET_PARAM_FAIL|-1318|Failed to set mic parameters.|
 |ERR_MIC_OCCUPY|-1319|The mic is being used. The mic cannot be turned on when, for example, the user is having a call on the mobile device.|
-|ERR_TRTC_ENTER_ROOM_FAILED|-3301|Failed to enter the room. For the reason, refer to the error message for -3301.|
+|ERR_TRTC_ENTER_ROOM_FAILED|-3301|Failed to enter the room. For the reason.|
 
 > **Note：**
->
 > More TRTC SDK error codes are available at：[TRTC Error Code](https://www.tencentcloud.com/document/product/647/35130)
 >
 
@@ -60,6 +58,6 @@ New version of CallKit REST API error codes, for example, when retrieving call s
 |Error Code|Description|
 |---------|---------|
 |101001|Internal server error, please try again.|
-|101002|Invalid parameter, check if parameters meet requirements. Refer to error message for specific invalid field.|
+|101002|Invalid parameter, check if parameters meet requirements. .|
 |101004|Call does not exist or has already ended.|
 |101050|Call record does not exist.|

package/resource/knowledge/callkit/faq/ios.md

@@ -1,6 +1,6 @@
 ### The error message "The package you purchased does not support this ability"?
 
-If you encounter the above error message, it is because the audio and video call capability package of your current application has expired or has not been activated. You can refer to the service activation guide to claim or activate the audio and video call capability, and then continue to use the TUICallKit component.
+If you encounter the above error message, it is because the audio and video call capability package of your current application has expired or has not been activated. You can .
 
 ### How to modify TUICallKit source code?
 
@@ -88,8 +88,6 @@ Tencent Cloud's audio and video libraries cannot be integrated at the same time,
 
 ### Does TUICallKit support background operation?
 
-Yes, if you need to continue running related functions in the background, you can select the current project, and in the Background Modes section under Capabilities, check **Audio, AirPlay, and Picture in Picture**, as shown in the following image:
-
 ### How to view TRTC logs?
 
 TRTC logs are compressed and encrypted by default, with the extension .xlog. Whether the log is encrypted can be controlled by setLogCompressEnabled. The file name containing C(compressed) is encrypted and compressed, and the file name containing R(raw) is plaintext.
@@ -97,6 +95,5 @@ TRTC logs are compressed and encrypted by default, with the extension .xlog. Whe
 iOS：Sandbox's `Documents/log`
 
 > **Note:**
->
 > - To view the .xlog file, you need to download the [decryption tool](https://dldir1.qq.com/hudongzhibo/log_tool/decode_mars_log_file.py) and run it directly in the Python 2.7 environment with the xlog file in the same directory using python decode_mars_log_file.py.
 > - To view the .clog file (new log format after version 9.6), you need to download the [decryption tool](http://dldir1.qq.com/hudongzhibo/log_tool/decompress_clog.py) and run it directly in the Python 2.7 environment with the clog file in the same directory using python decompress_clog.py.

package/resource/knowledge/callkit/preset/android/api.md

@@ -241,7 +241,6 @@ fun enableVirtualBackground(enable: Boolean);
 This API is used to make a (one-to-one) call.
 
 > **Note:**
->
 > **It is recommended to use the** [calls](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/en/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-store/calls.html) **API.**
 >
 
@@ -267,7 +266,6 @@ The parameters are described below:
 This API is used to make a (one-to-one) call, Support for custom room ID, call timeout, offline push content, etc.
 
 > **Note:**
->
 > **It is recommended to use the** [calls](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/en/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-store/calls.html) **API.**
 >
 
@@ -298,7 +296,6 @@ The parameters are described below:
 This API is used to make a group call.
 
 > **Note:**
->
 > - It is recommended to use the [calls](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/en/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-store/calls.html) API.
 > - Before making a group call, you need to create an Chat group first.
 > - For details about how to create a group, see [Chat Group Management](https://www.tencentcloud.com/zh/document/product/1047/48466#.E5.88.9B.E5.BB.BA.E7.BE.A4.E7.BB.84), or you can use [Chat UIKit](https://www.tencentcloud.com/en/document/product/1047/50057) to integrate chat, call and other scenarios.
@@ -326,7 +323,6 @@ The parameters are described below:
 This API is used to make a group call, Support for custom room ID, call timeout, offline push content, etc.
 
 > **Note:**
->
 > - It is recommended to use the [calls](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/en/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-store/calls.html) API.
 > - Before making a group call, you need to create an Chat group first.
 > - For details about how to create a group, see [Chat Group Management](https://www.tencentcloud.com/zh/document/product/1047/48466#.E5.88.9B.E5.BB.BA.E7.BE.A4.E7.BB.84), or you can use [Chat UIKit](https://www.tencentcloud.com/en/document/product/1047/50057) to integrate chat, call and other scenarios.
@@ -360,7 +356,6 @@ The parameters are described below:
 This API is used to join a group call.
 
 > **Note:**
->
 > - It is recommended to use the [join](https://liteav.sdk.cloudcachetci.com/doc/product/tuikit/atomic-x/android/en/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.call/-call-store/join.html) API.
 > - Before joining a group call, you need to create or join an Chat group in advance, and there are already users in the group who are in the call.
 > - For details about how to create a group, see [Chat Group Management](https://www.tencentcloud.com/zh/document/product/1047/48466#.E5.88.9B.E5.BB.BA.E7.BE.A4.E7.BB.84), or you can use [Chat UIKit](https://www.tencentcloud.com/en/document/product/1047/50057) to integrate chat, call and other scenarios.
@@ -388,7 +383,6 @@ The parameters are described below:
 Hide the specified button.
 
 > **Note：**
->
 > - Currently supports hiding the following buttons:
 > Camera, Microphone, Audio Device, Switch Camera, Invite User
 >

package/resource/knowledge/callkit/preset/ios/api.md

@@ -136,7 +136,6 @@ public func setScreenOrientation(orientation: Int, completion: CompletionClosure
 This API is used to make a (one-to-one) call.
 
 > **Note：**
->
 > It is recommended to use the [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)) API
 >
 
@@ -154,7 +153,6 @@ public func call(userId: String, callMediaType: TUICallMediaType)
 This API is used to make a (one-to-one) call, support for custom room ID, call timeout, offline push content, etc.
 
 > **Note：**
->
 > It is recommended to use the [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)) API
 >
 
@@ -174,7 +172,6 @@ public func call(userId: String, callMediaType: TUICallMediaType, params: TUICal
 This API is used to make a group call.
 
 > **Note:**
->
 > - It is recommended to use the [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)) API
 > - Before making a group call, you need to create a Chat group first.
 > - For details about how to create a group, see [Chat Group Management](https://www.tencentcloud.com/en/document/product/1047/48466#.E5.88.9B.E5.BB.BA.E7.BE.A4.E7.BB.84), or you can use [Chat UIKit](https://www.tencentcloud.com/document/product/1047/50056) to integrate chat, call and other scenarios.
@@ -194,7 +191,6 @@ public func groupCall(groupId: String, userIdList: [String], callMediaType: TUIC
 This API is used to make a group call, support for custom room ID, call timeout, offline push content, etc.
 
 > **Note:**
->
 > - It is recommended to use the [calls](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/callstore/calls(participantids:callmediatype:params:completion:)) API.
 > - Before making a group call, you need to create a Chat group first.
 > - For details about how to create a group, see [Chat Group Management](https://www.tencentcloud.com/en/document/product/1047/48466#.E5.88.9B.E5.BB.BA.E7.BE.A4.E7.BB.84), or you can use [Chat UIKit](https://www.tencentcloud.com/document/product/1047/50056) to integrate chat, call and other scenarios.

package/resource/knowledge/callkit/preset/react/api.md

@@ -36,7 +36,7 @@ The TUICallKit API is the **audio and video call component that includes a UI in
 |afterCalling|This function will be executed after the termination of the call|function()|No|-|√|√|
 |onMinimized|This function will be executed when the component switches to a minimized state. The explanation for the STATUS value is|function(oldStatus, newStatus)|No|-|√|√|
 |kickedOut|The events thrown by the component occur when the current logged-in user is ejected. The call will also automatically terminate|function()|No|-|√|×|
-|statusChanged|Event thrown by the component; this event is triggered when the call status changes. For detailed types of call status, refer to STATUS value description|function({oldStatus, newStatus})|No|-|√|×|
+|statusChanged|Event thrown by the component; this event is triggered when the call status changes. For detailed types of call status,
 
 ### Sample code
 
@@ -83,9 +83,9 @@ try {
 The parameters are described below:
 | Parameter | Type | Required | Meaning |
 | --- | --- | --- | --- |
-| SDKAppID | Number | Yes | The SDKAppID of your app, you can find your SDKAppID in the Live Audio and Video console. For details, see Activating Services |
+| SDKAppID | Number | Yes | The SDKAppID of your app, you can find your SDKAppID in the Live Audio and Video console.
 | userID | String | Yes | The current user's ID is of string type, only allowing for the inclusion of English letters (a-z and A-Z), digits (0-9), hyphens (-) and underscores (_) |
-| userSig | String | Yes | Use SDKSecretKey to encrypt SDKAppID, UserID and other information to obtain userSig.<br>It is an authentication ticket used by Tencent Cloud to identify whether the current user can use TRTC services. For how to obtain it, please refer to How to Calculate UserSig |
+| userSig | String | Yes | Use SDKSecretKey to encrypt SDKAppID, UserID and other information to obtain userSig.<br>It is an authentication ticket used by Tencent Cloud to identify whether the current user can use TRTC services. For how to obtain it, please
 | tim | TencentCloudChat | No | tim is an instance of <a href="https://www.npmjs.com/package/@tencentcloud/chat">TencentCloudChat</a> SDK. |
 
 ### calls
@@ -151,7 +151,6 @@ The parameters are described below:
 Set your own nickname and avatar.
 
 > **Note:**
->
 > **If you use this interface to modify user information during a call, the UI will not be updated immediately, and you will need to wait until the next call to see the changes.**
 >
 

package/resource/knowledge/callkit/preset/vue/api.md

@@ -36,7 +36,7 @@ The TUICallKit API is the **audio and video call component that includes a UI in
 |afterCalling|This function will be executed after the termination of the call|function()|No|-|√|√|
 |onMinimized|This function will be executed when the component switches to a minimized state. The explanation for the STATUS value is|function(oldStatus, newStatus)|No|-|√|√|
 |kickedOut|The events thrown by the component occur when the current logged-in user is ejected. The call will also automatically terminate|function()|No|-|√|×|
-|statusChanged|Event thrown by the component; this event is triggered when the call status changes. For detailed types of call status, refer to STATUS value description|function({oldStatus, newStatus})|No|-|√|×|
+|statusChanged|Event thrown by the component; this event is triggered when the call status changes. For detailed types of call status,
 
 ### Sample code
 
@@ -103,9 +103,9 @@ try {
 The parameters are described below:
 | Parameter | Type | Required | Meaning |
 | --- | --- | --- | --- |
-| SDKAppID | Number | Yes | The SDKAppID of your app, you can find your SDKAppID in the Live Audio and Video console. For details, see Activating Services |
+| SDKAppID | Number | Yes | The SDKAppID of your app, you can find your SDKAppID in the Live Audio and Video console.
 | userID | String | Yes | The current user's ID is of string type, only allowing for the inclusion of English letters (a-z and A-Z), digits (0-9), hyphens (-) and underscores (_) |
-| userSig | String | Yes | Use SDKSecretKey to encrypt SDKAppID, UserID and other information to obtain userSig.<br>It is an authentication ticket used by Tencent Cloud to identify whether the current user can use TRTC services. For how to obtain it, please refer to How to Calculate UserSig |
+| userSig | String | Yes | Use SDKSecretKey to encrypt SDKAppID, UserID and other information to obtain userSig.<br>It is an authentication ticket used by Tencent Cloud to identify whether the current user can use TRTC services. For how to obtain it, please
 | tim | TencentCloudChat | No | tim is an instance of <a href="https://www.npmjs.com/package/@tencentcloud/chat">TencentCloudChat</a> SDK. |
 
 ### calls
@@ -171,7 +171,6 @@ The parameters are described below:
 Set your own nickname and avatar.
 
 > **Note:**
->
 > **If you use this interface to modify user information during a call, the UI will not be updated immediately, and you will need to wait until the next call to see the changes.**
 >
 

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`?