@tencent-rtc/mcp 1.7.2 → 1.7.4

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

@@ -0,0 +1,362 @@
+## Overview
+
+The audio/video calling feature is implemented through `CallStore`, enabling real-time audio and video interaction between users. `CallStore` provides a comprehensive set of APIs to manage the entire call lifecycle. When integrating `CallStore`, be sure to understand the following runtime characteristics:
+- **Error Handling**: When actively calling APIs (such as `calls`), failures due to parameter validation or state conflicts are typically reported via asynchronous error events or error codes. Network or remote exceptions are also delivered through `onCallEnded` with the error reason.
+
+- **Threading Model & Cleanup**: All state updates (`CallState`) and event callbacks (`CallEvent` / `CallEventListener`) are typically **guaranteed to fire on the main thread**, making them safe for direct UI updates. Under the global singleton pattern, be sure to unregister listeners when components are destroyed (e.g., `deinit` / `onDestroy`) to avoid memory leaks.
+
+   > **Important:**
+   >
+   > After successful SDK initialization, obtain the `CallStore` instance through the **shared** singleton. Do not attempt to initialize it directly, or you will not receive call state updates.
+   >
+
+   > **Note:**
+   >
+   > Call state updates are delivered through the **state** publisher. Subscribe to it to receive real-time updates on call data.
+   >
+
+   > **Warning:**
+   >
+   > Ensure proper UI state handling after a call ends to avoid interface anomalies.
+   >
+
+## Features
+- **Initiate Audio/Video Calls**: Supports initiating audio or video calls to one or multiple users, with configurable timeout, custom data, and other parameters.
+
+- **Accept/Reject Calls**: When receiving an incoming call invitation, you can choose to accept or reject it.
+
+- **Hang Up Calls**: End the current ongoing audio/video call.
+
+- **Group Call Management**: Supports joining an existing group call or inviting other users to join during a call.
+
+- **Call Record Management**: Query recent call records (with pagination support) and delete specified call records.
+
+- **Event-Driven Architecture**: Provides event listeners for call started, invitation received, call ended, and more.
+
+- **State Subscription**: Subscribe to real-time call state including participant list, volume information, network quality, etc.
+
+## Subscribable Data
+
+**CallState** field descriptions:
+| **Property** | **Type** | **Description** |
+| --- | --- | --- |
+| activeCall | CallInfo | Current active call information.<br>**Lifecycle contract**: When `onCallEnded` fires, this object is not immediately cleared. It retains the call's final state for UI end-of-call animations (where `CallInfo.result` or other parameters reflect the end reason). It is automatically overwritten when a new call is initiated or received. Developers can manually clean up by resetting `CallStore`-related state. |
+| recentCalls | [CallInfo] | List of recent call records.<br>**Note:**<br>After each `queryRecentCalls` call, this state currently performs an **overwrite update** rather than automatic append. To implement infinite scrolling, the business layer must concatenate newly arrived data with the existing list. |
+| cursor | String | Pagination cursor for querying more call records. |
+| selfInfo | CallParticipantInfo | Current user's own information. |
+| allParticipants | [CallParticipantInfo] | List of all participants in the current call. |
+| speakerVolumes | [String: Int] | Participant volume information. Key is user ID, value is volume level. |
+| networkQualities | [String: NetworkQuality] | Participant network quality information. Key is user ID, value is network quality. |
+
+## API Reference
+
+| **Method** | **Description** |
+|---------|---------|
+| shared | Get the CallStore singleton instance. |
+| callEventPublisher | Call event publisher. |
+| calls | Initiate a call. |
+| accept | Accept a call. |
+| reject | Reject a call. |
+| hangup | Hang up a call. |
+| join | Join a group call. |
+| invite | Invite users to join a call. |
+| queryRecentCalls | Query recent call records. |
+| deleteRecentCalls | Delete call records. |
+
+### Get Instance
+
+#### shared
+
+Get the CallStore singleton instance.
+
+### Observe State and Events
+
+#### callEventPublisher
+
+Call event publisher.
+
+### Call Operations
+
+#### calls
+
+Initiate an audio or video call to specified users. Supports both one-to-one and group calls.
+``` ets
+calls(
+  participantIds: string[],
+  mediaType: CallMediaType,
+  params: CallParams | undefined,
+): Promise<void> {
+  return this.impl.calls(participantIds, mediaType, params)
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+**Parameters**
+
+| **Parameter** | **Type** | **Description** |
+|---------|---------|---------|
+| participantIds | [String] | List of callee IDs. Supports one or multiple users. |
+| mediaType | CallMediaType | Call media type (audio/video). |
+| params | CallParams? | Call parameter configuration. |
+
+#### accept
+
+Accept a call. Call this method to accept when receiving an incoming call invitation.
+``` ets
+accept(): Promise<void> {
+  return this.impl.accept()
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+#### reject
+
+Reject a call. Call this method to reject when receiving an incoming call invitation.
+``` ets
+reject(): Promise<void> {
+  return this.impl.reject()
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+#### hangup
+
+Hang up and end the current ongoing call.
+``` ets
+hangup(): Promise<void> {
+  return this.impl.hangup()
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+#### join
+
+Join an ongoing group call using a specific Call ID.
+``` ets
+join(callId: string): Promise<void> {
+  return this.impl.join(callId)
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+**Parameters**
+
+| **Parameter** | **Type** | **Description** |
+|---------|---------|---------|
+| callId | String | The call ID to join. |
+
+#### invite
+
+Invite other users to join during an ongoing call.
+``` ets
+invite(
+  participantIds: string[],
+  params: CallParams | undefined,
+): Promise<void> {
+  return this.impl.invite(participantIds, params)
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+**Parameters**
+
+| **Parameter** | **Type** | **Description** |
+|---------|---------|---------|
+| participantIds | [String] | List of invitee IDs. |
+| params | CallParams? | Call parameter configuration. |
+
+### Call Records
+
+#### queryRecentCalls
+
+Query recent call records.
+**Current limitation**: Query results currently **overwrite (reset)** the `state.recentCalls` list rather than automatically appending.
+``` ets
+queryRecentCalls(cursor: string, count: number): Promise<void> {
+  return this.impl.queryRecentCalls(cursor, count)
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+**Parameters**
+
+| **Parameter** | **Type** | **Description** |
+|---------|---------|---------|
+| cursor | String | Pagination cursor. Pass an empty string for the first query. |
+| count | UInt | Number of records to query. |
+
+#### deleteRecentCalls
+
+Delete specified call records.
+``` ets
+deleteRecentCalls(callIdList: string[]): Promise<void> {
+  return this.impl.deleteRecentCalls(callIdList)
+}
+```
+
+**Version Info**
+
+Supported since version 3.5.
+
+**Parameters**
+
+| **Parameter** | **Type** | **Description** |
+|---------|---------|---------|
+| callIdList | [String] | List of call IDs to delete. |
+
+## Data Structures
+
+### CallMediaType
+
+Call media type, used to specify whether to initiate an audio or video call.
+
+| **Enum Value** | **Value** | **Description** |
+|---------|---------|---------|
+| audio | 1 | Audio call. |
+| video | 2 | Video call. |
+
+### CallEndReason
+
+Call end reason, used to identify how the audio/video call ended (normal hangup, rejection, timeout, etc.).
+
+| **Enum Value** | **Value** | **Description** |
+|---------|---------|---------|
+| unknown | 0 | Unknown reason. |
+| hangup | 1 | Normal hangup. |
+| reject | 2 | Call rejected. |
+| noResponse | 3 | No response. |
+| offline | 4 | Remote party offline. |
+| lineBusy | 5 | Remote party busy. |
+| canceled | 6 | Call cancelled. |
+| otherDeviceAccepted | 7 | Accepted on another device. |
+| otherDeviceReject | 8 | Rejected on another device. |
+| endByServer | 9 | Call ended by server. |
+
+### CallDirection
+
+Call direction, used to identify whether the call is incoming, outgoing, or missed.
+
+| **Enum Value** | **Value** | **Description** |
+|---------|---------|---------|
+| unknown | 0 | Unknown. |
+| missed | 1 | Missed call. |
+| incoming | 2 | Incoming call. |
+| outgoing | 3 | Outgoing call. |
+
+### CallParticipantStatus
+
+Call participant status, used to identify whether a participant is waiting or has accepted.
+
+| **Enum Value** | **Value** | **Description** |
+|---------|---------|---------|
+| none | 0 | No status (not in a call). |
+| waiting | 1 | Waiting (calling/being called). |
+| accept | 2 | Accepted. |
+
+### CloudRecordPolicy
+
+Cloud recording policy for audio/video calls, used to configure whether cloud recording is enabled for a specific call.
+
+| **Enum Value** | **Value** | **Description** |
+|---------|---------|---------|
+| followConsoleConfig | 0 | Follow the console's global configuration (default). |
+| enable | 1 | Enable cloud recording, overriding the console configuration. |
+| disable | 2 | Disable cloud recording, overriding the console configuration. |
+
+### CallEventListener
+
+Call events, used to receive various event notifications during a call.
+
+**Methods**
+
+| **Method** | **Description** |
+|---------|---------|
+| onCallStarted | Callback when the call starts.<br>Timing note: This indicates "the call flow has been successfully entered (e.g., `calls` was initiated and internally accepted)", but **does not mean the audio/video room has been connected or established**. It is recommended to use this only for initial UI navigation (caller side). |
+| onCallReceived | Callback when a new call invitation is received.<br>Field recommendation: Event parameters only pass through `callId`, `mediaType`, and `userData`. To read the full information such as inviter, room ID, or associated group ID, read from `state.activeCall` after receiving this event. |
+| onCallEnded | Unified call end event callback.<br>Scenario note: Whether the call ends after connection, times out without answer, is cancelled by the remote party, or is accepted on another device, this event is ultimately triggered. Developers must use the `reason` parameter to determine the specific cause and display the corresponding UI text or handle branching logic.<br>Getting call duration: This event's parameters do not include a duration field. To get call duration, read `state.activeCall.duration` (in seconds) when receiving this callback. After the call is connected, the SDK internally increments this value every second; `activeCall` is not immediately cleared when the call ends, so it can be safely read in this callback. |
+| onSuggestSwitchToCellular | Callback triggered when the system detects poor WiFi quality and suggests switching to cellular network. |
+
+### CallParams
+
+Call parameter configuration, used to set room ID, timeout, custom data, and other parameters when initiating audio/video calls.
+| **Property** | **Type** | **Description** |
+| --- | --- | --- |
+| roomId | String | TRTC room ID (CallStore's media stream management uses Tencent Cloud TRTC service). Optional.<br>When not provided, automatically generated by the server. If the business needs to specify or reuse a TRTC room, pass a specific string. |
+| timeout | Int | Ring timeout in seconds. Optional.<br>Only controls the unanswered timeout phase from call initiation (`calls`) to acceptance. Does not apply to connected calls or `invite` operations.<br>When set to 0, the server default (30s) is used. |
+| userData | String | Custom pass-through data attached to the call. Optional.<br>This data is primarily exposed to the business side through the callee's `onCallReceived` event.<br>**Note:**<br>It does not persist in the long-term `CallInfo` state nor is it saved to call records. It is recommended to pass a short JSON string. |
+| chatGroupId | String | Tencent Cloud IM group ID. Optional.<br>Only required in "call initiated from a group chat" scenarios. When provided, the system routes signaling and associates this call with the group's call records, enabling call start/end status messages in the group chat and inviting group members to join during the call.<br>For one-to-one calls or ad-hoc multi-party calls not bound to a fixed group, leave this empty.<br>**Note:**<br>This field takes effect on the initial `calls`. Subsequent `invite` calls cannot change the group binding for this call. |
+| isEphemeralCall | Bool | Ephemeral call (no call record). Optional.<br>When set to `true`, no call message is generated after this call ends. Common scenario: initiating a call in a 1v1 chat without wanting to display a call message. |
+| cloudRecordPolicy | CloudRecordPolicy | Cloud recording policy for this call. Requires the relevant capability to be activated in the console.<br>- followConsoleConfig (default): Follow the console's global configuration.<br>- enable: Force enable cloud recording, overriding the console's global configuration.<br>- disable: Force disable cloud recording, overriding the console's global configuration. |
+| offlinePushTitle | string | Offline push notification title.<br>When non-empty, overrides the default title (logged-in user's nickname). |
+| offlinePushDescription | string | Offline push notification description.<br>When non-empty, overrides the default description. |
+
+### CallParticipantInfo
+
+Call participant information, including user ID, nickname, avatar, participation status, microphone/camera on/off status, etc.
+
+| **Property** | **Type** | **Description** |
+|---------|---------|---------|
+| id | String | User ID. |
+| name | String | User nickname. |
+| avatarURL | String | User avatar URL. |
+| remark | String | Friend remark. |
+| status | CallParticipantStatus | Participant status. |
+| isMicrophoneOpened | Bool | Whether the microphone is on. |
+| isCameraOpened | Bool | Whether the camera is on. |
+
+### CallInfo
+
+Call information, including call ID, room ID, initiator, invitees, media type, call direction, start time, duration, and other complete details.
+| **Property** | **Type** | **Description** |
+| --- | --- | --- |
+| callId | String | Call ID. |
+| roomId | String | Room ID. |
+| inviterId | String | Initiator ID. |
+| inviteeIds | [String] | List of invitee IDs. |
+| chatGroupId | String | Chat group ID. |
+| mediaType | CallMediaType? | Call media type.<br>**Note:**<br>May be null during early event phases, for unknown types, or when historical call records (recent calls) have not fully populated this field. Business code should handle optional unwrapping. |
+| result | CallDirection | Call direction/record type (e.g., incoming, outgoing, missed).<br>**Note:**<br>This does not represent the specific reason for call termination. |
+| startTime | TimeInterval | Timestamp when the call was actually connected (unit: milliseconds). |
+| duration | TimeInterval | Call duration (seconds). |
+
+### CallState
+
+Call state data, managing the real-time data state of the current call.
+| **Property** | **Type** | **Description** |
+| --- | --- | --- |
+| activeCall | CallInfo | Current active call information.<br>**Lifecycle contract**: When `onCallEnded` fires, this object is not immediately cleared. It retains the call's final state for UI end-of-call animations (where `CallInfo.result` or other parameters reflect the end reason). It is automatically overwritten when a new call is initiated or received. Developers can manually clean up by resetting `CallStore`-related state. |
+| recentCalls | [CallInfo] | List of recent call records.<br>**Note:**<br>After each `queryRecentCalls` call, this state currently performs an **overwrite update** rather than automatic append. To implement infinite scrolling, the business layer must concatenate newly arrived data with the existing list. |
+| cursor | String | Pagination cursor for querying more call records. |
+| selfInfo | CallParticipantInfo | Current user's own information. |
+| allParticipants | [CallParticipantInfo] | List of all participants in the current call. |
+| speakerVolumes | [String: Int] | Participant volume information. Key is user ID, value is volume level. |
+| networkQualities | [String: NetworkQuality] | Participant network quality information. Key is user ID, value is network quality. |
+
+## Usage Example
+``` ets
+import AtomicXCore
+// Initiate a video call
+CallStore.shared.calls(participantIds: ["mike"], mediaType: .video, params: nil) { code, message in
+}
+```

package/resource/knowledge/callkit/preset/harmonyos/integration.md

@@ -0,0 +1,318 @@
+This guide walks you through quickly integrating the TUICallKit component. You can complete the following key steps in 10 minutes and get a fully functional audio/video calling interface.
+
+## Prerequisites
+
+### **Environment Requirements**
+- IDE: DevEco Studio 6.0.0.858 or later.
+
+- Device OS: HarmonyOS 5.0.5 or later.
+
+- API Version: 17 or later.
+
+### **Activate the Service**
+
+Before using Tencent Cloud audio/video services, you need to go to the console to activate the service for your application. For detailed steps, see Activate Service. After activation, note down the `SDKAppID` and `SDKSecretKey` — you will need them in the subsequent login step.
+
+## Quick Integration
+
+### Step 1: Import the Component
+
+2. In your project's `entry/oh-package.json5` file, add the following plugin dependencies:
+
+   ``` json
+   "dependencies": {
+       "@tencentcloud/atomicxcore": "^4.2.0",
+       "@tencentcloud/tuicallkit": "file:../../../call",
+   }
+   ```
+
+   > **Note:**
+   >
+   > The `call` directory can be placed anywhere, as long as the relative path is correctly set in oh-package.json5.
+   >
+
+3. After modifying **oh-package.json5**, run the following command to install the local TUIKit component:
+
+   ``` bash
+   ohpm install
+   ```
+
+   `ohpm install` will automatically install the required dependencies.
+
+   > **Warning:**
+   >
+   > - When using local integration, to upgrade you need to get the latest component code from GitHub and overwrite your local project's call directory.
+   > - When private modifications conflict with remote changes, you need to manually merge and resolve conflicts.
+
+### Step 2: Project Configuration
+1. Permission configuration: In your project's `entry/module.json5` module section, declare the following required permissions:
+
+   ``` json
+   "requestPermissions":[
+     {
+       "name" : "ohos.permission.INTERNET"
+     },
+     {
+       "name" : "ohos.permission.USE_BLUETOOTH"
+     },
+     {
+       "name" : "ohos.permission.GET_BUNDLE_INFO"
+     },
+     {
+       "name" : "ohos.permission.GET_NETWORK_INFO"
+     },
+     {
+       "name" : "ohos.permission.GET_WIFI_INFO"
+     },
+     {
+       "name" : "ohos.permission.MODIFY_AUDIO_SETTINGS"
+     },
+     {
+       "name" : "ohos.permission.MICROPHONE",
+       "reason": "$string:module_desc",
+       "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
+     },
+     {
+       "name" : "ohos.permission.CAMERA",
+       "reason": "$string:module_desc",
+       "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
+     },
+     {
+       "name" : "ohos.permission.KEEP_BACKGROUND_RUNNING"
+     },
+   ]
+   ```
+2. Module declaration: After integrating the source code into your existing project, declare the module in the `build-profile.json5` file:
+
+   ``` bash
+    "modules": [
+       {
+         "name": "entry",
+         "srcPath": "./entry",
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       },
+       {
+         "name": "tuicallkit",
+         "srcPath": "../call",  // Adjust based on actual directory
+         "targets": [
+           {
+             "name": "default",
+             "applyToProducts": [
+               "default"
+             ]
+           }
+         ]
+       }
+     ]
+   ```
+3. Bind **TUICallKit** to your application's main window (WindowStage), enabling the entire app to accept incoming calls and initiate calls globally after startup, without repeated initialization in business pages.
+
+   ``` typescript
+   // Your project's EntryAbility.ets
+   import { UIAbility } from '@kit.AbilityKit';
+   import { window } from '@kit.ArkUI';
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   export default class EntryAbility extends UIAbility {
+     async onWindowStageCreate(windowStage: window.WindowStage): Promise<void> {
+       windowStage.loadContent('pages/Index');
+       // Hand the call UI hosting window to TUICallKit for management, establishing incoming call listeners
+       TUICallKit.createInstance(this.context).attach(windowStage);
+     }
+
+     onWindowStageDestroy(): void {
+       // Unbind the window and release resources
+       TUICallKit.createInstance(this.context).detach();
+     }
+   }
+   ```
+4. Declare backgroundModes. Under the UIAbility hosting the call interface (typically EntryAbility), add backgroundModes to the abilities node in module.json5:
+
+   ``` java
+   "abilities": [
+     {
+       "name": "EntryAbility",
+       // ... other configurations remain unchanged
+       "backgroundModes": [
+         "audioRecording",
+         "audioPlayback"
+       ]
+     }
+   ]
+   ```
+
+### Step 3: Login
+
+After code integration, you need to complete the login process. This is a **critical step for using TUICallKit**. TUICallKit features are only available after a successful login, so please carefully verify that the relevant parameters are correctly configured:
+
+> **Note:**
+> In the sample code, the login API is called directly. However, in real projects, it is **strongly recommended to call TUICallKit's login service after completing your own user authentication flow**. This avoids business logic confusion or data inconsistencies caused by premature login calls, and better adapts to your project's existing user management and permission control system.
+>
+
+[ArkTS]
+``` typescript
+import { LoginStore } from '@tencentcloud/atomicxcore'
+
+try {
+  await LoginStore.shared().login(
+    1400000000,     // Replace with your SDKAPPID
+    'userID',       // Replace with your UserID
+    'userSig',      // Replace with your UserSig
+  );
+  // login success
+} catch (error) {
+  // login error
+}
+```
+
+**Login API parameter reference:**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `sdkAppID` | `number` | Obtained from the [console](https://console.cloud.tencent.com/trtc). Usually a 10-digit number starting with `140` or `160`. |
+| `userID` | `string` | Unique ID of the current user. Only contains letters, numbers, hyphens, and underscores. To avoid multi-device login conflicts, **do not use** simple IDs like `1` or `123`. |
+| `userSig` | `string` | Authentication ticket for Tencent Cloud. For more information, see How to Calculate and Use UserSig.<br>**Note:**<br>- Development: You can use the local [GenerateTestUserSig.genTestSig](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/application/entry/src/main/ets/debug/GenerateTestUserSig.ts) function or the [UserSig Tool](https://console.cloud.tencent.com/im/tool-usersig) to generate a temporary userSig.<br>- Production: To prevent key leakage, always generate userSig on the server side. See Server-side UserSig Generation for details. |
+
+### Step 4: Set Nickname and Avatar [Optional]
+
+First-time users have no avatar or nickname. Use the `setSelfInfo` API from `LoginStore` to set personal information:
+``` typescript
+import { LoginStore, UserProfile, ErrorInfo } from '@tencentcloud/atomicxcore';
+
+try {
+  await LoginStore.shared().setSelfInfo(new UserProfile('userID', 'userName', 'avatarURL'));
+  console.info("setSelfInfo success");
+} catch (error) {
+  const err = error as ErrorInfo;
+  console.error(`setSelfInfo failed [code: ${err.code}] ${err.message}`);
+}
+```
+
+**setSelfInfo API parameter reference:**
+| Parameter/Return | Type | Description |
+| --- | --- | --- |
+| `userProfile` | `UserProfile` | Core user profile model containing:<br>- userID: The user ID to set information for.<br>- nickname: Nickname.<br>- avatarURL: Avatar URL. |
+
+### Step 5: Initiate a Call
+
+The caller can initiate a voice or video call by calling the `calls` function and specifying the call type and callee's userID. The `calls` API supports both one-to-one and group calls. When userIDList contains one userID, it is a one-to-one call; when it contains multiple userIDs, it is a group call.
+``` typescript
+import { TUICallKit, CallMediaType } from '@tencentcloud/tuicallkit';
+import { ErrorInfo } from '@tencentcloud/atomicxcore';
+
+try {
+  await TUICallKit.createInstance(getContext(this)).calls(['mike'], CallMediaType.audio);
+  // Success handling
+} catch (error) {
+  const err = error as ErrorInfo;
+  // Failure handling
+}
+```
+
+| Parameter | Type | Description |
+|---------|---------|---------|
+| userIdList | string[] | List of target user IDs. |
+| mediaType | CallMediaType | Call media type, e.g., video call or voice call. |
+| params? | CallParams | Call extension parameters, e.g., room ID, call invitation timeout, etc. |
+
+### Step 6: Accept a Call
+
+After the callee completes login, when the caller initiates a call, the callee receives a call invitation accompanied by a ringtone and vibration.
+
+## More Features
+
+### Enable Incoming Call Banner
+
+You can call the `enableIncomingBanner` API to enable/disable the incoming call banner display. This feature is disabled by default (`false`). When the callee receives a call, a full-screen call waiting UI is shown by default. When enabled, a banner notification is shown first, then switches to the full-screen call UI as needed.
+
+``` typescript
+import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+TUICallKit.createInstance(context).enableIncomingBanner(true);
+```
+
+**Details:** Default is `false`. After the callee receives an invitation, a full-screen call waiting UI is shown by default. When enabled, a banner is shown first, then the full-screen call UI is launched as needed.
+
+### Group Calls
+
+When the caller uses the `calls` method to initiate a call with more than one user in the callee list, it is automatically treated as a group call. Other members can join via the `join` method.
+- **Initiate a group call:** When using `calls` with more than one user in the `userIdList`, it is automatically treated as a group call.
+
+   ``` typescript
+   import { TUICallKit, CallMediaType } from '@tencentcloud/tuicallkit';
+   import { ErrorInfo } from '@tencentcloud/atomicxcore';
+
+   try {
+     await TUICallKit.createInstance(getContext(this)).calls(['mike','tate'], CallMediaType.audio);
+     // Success handling
+   } catch (error) {
+     const err = error as ErrorInfo;
+     // Failure handling
+   }
+   ```
+- **Join a group call:** Use the `join` method to join a specified group call.
+
+   ``` typescript
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   await TUICallKit.createInstance(context).join('your_call_id');
+   ```
+   | Parameter | Type | Description |
+   |---------|---------|---------|
+   | callId | string | Unique identifier of this call. |
+
+### Ringtone Settings
+
+You can set the default ringtone, mute mode for incoming calls, and offline push ringtone:
+- **Set default ringtone (Method 1):** If you integrated TUICallKit via source code dependency, you can replace the ringtone resource files ([dialing tone](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/call/src/main/resources/rawfile/phone_dialing.m4a), [ringing tone](https://github.com/Tencent-RTC/TUIKit_Harmony/blob/main/call/src/main/resources/rawfile/phone_ringing.mp3)) to set custom default ringtones.
+
+- **Set default ringtone (Method 2):** Use the `setCallingBell` API to set the incoming call ringtone for the callee.
+
+   ``` typescript
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   TUICallKit.createInstance(context).setCallingBell('***/callingBell.mp3');
+   ```
+
+   **Details:** Only local file paths are accepted. Ensure the file directory is accessible by the application. The ringtone setting is bound to the device — it persists even when switching users. To restore the default ringtone, pass an empty filePath.
+
+   | Parameter | Type | Description |
+   |---------|---------|---------|
+   | filePath | string | Path to the ringtone file. |
+
+- **Mute mode for incoming calls:** Use the `enableMuteMode` API to enable mute mode.
+
+   ``` typescript
+   import { TUICallKit } from '@tencentcloud/tuicallkit';
+
+   TUICallKit.createInstance(context).enableMuteMode(true);
+   ```
+
+   **Details:** When enabled, no ringtone is played when receiving a call request.
+
+## Customize Your UI
+
+### Replace Icon Buttons
+
+You can directly replace the icons in the [src/main/resources/base/media](https://github.com/Tencent-RTC/TUIKit_Harmony/tree/main/call/src/main/resources/base/media) folder to ensure consistent icon styles throughout your app. Below are the basic function buttons — replace the corresponding icons to match your business scenario.
+
+Common icon file list:
+| Icon | Filename | Description |
+| --- | --- | --- |
+|  | icon_dialing.png | Accept call icon |
+|  | icon_hangup.png | Hang up call icon |
+|  | icon_mute_on.png | Mute microphone icon |
+|  | icon_handsfree.png | Disable speaker icon |
+|  | icon_camera_off.png | Disable camera icon |
+
+## FAQ
+
+### Is there a sample oh-package.json5 configuration for reference?
+
+You can refer to the `oh-package.json5` sample file in the GitHub TUIKit_Harmony [application](https://github.com/Tencent-RTC/TUIKit_Harmony/tree/main/application) project.