@tencent-rtc/mcp 1.6.7 → 1.7.0

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

package/resource/knowledge/chat/best-practice/common/message-risk-error-and-render.md

@@ -0,0 +1,65 @@
+---
+title: "Web/Mini Program Chat SDK: Message Sending Error (80001/80004) and Content Moderation Rendering Strategy（发送消息报错 80001、80004 / 触发审核的消息渲染标识）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [sendMessage, 80001, 80004, hasRiskContent, MESSAGE_MODIFIED, cloud moderation, text moderation, image moderation, async moderation, audio message, video message]
+version_range: ">=3.0.0"
+---
+
+# Web/Mini Program Chat SDK: Message Sending Error (80001/80004) and Content Moderation Rendering Strategy
+
+## 1. Key Takeaways
+
+- Text sending error `80001` indicates the text has hit a sensitive content moderation policy; investigate the message content and cloud-side sensitive word configuration.
+- Image sending error `80004` indicates the image has hit a sensitive content moderation policy; investigate the image content and cloud-side image moderation rules.
+- The standard field for determining whether a message has been flagged by moderation on the UI side is `message.hasRiskContent`.
+- To receive `80001/80004` in `sendMessage`'s `catch` during synchronous moderation, you must enable "Deliver Blocking Error Code" in the IM console (Console > Cloud Moderation > Moderation Result Configuration > Deliver Blocking Error Code).
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| Error code `80001` | Text moderation blocking signal | Returned when a text message hits a sensitive policy |
+| Error code `80004` | Image moderation blocking signal | Returned when an image message hits a sensitive policy |
+| `message.hasRiskContent` | Risk content flag | Used by the UI to determine whether a message has been flagged by moderation |
+| `EVENT.MESSAGE_MODIFIED` | Message modified notification event | After async moderation hits, the SDK delivers message field updates via this event |
+| "Deliver Blocking Error Code" switch | Synchronous error return control | Must be enabled for `sendMessage.catch` to receive moderation blocking error codes |
+
+## 3. Mechanism & Sequence
+
+Text messages use synchronous moderation: send message -> moderation hit -> `sendMessage.catch` returns `80001`; the returned `message.hasRiskContent=true`. In the text synchronous moderation hit scenario, the `EVENT.MESSAGE_MODIFIED` event is not dispatched.
+Image messages default to synchronous moderation: send message -> if moderation completes and hits within 2 seconds -> `sendMessage.catch` returns `80004`; if moderation does not complete within 2 seconds -> automatically switches to async moderation; after async moderation hits, the update is delivered via `EVENT.MESSAGE_MODIFIED`.
+Audio/video messages default to async moderation: send message -> backend performs async moderation -> after moderation hits, the update is delivered via `EVENT.MESSAGE_MODIFIED`.
+
+## 4. Standard Usage
+
+1. Enable "Deliver Blocking Error Code" in the console to ensure `sendMessage.catch` can detect the error code during synchronous moderation hits.
+2. When sending text/image messages, read the error code and the returned `message` in the `catch` branch; if `message.hasRiskContent=true`, immediately update the on-screen message status.
+3. Listen to `EVENT.MESSAGE_MODIFIED`, iterate over `event.data`, and update the corresponding on-screen message when `message.hasRiskContent=true` is found.
+4. When the text/image hit rate is abnormal, review the sensitive word library and image moderation rules respectively, and coordinate cloud moderation strategy adjustments.
+5. Use `hasRiskContent` uniformly for UI rendering decisions; do not rely on a single error code for long-term state determination.
+
+## 5. Expected Results
+
+- When text hits a sensitive word, `sendMessage.catch` observes `80001` and the message status is updated to moderation-blocked.
+- When an image hits a sensitive rule, it is received via the synchronous path as `80004`, or via the async path through `MESSAGE_MODIFIED` with `hasRiskContent=true` update.
+- After async moderation hits for audio/video, the UI correctly updates the blocked status via `MESSAGE_MODIFIED`.
+- For the same message, both synchronous and async paths ultimately render a consistent state based on `hasRiskContent`.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Not enabling "Deliver Blocking Error Code" but expecting `sendMessage.catch` to always return `80001/80004`.
+- Pitfall 2: Only handling `sendMessage.catch` without listening to `MESSAGE_MODIFIED`, causing missed rendering for async moderation hits.
+- Pitfall 3: Rendering long-term state based solely on error codes without using `hasRiskContent` as the ultimate state source.
+
+## 7. Problem Definition (retrieval hint)
+
+What causes the Web Chat SDK to return `80001` when sending text and `80004` when sending images? How should the UI determine whether a message has been flagged by content moderation (risk content)?
+
+## 8. Alternative Queries (retrieval recall)
+
+- What causes text sending failure 80001?
+- What causes image sending failure 80004?
+- How does the frontend identify when a message is blocked by moderation?
+- When does `message.hasRiskContent` get updated?

package/resource/knowledge/chat/best-practice/common/message-unread-count.md

@@ -0,0 +1,71 @@
+---
+title: "Web/Mini Program Chat SDK: Total Unread Message Count and C2C/Group Split Statistics（unreadCount / 未读总数 / 单聊未读 / 群聊未读）"
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [getTotalUnreadMessageCount, TOTAL_UNREAD_MESSAGE_COUNT_UPDATED, unreadCount, total unread, C2C unread, group unread]
+version_range: ">=3.0.0"
+---
+
+# Web/Mini Program Chat SDK: Total Unread Message Count and C2C/Group Split Statistics
+
+## 1. Key Takeaways
+
+- Use `getTotalUnreadMessageCount` to get the total unread message count.
+- The SDK does not currently provide a direct API for "C2C-only unread total" or "group-only unread total".
+- The recommended pattern is "fetch once on initialization + continuous event updates": call `getTotalUnreadMessageCount` during initialization, then maintain the total unread count via `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`.
+- `getTotalUnreadMessageCount` depends on the SDK's conversation list data; if the cloud conversation list has not finished syncing when called, the return value may be `0`.
+- The SDK syncs the conversation list in pages; each sync that causes a total unread change dispatches `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `getTotalUnreadMessageCount` | Get current total unread count | Depends on the locally synced conversation list state |
+| `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` | Total unread update event | Triggered after conversation list page sync or unread count changes |
+| `CONVERSATION_LIST_UPDATED` | Conversation list update event | Can be used to get all conversations and perform C2C/group split statistics |
+| `conversation.type` | Conversation type identifier | Used to filter C2C or group conversations |
+| `conversation.unreadCount` | Per-conversation unread count | Summed up to get C2C-dimension or group-dimension total unread count |
+
+## 3. Mechanism & Sequence
+
+App starts -> SDK syncs conversation list (paginated) -> Business calls `getTotalUnreadMessageCount` during initialization to get the initial value (may be 0) -> Each time a page sync causes total unread change, SDK dispatches `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` -> Business updates total unread display in real time.
+If C2C/group dimension unread is needed: listen to `CONVERSATION_LIST_UPDATED` -> get all conversations -> filter by `conversation.type` and sum `conversation.unreadCount`.
+
+## 4. Standard Usage
+
+1. During app initialization, call `getTotalUnreadMessageCount` to get the current available total unread initial value.
+2. Listen to `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`; use the event value as the continuous update source for total unread count.
+3. Listen to `CONVERSATION_LIST_UPDATED` to get the full conversation list.
+4. Filter by `conversation.type` to separate C2C and group conversations, then sum each conversation's `unreadCount` to get the C2C unread total and group unread total.
+5. When initialization returns `0`, do not immediately conclude "no unread"; use the statistics result after the conversation list sync event as the authoritative value.
+
+## 5. Expected Results
+
+- `getTotalUnreadMessageCount` has been called during initialization, and the UI displays the initial value.
+- During the conversation list page sync process, `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED` continuously drives total unread changes.
+- C2C and group unread totals are stably derived from the `CONVERSATION_LIST_UPDATED + unreadCount` aggregation result.
+- When `0` appears during initialization, the unread count correctly refreshes to the real value once syncing completes.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming the SDK provides a ready-made API for "C2C unread total" or "group unread total".
+- Pitfall 2: Treating the `getTotalUnreadMessageCount` result of `0` during initialization as the final result.
+- Pitfall 3: Only fetching the total unread count once during initialization without listening to `TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`.
+
+## 7. Problem Definition (retrieval hint)
+
+How does the Web Chat SDK get the total unread message count? Is there an API to get only the C2C unread total or group unread total?
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to get the total IM unread message count?
+- Is there an official API for "C2C-only unread" or "group-only unread"?
+- Why does `getTotalUnreadMessageCount` return 0 during initialization?
+- Should the total unread count be updated via events or by polling the API?
+
+## 9. References
+
+- getTotalUnreadMessageCount: `https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#getTotalUnreadMessageCount`
+- TOTAL_UNREAD_MESSAGE_COUNT_UPDATED: `https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED`
+- CONVERSATION_LIST_UPDATED: `https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.CONVERSATION_LIST_UPDATED`

package/resource/knowledge/chat/best-practice/miniprogram/audio-message-send.md

@@ -0,0 +1,113 @@
+---
+title: "Mini Program: Standard Approach for Sending Audio Messages with IM SDK（recorderManager / createAudioMessage / sendMessage / 小程序发送语音消息）"
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [audio, voice, recorderManager, createAudioMessage, sendMessage, aac, miniprogram]
+version_range: ">=3.0.0"
+---
+
+# Mini Program: Standard Approach for Sending Audio Messages with IM SDK
+
+## 1. Key Takeaways
+
+- On the mini program side, use the official WeChat `RecorderManager` for recording, then call `createAudioMessage` in the `onStop` callback to create the audio message.
+- After message creation, send it via `sendMessage`; the send result is determined by the Promise success/failure callback.
+- Using `aac` audio format enables cross-platform interoperability across IM on Android, iOS, Mini Program, and Web.
+- Recording parameters must be explicitly configured: `duration`, `sampleRate`, `numberOfChannels`, `encodeBitRate`, `format`; also listen to `onError` to handle recording exceptions.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `wx.getRecorderManager()` | Recording entry | Gets the globally unique recorder manager instance |
+| `recordOptions.format` | Audio format control | Set to `aac` for cross-platform interoperability |
+| `recorderManager.onStop(res)` | Recording result callback | Use `res` in the callback to create the audio message |
+| `chat.createAudioMessage({...})` | Create message instance | Generates an audio message object ready for rendering and sending |
+| `chat.sendMessage(message)` | Send message | Returns a Promise; `then` for success, `catch` for failure |
+
+## 3. Mechanism & Sequence
+
+Initialize `RecorderManager` -> Configure recording parameters -> Start recording -> Listen to `onStop` to get the recording result -> Call `createAudioMessage` to create the audio message -> Call `sendMessage` to send -> Update UI and logs based on send result.
+
+## 4. Standard Usage
+
+1. Get the recorder manager and configure recording parameters with `format` set to `aac`.
+2. Register `onError` and `onStop` callbacks; create the audio message based on the recording result in `onStop`.
+3. Call `sendMessage` to send the audio message and handle success/failure callbacks.
+4. Render the message instance on screen, and prompt retry on failure.
+
+```javascript
+// 示例：使用微信官方的 RecorderManager 进行录音
+// 参考 https://developers.weixin.qq.com/minigame/dev/api/media/recorder/RecorderManager.start.html
+// 1. 获取全局唯一的录音管理器 RecorderManager
+const recorderManager = wx.getRecorderManager();
+
+// 录音部分参数
+const recordOptions = {
+  duration: 60000, // 录音的时长，单位 ms，最大值 600000（10 分钟）
+  sampleRate: 44100, // 采样率
+  numberOfChannels: 1, // 录音通道数
+  encodeBitRate: 192000, // 编码码率
+  format: 'aac' // 音频格式，选择此格式创建的音频消息可以在 IM 全平台互通
+};
+
+// 2.1 监听录音错误事件
+recorderManager.onError(function(errMsg) {
+  console.warn('recorder error:', errMsg);
+});
+
+// 2.2 监听录音结束事件，录音结束后创建并发送音频消息
+recorderManager.onStop(function(res) {
+  console.log('recorder stop', res);
+
+  // 4. 创建消息实例，接口返回的实例可以上屏
+  const message = chat.createAudioMessage({
+    to: 'user1',
+    conversationType: TencentCloudChat.TYPES.CONV_C2C,
+    // 消息优先级，用于群聊
+    // priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,
+    payload: {
+      file: res
+    },
+    // 消息自定义数据（云端保存，会发送到对端，程序卸载重装后还能拉取到）
+    // cloudCustomData: 'your cloud custom data'
+  });
+
+  // 5. 发送消息
+  chat.sendMessage(message).then(function(imResponse) {
+    // 发送成功
+    console.log(imResponse);
+  }).catch(function(imError) {
+    // 发送失败
+    console.warn('sendMessage error:', imError);
+  });
+});
+
+// 3. 开始录音
+recorderManager.start(recordOptions);
+```
+
+## 5. Expected Results
+
+- After recording ends, `onStop` is triggered reliably and a voice message instance is created successfully.
+- On successful send, the `sendMessage` Promise enters `then` and the message renders on screen.
+- The audio message can be played on Android, iOS, Mini Program, and Web (using `aac` format).
+- On recording exceptions, `onError` provides clear logs with no silent failures.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Not creating the message in the `onStop` callback, resulting in no valid audio file at send time.
+- Pitfall 2: Not using `aac` for the audio format, causing cross-platform interoperability issues.
+- Pitfall 3: Only calling `createAudioMessage` without calling `sendMessage`, mistakenly thinking the message has been sent.
+
+## 7. Problem Definition (retrieval hint)
+
+When integrating IM SDK in a mini program, how to complete voice recording, create an audio message, and send it while ensuring cross-platform interoperability.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to send an audio message with the mini program IM SDK?
+- How to use `createAudioMessage` to send a message after recording in a mini program?
+- How to integrate `RecorderManager` recording result with IM sending?
+- What audio format allows interoperability with Android/iOS/Web?

package/resource/knowledge/chat/best-practice/miniprogram/login-timeout-2801-diagnosis.md

@@ -0,0 +1,63 @@
+---
+title: "Mini Program: IM SDK Login Timeout 2801 Diagnosis and Fix（小程序体验版和正式版登录超时 / 开发版正常）"
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [login, timeout, 2801, websocket, domain allowlist, debug mode, ipv6]
+version_range: ">=3.0.0"
+---
+
+# Mini Program: IM SDK Login Timeout 2801 Diagnosis and Fix
+
+## 1. Key Takeaways
+
+- The primary item to check in this scenario is whether the `websocket` domain allowlist is fully configured in the mini program management backend.
+- The validation policies differ between dev builds and preview/production builds; a successful login in the dev build does not guarantee the allowlist is correctly configured.
+- Preview builds can enable debug mode for verification: debug mode bypasses domain allowlist validation and can be used to quickly determine whether the issue is caused by the allowlist.
+- The dedicated domain `wss://${SDKAppID}w4c.my-imcloud.com` requires SDK `v3.4.6` or above.
+- The IPv6 domain `wss://wssv6.im.qcloud.com` requires SDK `v3.4.9` or above.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| Error code `2801` | Login timeout signal | When this occurs in preview/production builds, prioritize checking network connectivity and domain allowlist |
+| `websocket` domain allowlist | Connection access control | Incomplete allowlist configuration causes connection failure or timeout in non-dev builds |
+| Preview build debug mode | Diagnostic tool | Bypasses domain allowlist validation; used to verify whether the allowlist is the root cause |
+| `wss://${SDKAppID}w4c.my-imcloud.com` | Dedicated domain | Supported from SDK `v3.4.6+` |
+| `wss://wssv6.im.qcloud.com` | IPv6 domain | Supported from SDK `v3.4.9+` |
+
+## 3. Mechanism & Sequence
+
+Dev build can log in -> Preview/production build login times out (2801) -> Check `websocket` domain allowlist in mini program management backend -> Enable debug mode in preview build and retest -> If debug mode resolves the issue, confirm it is an allowlist configuration problem.
+
+## 4. Standard Usage
+
+1. Log in to the mini program management backend and check whether the `websocket` domain allowlist is fully configured. Reference: `https://cloud.tencent.com/document/product/269/117335`.
+2. Enable debug mode in the preview build and retest login.
+3. If login recovers after enabling debug mode, complete/correct the `websocket` domain configuration per allowlist specifications.
+4. Verify the login path again in both preview and production builds to confirm 2801 no longer occurs.
+
+## 5. Expected Results
+
+- Preview build can log in stably with debug mode disabled.
+- Production build login no longer shows the 2801 timeout.
+- The mini program backend `websocket` domain allowlist is fully consistent with the current connected domains.
+- If using a dedicated domain or IPv6 domain, the SDK version meets `v3.4.6+` / `v3.4.9+` respectively.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming the domain allowlist is correctly configured just because the dev build can log in.
+- Pitfall 2: Only verifying in debug mode and then directly publishing to production.
+- Pitfall 3: Using a dedicated domain or IPv6 domain while ignoring the minimum SDK version requirement.
+
+## 7. Problem Definition (retrieval hint)
+
+When integrating IM SDK in a mini program, the dev build logs in successfully, but the preview and production builds get a login timeout (2801).
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to handle IM login 2801 in a preview mini program?
+- Why can the dev build log in but the preview and production builds timeout?
+- Is preview build login timeout related to the websocket domain allowlist?
+- Can a missing websocket allowlist entry cause IM login failure in a mini program?

package/resource/knowledge/chat/best-practice/miniprogram/media-upload-fail-diagnosis.md

@@ -0,0 +1,64 @@
+---
+title: "Mini Program: IM SDK Media Upload Failure Diagnosis and Fix (Image/Video/Audio/File)（小程序体验版和正式版偶现发送图片、视频、语音、文件失败 / 开发版正常）"
+product: chat
+frameworks: [miniprogram]
+scope: platform_specific
+tags: [upload, media, image, video, audio, file, uploadFile, domain allowlist, debug mode, COS dedicated domain]
+version_range: ">=3.0.0"
+---
+
+# Mini Program: IM SDK Media Upload Failure Diagnosis and Fix (Image/Video/Audio/File)
+
+## 1. Key Takeaways
+
+- The primary item to check in this scenario is whether the `uploadFile` domain allowlist is fully configured in the mini program management backend.
+- The validation policies differ between dev builds and preview/production builds; successful uploads in the dev build do not guarantee the allowlist is correctly configured.
+- Preview builds can enable debug mode for verification: debug mode bypasses domain allowlist validation and can be used to quickly determine whether the issue is caused by the `uploadFile` domain configuration.
+- Starting from 2024-09-10, newly created apps are assigned a COS dedicated domain `https://${SDKAppID}-cn.rich.my-imcloud.com` by default.
+- When using the COS dedicated domain, it must be added to the mini program `uploadFile` allowed domain allowlist.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `uploadFile` domain allowlist | Upload channel access control | Incomplete allowlist configuration causes upload failures in preview/production builds |
+| Preview build debug mode | Diagnostic tool | Bypasses domain allowlist validation; used to verify whether the allowlist is the root cause |
+| `https://${SDKAppID}-cn.rich.my-imcloud.com` | COS dedicated domain | Assigned by default for new apps; must be added to the `uploadFile` allowlist |
+| Media message types (image/video/audio/file) | Affected scope | All share the `uploadFile` path and are affected by allowlist configuration |
+
+## 3. Mechanism & Sequence
+
+Dev build uploads successfully -> Preview/production build uploads fail -> Check `uploadFile` domain allowlist in mini program management backend -> Enable debug mode in preview build and retest -> If debug mode resolves the issue, confirm it is an allowlist configuration problem.
+
+## 4. Standard Usage
+
+1. Log in to the mini program management backend and check whether the `uploadFile` allowed domains are fully configured. Reference: `https://cloud.tencent.com/document/product/269/117335`.
+2. Verify and add the upload domains actually used by the current app, with special attention to confirming that the COS dedicated domain `https://${SDKAppID}-cn.rich.my-imcloud.com` is allowlisted.
+3. Enable debug mode in the preview build and retest image/video/audio/file uploads.
+4. If uploads recover after enabling debug mode, complete/correct the `uploadFile` domain configuration per allowlist specifications.
+5. After disabling debug mode, verify the upload path again in both preview and production builds.
+
+## 5. Expected Results
+
+- Preview build can upload images/videos/audio/files successfully with debug mode disabled.
+- Production build upload path is stable with no upload failures.
+- The mini program backend `uploadFile` domain allowlist is fully consistent with the current connected domains.
+- COS dedicated domain `https://${SDKAppID}-cn.rich.my-imcloud.com` has been added to the allowlist (applicable for new apps).
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming the domain allowlist is correctly configured just because the dev build uploads successfully.
+- Pitfall 2: Only verifying in debug mode and then directly publishing to production.
+- Pitfall 3: Only checking `request` or `websocket` allowlists while ignoring the `uploadFile` allowlist.
+- Pitfall 4: After a new app enables the COS dedicated domain, not syncing the `uploadFile` allowlist update.
+
+## 7. Problem Definition (retrieval hint)
+
+When integrating IM SDK in a mini program, the dev build can upload images/videos/audio/files normally, but the preview and production builds fail to upload.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to fix image upload failure in a preview mini program with IM?
+- Why can the dev build upload but the preview and production builds fail?
+- Can a missing `uploadFile` domain allowlist entry cause IM upload failure in a mini program?
+- What does it mean when uploads recover after enabling debug mode in the preview build?

package/resource/knowledge/chat/best-practice/web/audio-message-send.md

@@ -0,0 +1,118 @@
+---
+title: "Web (PC/H5): Standard Approach for Sending Audio Messages with IM SDK（pc/h5发送语音消息）"
+product: chat
+frameworks: [web]
+scope: platform_specific
+tags: [audio, voice, createAudioMessage, sendMessage, Recorder, js-audio-recorder, h5, pc]
+version_range: ">=3.0.0"
+---
+
+# Web (PC/H5): Standard Approach for Sending Audio Messages with IM SDK
+
+## 1. Key Takeaways
+
+- On the Web side, you can use a third-party recording library (e.g., `js-audio-recorder`) to record audio, then convert the recording result to a `File` and call `createAudioMessage`.
+- The `audioFile` must have a `uri` field set (`audioFile.uri = window.URL.createObjectURL(audioFile)`); otherwise the audio message creation and sending pipeline is incomplete.
+- After message creation, send it via `sendMessage`; the send result is determined by the Promise success/failure callback.
+- It is recommended to pass an `onProgress` callback in `createAudioMessage` to monitor audio upload progress in real time.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Description |
+|---|---|---|
+| `Recorder` | Recording capability | Captures audio data in the browser |
+| `recorder.getWAVBlob()` | Export recording data | Gets WAV binary data for constructing a `File` |
+| `audioFile.uri` | Local accessible address | Required field; generated using `window.URL.createObjectURL(audioFile)` |
+| `chat.createAudioMessage({...})` | Create audio message instance | Generates an audio message object ready for rendering and sending |
+| `chat.sendMessage(message)` | Send message | Returns a Promise; `then` for success, `catch` for failure |
+| `onProgress` | Upload progress callback | Monitors the audio file upload process |
+
+## 3. Mechanism & Sequence
+
+Start recording -> Stop recording -> Calculate duration and get WAV Blob -> Convert to `File` and add `uri` and `duration` -> Call `createAudioMessage` to create the audio message -> Call `sendMessage` to send -> Update UI and logs based on send result.
+
+## 4. Standard Usage
+
+1. Start recording with the recorder and record the start timestamp.
+2. After stopping recording, calculate the duration and get the `WAV Blob`.
+3. Convert the `Blob` to a `File` and set `audioFile.uri` and `audioFile.duration`.
+4. Call `createAudioMessage` to create the audio message, passing in the `onProgress` callback.
+5. Call `sendMessage` to send the audio message and handle success and failure branches.
+
+```javascript
+// 在 Web 端创建语音消息并发送
+// 示例：使用第三方库 js-audio-recorder 录制音频
+
+// 1. 开始录制
+let recorder = new Recorder({
+  sampleBits: 16, // 采样位数，支持 8 或 16，默认 16
+  sampleRate: 16000, // 采样率
+  numChannels: 1 // 声道，支持 1 或 2，默认 1
+});
+
+let startTs;
+recorder.start().then(() => {
+  // 开始录音，记录起始时间戳
+  startTs = Date.now();
+}, (error) => {
+  // 出错了
+  console.log(`${error.name} : ${error.message}`);
+});
+
+// 2. 结束录制
+recorder.stop();
+
+// 3. 计算录音时长，获取 WAV 数据
+let duration = Date.now() - startTs; // 单位：ms
+let wavBlob = recorder.getWAVBlob();
+
+// 4. blob 数据转成 File 对象
+let audioFile = new File([wavBlob], 'hello.wav', { type: 'wav' });
+audioFile.uri = window.URL.createObjectURL(audioFile);
+audioFile.duration = duration;
+
+// 5. 创建音频消息
+let message = chat.createAudioMessage({
+  to: 'user1',
+  conversationType: 'C2C',
+  payload: {
+    file: audioFile
+  },
+  // 音频上传进度回调
+  onProgress: function(event) {
+    console.log('file uploading:', event);
+  }
+});
+
+// 6. 发送消息
+chat.sendMessage(message).then(function(imResponse) {
+  // 发送成功
+  console.log(imResponse);
+}).catch(function(imError) {
+  // 发送失败
+  console.warn('sendMessage error:', imError);
+});
+```
+
+## 5. Expected Results
+
+- After recording ends, `wavBlob` is reliably obtained and `audioFile` is constructed successfully.
+- `audioFile.uri` is set, and `createAudioMessage` creates the audio message normally.
+- `sendMessage` enters `then` on success; the audio message renders on screen and is playable.
+- During upload, `onProgress` callbacks are received; on failure, `catch` provides clear error logs.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Not setting `audioFile.uri` before sending, causing the message pipeline to fail.
+- Pitfall 2: Only creating the message without sending it, mistakenly thinking the message has been delivered.
+- Pitfall 3: Not correctly calculating the duration or packaging the file after recording ends, causing the audio to be unusable.
+
+## 7. Problem Definition (retrieval hint)
+
+When integrating IM SDK on Web (PC/H5), how to complete voice recording and reliably send audio messages.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to send an audio message with the Web IM SDK?
+- How to call `createAudioMessage` after recording on PC/H5?
+- Why must `audioFile.uri` be set?

package/resource/knowledge/chat/preset/android/features/chat-setting.md

@@ -3,9 +3,6 @@
 ChatSetting is a set of chat settings components built with Jetpack Compose. It includes two main components: C2CChatSetting (C2C Chat Settings) and GroupChatSetting (Group Chat Settings).
 
 These components offer comprehensive chat session management features, such as user information management, permission controls, group management, and other essential capabilities.
-| <strong>C2C Chat Settings Interface</strong> | <strong>Group Chat Settings Interface</strong> |
-| --- | --- |
-|  |  |
 
 ## Component Integration
 
@@ -40,7 +37,6 @@ ChatSetting consists of two main components: C2CChatSetting (C2C Chat Settings)
 
 ## Basic Usage
 
-To display the C2C Chat Settings page, initialize C2CChatSetting as shown below:
 ``` swift
 Box {
     C2CChatSetting(
@@ -55,7 +51,6 @@ Box {
 }
 ```
 
-To display the Group Chat Settings page, initialize GroupChatSetting as shown below:
 ``` swift
 Box {
     GroupChatSetting(

package/resource/knowledge/chat/preset/android/features/contact-list.md

@@ -1,9 +1,6 @@
 ## Component Overview
 
 ContactList is a Jetpack Compose-based contact list component that provides users with robust contact management features. It supports displaying friends, handling friend requests, managing group lists, managing blacklists, and offers a comprehensive set of interactive webhook interfaces.
-| <strong>Contact List</strong> | <strong>Group List</strong> | <strong>Friend Request List</strong> |
-| --- | --- | --- |
-|  |  |  |
 
 ## Component Integration
 
@@ -19,15 +16,11 @@ The `ContactList` component is included in TUIKit Compose. To use `ContactList`,
 | <code>onContactClick: (ContactInfo) -> Unit</code> | Webhook triggered when a contact is clicked; this parameter is optional. |  |
 | <code>contactListViewModelFactory: ContactListViewModelFactory</code> | Factory for creating the internal ContactListViewModel. Typically, you do not need to provide this manually, as a default implementation is included. |  |
 
-The top section of `ContactList` provides entry points for subviews such as friend requests, group chat requests, group chat list, and blacklist. The bottom section displays the contact list, as shown below:
-
 ## Basic Usage
 - When you tap the entry points for friend requests, group chat requests, group chat list, or blacklist in `ContactList`, the component automatically handles navigation—no extra configuration is required.
 
 - When you tap a group in the group chat list or a contact in the contact list or blacklist, the corresponding webhook (`onGroupClick` or `onContactClick`) is triggered. You must handle these webhooks to implement custom navigation. See the routing example below:
 
-   To display the contact list directly, initialize `ContactList` as shown below:
-
    ``` swift
    Box(
        modifier = Modifier

package/resource/knowledge/chat/preset/android/features/conversation-list.md

@@ -1,9 +1,6 @@
 ## Component Overview
 
 ConversationList is a Jetpack Compose component designed to display and manage user chat conversations. It offers a comprehensive set of features for viewing and interacting with conversations.
-| <strong>Conversation List</strong> | <strong>Conversation Actions</strong> |
-| --- | --- |
-|  |  |
 
 ## Component Integration
 
@@ -112,6 +109,3 @@ ConversationList() {
 ```
 
 The following images show the customization effects:
-| <strong>Conversation Actions</strong><br><strong>(Default Options)</strong> | <strong>Conversation Actions</strong><br><strong>(Delete Option Hidden)</strong> | <strong>Conversation Actions</strong><br><strong>(Share Option Added)</strong> |
-| --- | --- | --- |
-|  |  |  |