@tencent-rtc/mcp 1.6.7 → 1.7.0

package/resource/knowledge/callkit/best-practice/common/call-autoplay-blocked.md

@@ -0,0 +1,77 @@
+---
+title: "Why Web TUICallKit Shows a `Resume Playback` Dialog and How to Handle It（ web TUICallKit 恢复播放弹窗）"
+product: call
+frameworks: [react, vue, web]
+scope: platform_common
+tags: [TUICallKit, resume playback, autoplay, webview, autoplay, enableAutoPlayDialog, callExperimentalAPI, no sound, vue2.6, vue2.7, vue3]
+version_range: ">=4.0.0"
+---
+
+# Why Web TUICallKit Shows a "Resume Playback" Dialog and How to Handle It
+
+## 1. Key Takeaways
+
+- Browser autoplay restriction: browsers block media with sound from playing before the user interacts with the page. When Web TUICallKit detects a playback failure, it shows a "Resume Playback" dialog requiring the user to click "Resume."
+- This issue occurs most often in webview environments (e.g., H5 pages embedded in native apps).
+- Disabling this dialog is not recommended because it may cause no-sound issues. If you must disable it, use `callExperimentalAPI` to set `enableAutoPlayDialog: 0`.
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `enableAutoPlayDialog` | Autoplay dialog toggle | `1` enabled (default), `0` disabled |
+| `callExperimentalAPI` | Invoke experimental API | Called via the TRTC instance to set `enableAutoPlayDialog` |
+| `getTUICallEngineInstance()` | Get the TUICallEngine instance | Obtained from `TUICallKitAPI` to access the underlying engine |
+| `getTRTCCloudInstance()` | Get the TRTC instance | Obtained from TUICallEngine to access the TRTC cloud instance |
+
+## 3. Mechanism & Sequence
+
+User enters the call page -> TUICallKit attempts to auto-play audio -> browser blocks autoplay -> playback fails -> TUICallKit shows the "Resume Playback" dialog -> user clicks "Resume" -> audio plays normally.
+
+In webview scenarios, the host app imposes stricter autoplay restrictions, making this issue more likely.
+
+## 4. Standard Usage
+
+Disabling the dialog is not recommended. If your use case requires it:
+
+1. Get the TUICallEngine instance from `TUICallKitAPI`.
+2. Get the TRTC cloud instance from TUICallEngine.
+3. Call `callExperimentalAPI` on the TRTC instance to set `enableAutoPlayDialog: 0`.
+
+```javascript
+// React: @trtc/calls-uikit-react
+// Vue 3: @trtc/calls-uikit-vue
+// Vue 2.7: @trtc/calls-uikit-vue2
+// Vue 2.6: @trtc/calls-uikit-vue2.6  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+const trtcCloudInstance = TUICallKitAPI?.getTUICallEngineInstance()?.getTRTCCloudInstance();
+const params = {
+  api: 'enableAutoPlayDialog',
+  params: { enable: 0 },
+};
+trtcCloudInstance?.callExperimentalAPI(JSON.stringify(params));
+```
+
+## 5. Expected Results
+
+- Dialog enabled: a "Resume Playback" prompt appears during calls; audio plays normally after the user clicks it.
+- Dialog disabled: no prompt appears during calls; audio auto-plays once the browser allows it (if still blocked, there is no sound).
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming the dialog is a TUICallKit bug (it is actually the browser's autoplay restriction policy).
+- Pitfall 2: Disabling the dialog and expecting audio to play correctly in all scenarios (disabling the dialog does not bypass the autoplay restriction; no-sound issues may still occur).
+- Pitfall 3: Calling `enableAutoPlayDialog` before TUICallKit initialization (it must be called after obtaining the TRTC instance).
+
+## 7. Problem Definition (retrieval hint)
+
+Web TUICallKit shows a "Resume Playback" dialog during calls, requiring a user click before audio is heard. How to resolve this and whether the dialog can be disabled.
+
+## 8. Alternative Queries (retrieval recall)
+
+- Why is there no sound in TUICallKit calls?
+- Why does TUICallKit show a "Resume Playback" prompt?
+- How to disable the TUICallKit autoplay dialog?
+- How to fix no sound in TUICallKit inside a webview?
+- How to configure `enableAutoPlayDialog`?

package/resource/knowledge/callkit/best-practice/common/call-message-in-chat.md

@@ -0,0 +1,78 @@
+---
+title: "How to Display Call Messages When Integrating TUICallKit with a UI-less Chat SDK Project（TUICallKit 通话消息上屏 / 通话信令字段含义）"
+product: call
+frameworks: [react, vue, miniprogram, android, ios, flutter, uni-app, web]
+scope: platform_common
+tags: [TUICallKit, call-message, custom message, actionType, cmd, call_end, call message rendering]
+version_range: ">=2.0.0"
+---
+
+# How to Display Audio/Video Call Messages When Integrating TUICallKit with a UI-less Chat SDK Project
+
+## 1. Key Takeaways
+
+- Call messages are custom messages sent by the backend via the Chat REST API during TUICallKit calls. Each platform can retrieve them through the Chat SDK's message-received event or by pulling message history.
+- Real-time call states (ringing, answering, hanging up) are handled by TUICallKit event listeners and do not rely on Chat messages.
+- Use `actionType` to determine the call result type (hang up / cancel / reject / timeout) and `cmd` to distinguish voice / video / busy.
+- Call duration is obtained from the `call_end` field, in seconds.
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `actionType` | Call event type | 1=initiate/hang up, 2=cancel, 3=answer, 4=reject, 5=timeout |
+| `cmd` | Call command subtype | `videoCall` video call, `audioCall` voice call, `hangup` hang up, `line_busy` busy |
+| `call_end` | Call duration | Present when `actionType=1` and `cmd=hangup`, in seconds |
+| `MESSAGE_RECEIVED` | Message received event | Unified Chat SDK event that includes call custom messages |
+| `getMessageList` | Pull message history | Called when entering a conversation; call messages are included in the returned list |
+
+### actionType and cmd Mapping
+
+| Scenario | actionType | cmd | Notes |
+|---|---|---|---|
+| Initiate call | 1 | `videoCall` or `audioCall` | Sent by caller |
+| Answered | 3 | — | Triggered after callee answers |
+| Call ended | 1 | `hangup` | One party hung up; `call_end` contains duration |
+| Call cancelled | 2 | — | Caller cancelled before answer |
+| Call rejected | 4 | — | Callee actively rejected |
+| Remote busy | 4 | `line_busy` | Callee is already in a call |
+| Timeout (no answer) | 5 | — | Callee did not answer within the time limit |
+
+## 3. Mechanism & Sequence
+
+Caller initiates a call -> TUICallKit establishes the call connection via a signaling channel (not Chat messages) -> during the call, each state change (cancel / answer / reject / timeout / hang up) triggers the TUICallKit backend to send a custom message to the Chat SDK via REST API -> both parties receive the message through `MESSAGE_RECEIVED` -> parse `actionType` and `cmd` to identify the event type and update the UI.
+
+The call process itself (initiate, answer, cancel, reject, timeout) does not rely on Chat custom messages for notification; Chat messages are solely used to display call records in the conversation after the call ends.
+
+## 4. Standard Usage
+
+1. Retrieve the call custom messages sent by the backend via the Chat SDK (listen to the message-received event or pull message history; the API name varies by platform but the semantics are the same).
+2. Read `message.actionType` and `message.cmd` to determine the call event type.
+3. For hang-up messages (`actionType=1, cmd=hangup`), read `message.call_end` to display the call duration.
+4. Other `actionType` values indicate why the call was not connected (cancel / reject / busy / timeout); update the UI display accordingly.
+
+## 5. Expected Results
+
+- After each call state change, a call custom message can be received via the Chat SDK.
+- `actionType` and `cmd` correctly reflect the call state change.
+- The `call_end` value accurately reflects the actual call duration.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Treating call messages as generic custom messages without reading `actionType` to distinguish states.
+- Pitfall 2: Only handling `MESSAGE_RECEIVED` without processing offline call messages pulled via `getMessageList`.
+- Pitfall 3: Calculating call duration from the `timestamp` difference between messages (should read directly from the `call_end` field).
+- Pitfall 4: Not handling the `line_busy` scenario, causing busy to be treated as a normal rejection.
+
+## 7. Problem Definition (retrieval hint)
+
+When integrating TUICallKit with a UI-less Chat SDK project, how to retrieve and render audio/video call messages (initiate / answer / hang up / cancel / reject / timeout / busy) via the Chat SDK.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to parse TUICallKit call messages?
+- What do the various `actionType` values mean?
+- How to get the call duration after a call ends?
+- How to distinguish between initiate and hang up in `MESSAGE_RECEIVED` call messages?
+- How to determine if the callee is busy?
+- Is call message parsing the same on mini programs and Web?

package/resource/knowledge/callkit/best-practice/common/call-vs-calls.md

@@ -0,0 +1,110 @@
+---
+title: "TUICallKit Difference Between calls and call/groupCall（call、groupCall 和 calls 的区别 / 参数1和2分别代表什么）"
+product: call
+frameworks: [react, vue, web]
+scope: platform_common
+tags: [call, calls, groupCall, userIDList, TUICallKit, init, v4.x, calls-uikit, vue2, vue2.6, vue2.7, vue3, call vs calls difference, callMediaType, parameters 1 and 2, numeric literal, call type, enum constant]
+version_range: ">=4.0.0"
+---
+
+# TUICallKit React/Vue: Difference Between calls and call/groupCall for Initiating Audio/Video Calls
+
+## 1. Key Takeaways
+
+- TUICallKit React / Vue **v4.x must use `calls`** to initiate one-on-one or group calls.
+- `call` and `groupCall` are deprecated since v4.0.0.
+- `init` must be completed before initiating a call; otherwise the call may fail or enter an abnormal state.
+- Use the `CallMediaType` enum constant for `type`; using numeric literals (1/2) as the primary approach is not recommended.
+- `userIDList` must be an array (even for one-on-one calls); pass `chatGroupID` only when linking with a Chat group.
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `TUICallKitAPI` | v4.x entry object | Imported from `@trtc/calls-uikit-{react\|vue}`, replaces the legacy `TUICallKitServer` |
+| `calls` | Initiate a call (v4.x) | Unified entry for one-on-one and group calls |
+| `call` / `groupCall` | Initiate a call (legacy) | Used before v4.0.0, deprecated in v4.x |
+| `CallMediaType` | Call media type enum | `AUDIO` for voice, `VIDEO` for video |
+| `roomID` / `strRoomID` | Room ID | Mutually exclusive; choose one, do not mix |
+
+## 3. Mechanism & Sequence
+
+Initialize -> log in -> call `calls` to initiate a call -> wait for callee to answer -> call established -> call ends.
+
+For new v4.x projects, start directly with `calls`. When migrating legacy projects, replace `call`/`groupCall` with `calls` and replace `TUICallKitServer` with `TUICallKitAPI`.
+
+## 4. Standard Usage
+
+1. Import `TUICallKitAPI` from the corresponding platform package.
+2. Call `TUICallKitAPI.init({ SDKAppID, userID, userSig })` to complete initialization.
+3. Call `TUICallKitAPI.calls({ userIDList, type })` to initiate a call.
+4. Handle call initiation failures in the `catch` branch.
+
+```javascript
+// React: @trtc/calls-uikit-react
+// Vue 3: @trtc/calls-uikit-vue
+// Vue 2.7: @trtc/calls-uikit-vue2
+// Vue 2.6: @trtc/calls-uikit-vue2.6  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+// 1. 初始化
+TUICallKitAPI.init({ SDKAppID, userID, userSig });
+
+// 2. 发起通话（单聊或多人）
+try {
+  await TUICallKitAPI.calls({
+    userIDList: ['jack', 'tom'],
+    type: CallMediaType.VIDEO_CALL
+  });
+} catch (error: any) {
+  console.error(`[TUICallKit] Failed to call. Reason:${error}`);
+}
+```
+
+`calls` parameter reference:
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| userIDList | Array\<String\> | Yes | List of users to call |
+| type | CallMediaType | Yes | Call media type (`AUDIO`/`VIDEO`) |
+| chatGroupID | String | No | Chat group ID |
+| roomID | Number | No | Numeric room ID, range [1, 2147483647] |
+| strRoomID | String | No | String room ID. Mutually exclusive with roomID; if both are provided, roomID takes priority |
+| timeout | Number | No | Call timeout in seconds, default 30s, range 10s–600s |
+| userData | String | No | Custom extension field; the callee can read it from `ON_CALL_RECEIVED` |
+| offlinePushInfo | Object | No | Custom offline push parameters |
+
+CallMediaType values:
+
+| CallMediaType | Description |
+|---|---|
+| `CallMediaType.AUDIO` | Voice call |
+| `CallMediaType.VIDEO` | Video call |
+
+## 5. Expected Results
+
+- After `TUICallKitAPI.calls` succeeds, the callee receives a call invitation.
+- Once the callee answers, the call is established and both parties can communicate via audio/video.
+- When the call times out or the callee rejects, the `catch` branch receives a clear error message.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Continuing to use `call` / `groupCall` in v4.x (deprecated; no error is thrown but functionality is incomplete).
+- Pitfall 2: Passing a single string via a `userID` field instead of `userIDList` (v4.x no longer supports single-string parameters).
+- Pitfall 3: Mixing `roomID` and `strRoomID` (they are mutually exclusive and not interchangeable).
+- Pitfall 4: Persistently using numeric literals (1/2) for `type` instead of `CallMediaType` enum constants.
+
+## 7. Problem Definition (retrieval hint)
+
+TUICallKit React/Vue v4.x users ask how to initiate audio/video calls and the difference between `calls` and the legacy `call`/`groupCall`, including migration steps.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to initiate a call with TUICallKit React/Vue?
+- What is the difference between `calls` and `call`?
+- How to pass the `userIDList` parameter in v4.x?
+- Can `CallMediaType` and numeric values 1/2 be mixed?
+- What should I watch out for when migrating from `TUICallKitServer.call` to `TUICallKitAPI.calls`?
+- What do `type` parameter values 1 and 2 represent in `call`?
+- What do `callMediaType` values 1 and 2 mean — voice or video?
+- What do TUICallKit call type numbers 1 and 2 mean?

package/resource/knowledge/callkit/best-practice/common/callengine-call-flow.md

@@ -0,0 +1,123 @@
+---
+title: "TUICallEngine Call Invitation Receiving and Initiating Flow（TUICallEngine 发起通话的流程）"
+product: call
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [TUICallEngine, ON_CALL_RECEIVED, calls, accept, reject, call invitation, call-engine-lite, userData, callMediaType]
+version_range: ">=4.0.0"
+---
+
+# TUICallEngine Call Invitation Receiving and Initiating Flow
+
+## 1. Key Takeaways
+
+- To receive call invitations, listen only to `TUICallEvent.ON_CALL_RECEIVED`. **Do not listen to the Chat SDK's `MESSAGE_RECEIVED` and parse call invitations manually.**
+- To initiate a call, use `TUICallEngine.calls()` with `userIDList` (array) and `type` (media type) in the parameters.
+- After receiving an invitation, call `accept()` to answer or `reject()` to decline. Extension data is passed via the `userData` string.
+- The Web and mini program APIs are identical; only the package name differs (Web: `@trtc/call-engine-lite-js`, Mini Program: `@trtc/call-engine-lite-wx`).
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `TUICallEvent.ON_CALL_RECEIVED` | Receive call invitation event | Triggered when the callee receives an incoming call; do not parse from Chat custom messages |
+| `calls({userIDList, type, ...})` | Initiate a call | Called by the caller; unified entry for one-on-one and group calls |
+| `accept()` | Answer the call | Called by the callee after receiving an invitation |
+| `reject()` | Reject the call | Called by the callee after receiving an invitation |
+| `userData` | Custom extension data | A string passed by the caller; the callee reads it from the `ON_CALL_RECEIVED` event |
+| `callMediaType` | Call media type | Carried in the `ON_CALL_RECEIVED` event: 1=voice, 2=video |
+| `inviteID` | Invitation ID | Identifies a single call invitation, used to correlate subsequent events |
+| `callId` | Call ID | Unique identifier for this call |
+| `callRole` | Role | Caller (`call`) / Callee (`called`) |
+
+### ON_CALL_RECEIVED Event Fields
+
+| Parameter | Type | Description |
+|---|---|---|
+| callerId | String | The inviter |
+| calleeIdList | Array\<String\> | Other users also invited |
+| isFromGroup | Boolean | Whether it is a group call |
+| inviteData | Object | Call data |
+| inviteID | String | Invitation ID |
+| userData | String | Extension field — custom data passed by the caller |
+| callId | String | Unique ID for this call |
+| roomID | Number | Audio/video room ID |
+| callMediaType | Number | Call media type (1=voice, 2=video) |
+| callRole | String | Role: caller / callee |
+
+### calls Parameter Reference
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| userIDList | Array\<String\> | Yes | List of users to call |
+| type | Number | Yes | 1=voice, 2=video (`CallMediaType`) |
+| userData | String | No | Custom extension data; the callee reads it from `ON_CALL_RECEIVED` |
+| timeout | Number | No | Timeout in seconds, default 30 |
+| roomID | Number | No | Numeric room ID, range [1, 2147483647] |
+| strRoomID | String | No | String room ID; mutually exclusive with roomID |
+| chatGroupID | String | No | Chat group ID; used for multi-party calls in a group chat |
+| offlinePushInfo | Object | No | Custom offline push parameters |
+
+## 3. Mechanism & Sequence
+
+Caller invokes `calls()` to send an invitation -> the SDK sends the invitation via the signaling channel -> callee triggers `ON_CALL_RECEIVED` -> callee calls `accept()` to answer or `reject()` to decline -> call is established / ended.
+
+Real-time state changes during the call are handled through TUICallEngine event listeners and do not rely on Chat messages.
+
+## 4. Standard Usage
+
+1. Create a `TUICallEngine` instance and log in.
+2. The caller calls `calls()` to initiate a call invitation.
+3. The callee listens for the `ON_CALL_RECEIVED` event and calls `accept()` or `reject()` upon receiving it.
+4. Extension data is passed as a `userData` string; the callee reads it from the event.
+
+```javascript
+// Web: @trtc/call-engine-lite-js
+// 小程序: @trtc/call-engine-lite-wx  （API 一致，仅包名不同）
+import { TUICallEngine, TUICallEvent } from '@trtc/call-engine-lite-js';
+
+// 创建实例并登录
+const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: xxx, tim: timInstance });
+await tuiCallEngine.login({ userID, userSig });
+
+// 主叫：发起通话邀请
+await tuiCallEngine.calls({
+  userIDList: ['user_bob'],
+  type: 2,                    // 1=语音 2=视频
+  userData: '{"ext":"info"}',
+  timeout: 30,
+});
+
+// 被叫：监听通话邀请
+tuiCallEngine.on(TUICallEvent.ON_CALL_RECEIVED, (event) => {
+  console.log('来电', event);
+  // 展示接听 UI，随后调用 accept() 或 reject()
+  tuiCallEngine.accept({ inviteID: event.inviteID, roomID: event.roomID });
+});
+```
+
+## 5. Expected Results
+
+- After the caller invokes `calls()`, the callee receives the `ON_CALL_RECEIVED` event.
+- After the callee calls `accept()`, the call is established; after `reject()`, the call is declined.
+- `userData` passed by the caller can be correctly read by the callee from the event.
+- Other events during the call (answer, hang up, timeout, etc.) are triggered normally through TUICallEngine's event mechanism.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Listening to `MESSAGE_RECEIVED` to manually parse call invitations (use `ON_CALL_RECEIVED` instead).
+- Pitfall 2: Using `businessID` / low-level payload formats or other SDK internal fields (no official public documentation exists; do not fabricate them).
+- Pitfall 3: Assuming a `customData` field exists (v4.x uses the `userData` string to pass custom data).
+
+## 7. Problem Definition (retrieval hint)
+
+TUICallEngine Web / mini program users need to understand how to receive call invitations, initiate calls, and pass custom extension data.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How does TUICallEngine receive call invitations?
+- How does TUICallEngine initiate a call?
+- What do the `ON_CALL_RECEIVED` fields mean?
+- How to fill in the `calls` API parameters?
+- How does TUICallEngine pass custom extension data?
+- Is the call invitation flow in mini program TUICallEngine the same as Web?

package/resource/knowledge/callkit/best-practice/common/callengine-log-level.md

@@ -0,0 +1,67 @@
+---
+title: "Set log Level for TUICallEngine（TUICallEngine / setLogLevel / 日志级别 / 控制台日志 / 关闭日志）"
+product: call
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [TUICallEngine, setLogLevel, log level, console log, disable log]
+version_range: ">=4.0.0"
+---
+
+# Setting the Log Output Level for TUICallEngine
+
+## 1. Key Takeaways
+
+- TUICallEngine provides the `setLogLevel` API to control the log output level. It can be called immediately after creating an instance.
+- During integration and debugging, set the level to 0 (verbose). After going live, set it to level 1 (default, key info) or higher.
+- To disable all logs, set the level to 4.
+
+## 2. Field / API Reference
+
+| Level | Value | Description |
+|---|---|---|
+| Verbose | 0 | High log volume; recommended during integration and debugging |
+| Key info | 1 | SDK outputs key information; **default log level** |
+| Warning | 2 | SDK outputs only warning and error level logs |
+| Error | 3 | SDK outputs only error level logs |
+| Silent | 4 | SDK prints no logs at all |
+
+## 3. Mechanism & Sequence
+
+Create a `TUICallEngine` instance -> call `setLogLevel` to set the log level -> the SDK outputs logs at the specified level going forward. A single call takes effect globally; no repeated calls are needed.
+
+## 4. Standard Usage
+
+1. Create an engine instance via `TUICallEngine.createInstance(options)`.
+2. Call `tuiCallEngine.setLogLevel(level)` to set the log level.
+3. Use level 0 during integration and debugging; adjust to level 1–4 as needed after going live.
+
+```javascript
+import TUICallEngine from '@trtc/call-engine-lite-js'; // Web
+// import TUICallEngine from '@trtc/call-engine-lite-wx'; // 小程序
+
+const tuiCallEngine = TUICallEngine.createInstance({ SDKAppID: 0 });
+tuiCallEngine.setLogLevel(0); // 接入调试：全量日志
+```
+
+## 5. Expected Results
+
+- After calling `setLogLevel`, console log volume matches the target level.
+- At level 4, the SDK produces no log output.
+- Takes effect immediately without restarting or reinitializing.
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Assuming `setLogLevel` can only be called after `init` (it can actually be called as soon as the instance is created).
+- Pitfall 2: Setting level 4 and still expecting to receive critical warnings (level 4 disables all logs).
+
+## 7. Problem Definition (retrieval hint)
+
+TUICallEngine users want to control SDK log output volume: view full logs during integration, reduce logs after going live, or disable log output entirely.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to disable TUICallEngine logs?
+- How to set the TUICallEngine log level?
+- What do the `setLogLevel` values mean?
+- How to view full TUICallEngine logs during integration?
+- Is the TUICallEngine log level the same on mini programs and Web?

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

@@ -0,0 +1,81 @@
+---
+title: "How to Get the TUICallEngine Instance from Web TUICallKit（TUICallKit 如何获取 TUICallengine 实例）"
+product: call
+frameworks: [react, vue, miniprogram, web]
+scope: platform_common
+tags: [TUICallKit, getTUICallEngineInstance, engine instance, underlying engine, WeChat native mini program, uniapp mini program]
+version_range: ">=4.0.0"
+---
+
+# How to Get the TUICallEngine Instance from Web TUICallKit
+
+## 1. Key Takeaways
+
+- Use `TUICallKitAPI.getTUICallEngineInstance()` to get the underlying TUICallEngine instance.
+- Once you have the engine instance, you can listen to call events (e.g., `ON_CALL_BEGIN`, `ON_CALL_RECEIVED`) via `.on()`.
+
+## 2. Field / API Reference
+
+| Field / API | Purpose | Notes |
+|---|---|---|
+| `TUICallKitAPI` | TUICallKit API entry | Imported from the corresponding platform package; provides `getTUICallEngineInstance()` |
+| `getTUICallEngineInstance()` | Get the TUICallEngine instance | Returns the engine instance for event listening and underlying API calls |
+| `TUICallEngine` | Engine instance | Obtained via this method; used to register event callbacks |
+
+## 3. Mechanism & Sequence
+
+TUICallKit initialization completes -> call `TUICallKitAPI.getTUICallEngineInstance()` to get the engine instance -> use the engine instance to register event listeners or call underlying APIs.
+
+Ensure TUICallKit initialization is complete before calling; otherwise it may return `undefined`.
+
+## 4. Standard Usage
+
+1. Import `TUICallKitAPI` from the corresponding platform package.
+2. Call `TUICallKitAPI.getTUICallEngineInstance()` to get the engine instance.
+3. Use the engine instance to register event listeners or call other underlying methods.
+
+```javascript
+// React: @trtc/calls-uikit-react
+// Vue 3: @trtc/calls-uikit-vue
+// Vue 2.7: @trtc/calls-uikit-vue2
+// Vue 2.6: @trtc/calls-uikit-vue2.6
+// uniapp 小程序: @trtc/calls-uikit-wx-uniapp
+// 微信原生小程序: @trtc/calls-uikit-wx  （API 一致，仅包名不同）
+import { TUICallKitAPI } from "@trtc/calls-uikit-react";
+
+const tuiCallEngine = TUICallKitAPI.getTUICallEngineInstance();
+
+if (tuiCallEngine) {
+  // 获取成功，可监听事件或调用底层 API
+  tuiCallEngine.on(TUICallEvent.ON_CALL_BEGIN, (event) => {
+    console.log('通话建立', event);
+  });
+} else {
+  console.warn('TUICallEngine 实例未就绪，请确认 TUICallKit 已完成初始化');
+}
+```
+
+## 5. Expected Results
+
+- `getTUICallEngineInstance()` returns a non-`undefined` engine instance that can be used normally.
+- Event callbacks registered via the engine instance trigger correctly.
+- Multiple calls return the same engine instance (singleton).
+
+## 6. Common Pitfalls
+
+- Pitfall 1: Calling `getTUICallEngineInstance()` before TUICallKit initialization completes (returns `undefined`).
+- Pitfall 2: Assuming each call to `getTUICallEngineInstance()` creates a new engine instance (it is a singleton; multiple calls return the same instance).
+- Pitfall 3: Directly creating an instance from the mini program engine package (use `TUICallKitAPI.getTUICallEngineInstance()` instead of creating one manually).
+
+## 7. Problem Definition (retrieval hint)
+
+TUICallKit users need to obtain the underlying TUICallEngine instance to listen to call events or invoke underlying APIs.
+
+## 8. Alternative Queries (retrieval recall)
+
+- How to get the TUICallEngine instance from TUICallKit?
+- How to use `getTUICallEngineInstance`?
+- How to get the TUICallEngine instance in TUICallKit Vue?
+- How to listen to underlying TUICallEngine events in TUICallKit React?
+- Can TUICallKit mini program get the TUICallEngine instance?
+- What can you do after getting the engine instance from TUICallKit?

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

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

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

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