@tencent-rtc/mcp 1.6.8 → 1.7.0

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/urls/sdk/web.md

@@ -21,7 +21,7 @@
 | Text message (createTextMessage → sendMessage) | `https://trtc.io/document/47993` |
 | Group @ message (createTextAtMessage → sendMessage) | `https://trtc.io/document/47993` |
 | Image message (createImageMessage → sendMessage) | `https://trtc.io/document/47993` |
-| Voice message (createVoiceMessage → sendMessage) | `https://trtc.io/document/47993` |
+| Audio message (createAudioMessage → sendMessage) | `https://trtc.io/document/47993` |
 | Video message (createVideoMessage → sendMessage) | `https://trtc.io/document/47993` |
 | File message (createFileMessage → sendMessage) | `https://trtc.io/document/47993` |
 | Custom message (createCustomMessage → sendMessage) | `https://trtc.io/document/47993` |

package/resource/knowledge/livekit/best-practice/android/voice-room-anchor-start.md

@@ -0,0 +1,120 @@
+---
+title: "Voice Room Anchor Creates Room and Starts Streaming (Android)（语聊房 / 房主 / 开播 / createLive）"
+product: live
+frameworks: [android]
+scope: platform_specific
+tags: [voice room, anchor, start streaming, publish audio, createLive, openLocalMicrophone, muteMicrophone, unmuteMicrophone, LiveListStore, AudioSalon, keepOwnerOnSeat, seatMode, TakeSeatMode, Android]
+version_range: ">=2.0.0"
+---
+
+# Voice Room Anchor Creates Room and Starts Streaming (Android)
+
+## 1. Key Takeaways
+
+- Voice room streaming flow: construct `LiveInfo` (with `liveID`, `seatTemplate`, `keepOwnerOnSeat`, `seatMode`), call `createLive` to create the room; on success, call `openLocalMicrophone` to capture and publish audio so other users in the room can hear the anchor.
+- `liveID` is required — it is the unique identifier of the live room.
+- Setting `keepOwnerOnSeat` to `true` makes the anchor automatically take a seat upon entering the room (taking a seat is a prerequisite for publishing audio — only seated users can publish audio streams in the room).
+- `seatTemplate` should be set to `SeatLayoutTemplate.AudioSalon(n)`, where n is the maximum seat count supported by the plan or a value less than it.
+- `seatMode` sets the seat-taking mode (e.g., `TakeSeatMode.APPLY` for apply-to-take-seat).
+- `muteMicrophone` pauses publishing local audio; `unmuteMicrophone` resumes publishing local audio.
+
+## 2. Field / API Reference
+
+| Field / Capability | Purpose | Notes |
+|---|---|---|
+| `LiveInfo` | Room information | Contains `liveID`, `liveName`, `seatTemplate`, `keepOwnerOnSeat`, `seatMode`, etc. |
+| `liveID` | Room ID | Required parameter for `createLive` |
+| `liveName` | Room name | Display name of the room |
+| `seatTemplate` | Seat layout template | Use `SeatLayoutTemplate.AudioSalon(seatCount = n)` for voice rooms, where n ≤ max seats in plan |
+| `keepOwnerOnSeat` | Auto-seat the owner | Set to `true` so the anchor automatically takes a seat upon entering |
+| `seatMode` | Seat-taking mode | e.g., `TakeSeatMode.APPLY` for apply-to-take-seat |
+| `createLive(liveInfo, callback)` | Create room (start streaming) | Pass `LiveInfo` and `LiveInfoCompletionHandler` callback |
+| `openLocalMicrophone` | Capture and publish audio | Opens local microphone and publishes audio stream to the room |
+| `muteMicrophone` | Pause audio publishing | Pauses local audio stream while microphone remains open |
+| `unmuteMicrophone` | Resume audio publishing | Resumes local audio stream while microphone remains open |
+
+## 3. Mechanism & Sequence
+
+Construct `LiveInfo` (`liveID` required, `seatTemplate=AudioSalon(n)`, `keepOwnerOnSeat=true`, `seatMode` as needed) -> call `createLive` to create the room -> `onSuccess` callback fires, anchor is auto-seated -> call `openLocalMicrophone` to capture and publish audio -> other users in the room hear the anchor.
+
+Taking a seat is a prerequisite for streaming: `keepOwnerOnSeat=true` ensures the anchor takes a seat before publishing audio. `muteMicrophone` / `unmuteMicrophone` are used to pause/resume during streaming.
+
+## 4. Standard Usage
+
+1. Construct `LiveInfo`: set `liveID`, `seatTemplate`, `keepOwnerOnSeat`, `seatMode`.
+2. Implement `LiveInfoCompletionHandler` and call `createLive` to start streaming.
+3. In `onSuccess` callback, call `openLocalMicrophone` to capture and publish audio.
+4. Call `muteMicrophone` / `unmuteMicrophone` to pause/resume streaming as needed.
+
+```kotlin
+import android.util.Log
+import androidx.appcompat.app.AppCompatActivity
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfo
+import io.trtc.tuikit.atomicxcore.api.live.LiveInfoCompletionHandler
+import io.trtc.tuikit.atomicxcore.api.live.TakeSeatMode
+
+class YourAnchorActivity : AppCompatActivity() {
+    // ... 其他代码 ...
+
+    private fun startLive() {
+        val liveInfo = LiveInfo().apply {
+            // 1. 设置房间基础信息
+            liveID = this@YourAnchorActivity.liveID
+            liveName = "test 语聊房"
+
+            // 2. 设置语聊房麦位模板，seatCount 传入所需麦位数（≤ 套餐最大麦位数）
+            seatTemplate = SeatLayoutTemplate.AudioSalon(seatCount = 9)
+
+            // 3. 主播开播后自动上麦（上麦后才能推音频流）
+            keepOwnerOnSeat = true
+
+            // 4. 设置上麦模式（例如申请上麦）
+            seatMode = TakeSeatMode.APPLY
+        }
+
+        // 5. 调用 createLive 创建房间（开播）
+        liveListStore.createLive(liveInfo, object : LiveInfoCompletionHandler {
+            override fun onFailure(code: Int, desc: String) {
+                Log.e("Live", "Response startLive onError: $desc")
+            }
+
+            override fun onSuccess(liveInfo: LiveInfo) {
+                Log.d("Live", "Response startLive onSuccess")
+                // 6. 房主创建成功后默认自动上麦，此时调用 openLocalMicrophone 采集并发布音频
+                liveSeatStore.openLocalMicrophone(null)
+            }
+        })
+    }
+}
+```
+
+## 5. Expected Results
+
+- `onSuccess` callback fires: room created successfully, anchor is auto-seated.
+- After `openLocalMicrophone`: other users in the room can hear the anchor.
+- After `muteMicrophone`: local audio publishing is paused; after `unmuteMicrophone`: publishing resumes.
+- If `keepOwnerOnSeat` is not set to `true`: the anchor is not auto-seated and cannot publish audio.
+- `onFailure(code, desc)` callback fires: streaming failed, `code` is the error code, `desc` is the error description.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Calling `openLocalMicrophone` without calling `createLive` first (cannot publish audio without creating a room).
+- Pitfall 2: Not setting `keepOwnerOnSeat` to `true`, so the anchor is not seated and audio publishing does not work.
+- Pitfall 3: Not setting `seatTemplate` or setting `seatCount` beyond the plan's maximum seat count.
+- Pitfall 4: Confusing `muteMicrophone` (pauses audio stream publishing) with closing the microphone (stops audio capture).
+- Pitfall 5: Reusing `liveID` (it must be globally unique; otherwise creation fails).
+- Pitfall 6: Confusing `onSuccess` and `onFailure` callbacks (both branches require defensive handling).
+
+## 7. Problem Definition (retrieval hint)
+
+An Android voice room anchor needs to create a room and start audio streaming in the correct order, understanding the call timing and parameter meanings of `createLive`, `openLocalMicrophone`, `muteMicrophone`, and `unmuteMicrophone`.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How does an Android voice room anchor start streaming?
+- What is the call order of `createLive` and `openLocalMicrophone` on Android?
+- How does an Android anchor take a seat and publish audio?
+- What does the `keepOwnerOnSeat` parameter do?
+- How to set the `AudioSalon` template for `seatTemplate`?
+- What is the difference between `muteMicrophone` and `unmuteMicrophone` on Android?
+- How to publish audio after creating a voice room?