Starter Deal! First 3 month from only  $9.9 /month!
Starter Deal! First 3 month from only  $9.9 /month!
Grab It Now 
Call
Overview
  • Web
    • Run Sample Demo
    • Integration
      • Web&H5 (React)
      • Web&H5 (Vue3)
    • AI Denoising
    • Virtual Background
    • UI Customization
    • On-Cloud Recording
    • More Features
      • Configuring Nicknames and Avatars
      • Configure Resolution and Fill Mode
      • Group Call
      • Floating Window
      • Custom Ringtone
      • Monitoring Call Status
    • API Documentation
      • API Overview
      • TUICallKit
      • TUICallEngine
      • TUICallEvent
    • Server APIs
      • Call Status Callback
        • Call Status Callback
        • Call Event Callback
        • Callback Configuration
          • API List for Callback Configuration
          • Establishing Callback Configuration
          • Retrieving Callback Configuration
          • Update Callback Configuration
          • Remove Callback Configuration
      • REST API
        • Introduction to REST API
        • Retrieve records via callId
        • Retrieve Records Based on Conditions
    • Release Notes
  • Android
    • Run Sample Demo
    • Integration
    • AI Denoising
    • Virtual Background
    • UI Customization
    • Offline Call Push
    • On-Cloud Recording
    • More Features
      • Configuring Nicknames and Avatars
      • Group Call
      • Floating Window
      • Custom Ringtone
      • Monitoring Call Status
    • API Documentation
      • API Overview
      • TUICallKit
      • TUICallEngine
      • TUICallObserver
      • Type Definition
    • Server APIs
      • Call Status Callback
        • Call Status Callback
        • Call Event Callback
        • Callback Configuration
          • API List for Callback Configuration
          • Establishing Callback Configuration
          • Retrieving Callback Configuration
          • Update Callback Configuration
          • Remove Callback Configuration
      • REST API
        • Introduction to REST API
        • Retrieve records via callId
        • Retrieve Records Based on Conditions
    • Release Notes
  • iOS
    • Run Sample Demo
    • Integration
    • AI Denoising
    • Virtual Background
    • UI Customization
    • Offline Call Push
      • VoIP
      • APNs
    • On-Cloud Recording
    • More Features
      • Configuring Nicknames and Avatars
      • Group Call
      • Floating Window
      • Custom Ringtone
      • Monitoring Call Status
    • API Documentation
      • API Overview
      • TUICallKit
      • TUICallEngine
      • TUICallObserver
      • Type Definition
    • Server APIs
      • Call Status Callback
        • Call Status Callback
        • Call Event Callback
        • Callback Configuration
          • API List for Callback Configuration
          • Establishing Callback Configuration
          • Retrieving Callback Configuration
          • Update Callback Configuration
          • Remove Callback Configuration
      • REST API
        • Introduction to REST API
        • Retrieve records via callId
        • Retrieve Records Based on Conditions
    • Release Notes
  • Flutter
    • Run Sample Demo
    • Integration
    • Offline Call Push
    • AI Denoising
    • Virtual Background
    • UI Customization
    • offline Call Push
      • Notification
      • VoIP (Optional)
    • On-Cloud Recording
    • More Features
      • Configuring Nicknames and Avatars
      • Group Call
      • Floating Window
      • Beauty Effects
      • Custom Ringtone
      • Monitoring Call Status
    • API Documentation
      • API Overview
      • TUICallKit
      • TUICallEngine
      • TUICallObserver
      • Type Definition
    • Server APIs
      • Call Status Callback
        • Call Status Callback
        • Call Event Callback
        • Callback Configuration
          • API List for Callback Configuration
          • Establishing Callback Configuration
          • Retrieving Callback Configuration
          • Update Callback Configuration
          • Remove Callback Configuration
      • REST API
        • Introduction to REST API
        • Retrieve records via callId
        • Retrieve Records Based on Conditions
    • Upgrading
    • Release Notes
  • Overview
    • Overview
  • Activate the Service
  • Pricing
    • Call Monthly Packages
    • Pay-As-You-Go
    • Free Minutes
  • ErrorCode
  • FAQs
    • All Platform
    • Web
    • Flutter
    • iOS
    • Android
Call

TUICallKit

API Introduction

The TUICallKit API is the audio and video call component that includes a UI interface. With the TUICallKit API, you can swiftly develop audio and video call scenarios reminiscent of WeChat through simple interfaces. For further comprehensive steps to access this, please refer to: Integrating TUICallKit.

API Overview

TUICallKit is the audio and video call component with a UI, which enables you to swiftly create scenarios akin to WeChat for voice and video calls.
<TUICallKit/>: The core UI call component.
TUICallKitServer is the call instance, offering the following API interfaces.
API
Description
init
Initialize TUICallKit.
call
Makes a one-to-one call, Support for custom room ID, call timeout, offline push content, etc
groupCall
Makes a group call, Support for custom room ID, call timeout, offline push content, etc
Join a group call.
Customize user's ringtone.
Set your own nickname and avatar.
Turn on/off ringtone
Turn on/off the floating window function
Turn on/off the blurred background function button. v3.2.4+ support
Set the call language for the TUICallKit component
destroyed
Destroy TUICallKit

Introduction to <TUICallKit/> attributes

Attribute Overview

Attribute
Description
Type
Required
Default Value
Vue is supported
React is supported
allowedMinimized
Is the floating window permitted?
boolean
No
false
allowedFullScreen
Whether to permit full screen mode for the call interface
boolean
No
true
Display mode for the call interface
VideoDisplayMode
No
VideoDisplayMode.COVER
Call Resolution
VideoResolution
No
VideoResolution.RESOLUTION_480P
beforeCalling
This function will be executed prior to making a call and before receiving an invitation to talk
function(type, error)
No
-
afterCalling
This function will be executed after the termination of the call
function()
No
-

onMinimized

This function will be executed when the component switches to a minimized state. The explanation for the STATUS value is
function(oldStatus, newStatus)
No
-
×

kickedOut

The events thrown by the component occur when the current logged-in user is ejected. The call will also automatically terminate
function()
No
-
×

statusChanged

Event thrown by the component; this event is triggered when the call status changes. For detailed types of call status, refer to STATUS value description
function({oldStatus, newStatus})
No
-
×

Sample code

React
Vue
import { TUICallKit, VideoDisplayMode, VideoResolution } from "@tencentcloud/call-uikit-react";

<TUICallKit
videoDisplayMode={VideoDisplayMode.CONTAIN}
videoResolution={VideoResolution.RESOLUTION_1080P}
beforeCalling={handleBeforeCalling}
afterCalling={handleAfterCalling}
/>

function handleBeforeCalling(type: string, error: any) {
console.log("[TUICallkit Demo] handleBeforeCalling:", type, error);
}
function handleAfterCalling() {
console.log("[TUICallkit Demo] handleAfterCalling");
}
<template>
<TUICallKit
:allowedMinimized="true"
:allowedFullScreen="true"
:videoDisplayMode="VideoDisplayMode.CONTAIN"
:videoResolution="VideoResolution.RESOLUTION_1080P"
:beforeCalling="beforeCalling"
:afterCalling="afterCalling"
:onMinimized="onMinimized"
:kickedOut="handleKickedOut"
:statusChanged="handleStatusChanged"
/>
</template>
<script lang="ts" setup>
import { TUICallKit, TUICallKitServer, VideoDisplayMode, VideoResolution, STATUS } from "@tencentcloud/call-uikit-vue";

function beforeCalling(type: string, error: any) {
console.log("[TUICallkit Demo] beforeCalling:", type, error);
}
function afterCalling() {
console.log("[TUICallkit Demo] afterCalling");
}
function onMinimized(oldStatus: string, newStatus: string) {
console.log("[TUICallkit Demo] onMinimized: " + oldStatus + " -> " + newStatus);
}
function kickedOut() {
console.log("[TUICallkit Demo] kickedOut");
}
function statusChanged(args: { oldStatus: string; newStatus: string; }) {
const { oldStatus, newStatus } = args;
if (newStatus === STATUS.CALLING_C2C_VIDEO) {
console.log(`[TUICallkit Demo] statusChanged: ${oldStatus} -> ${newStatus}`);
}
}
</script>

Detailed information on TUICallKitServer API

import { TUICallKitServer } from "@tencentcloud/call-uikit-react";
// Replace it with the call-uikit npm package you are currently using

init

Initialize TUICallKit.
Note:
Init initialization needs to be completed before functions such as call and groupCall can be used.
try {
await TUICallKitServer.init({ SDKAppID, userID, userSig });
// If you already have a tim instance in your project, you need to pass it in here
// await TUICallKitServer.init({ tim, SDKAppID, userID, userSig});
console.log("[TUICallKit] Initialization succeeds.");
} catch (error: any) {
console.error(`[TUICallKit] Initialization failed. Reason: ${error}`);
}
The parameters are described below:
Parameter
Type
Required
Meaning
SDKAppID
Number
Yes
The SDKAppID of your app, you can find your SDKAppID in the Live Audio and Video console. For details, see Activating Services
userID
String
Yes
The current user's ID is of string type, only allowing for the inclusion of English letters (a-z and A-Z), digits (0-9), hyphens (-) and underscores (_)
userSig
String
Yes
Use SDKSecretKey to encrypt SDKAppID, UserID and other information to obtain userSig.
It is an authentication ticket used by Tencent Cloud to identify whether the current user can use TRTC services. For how to obtain it, please refer to How to Calculate UserSig
tim
TencentCloudChat
No
tim is an instance of TencentCloudChat SDK.

call

Makes a one-to-one call, Support for custom room ID, call timeout, offline push content, etc.
import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-react';
try {
await TUICallKitServer.call({
userID: 'mike',
type: TUICallType.VIDEO_CALL,
});
} catch (error: any) {
console.error(`[TUICallKit] Call failed. Reason: ${error}`);
}
The parameters are described below:
Parameter
Type
Required
Meaning
userID
String
Yes
The username of the called user
type
Yes
The media type of the call, see TUICallType call type for parameter value specifications
roomID
Number
No
Numerical Room ID, range [1, 2147483647]
timeout
Number
No
Call timeout, default: 30s, unit: seconds. timeout = 0, set to no timeout
userData
String
No
Customize the extended fields when initiating a call. The called user has this parameter in the ON_CALL_RECEIVED event.
Object
No
Customize offline message push parameters

groupCall

Makes a group call, Support for custom room ID, call timeout, offline push content, etc.
import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-react';
try {
await TUICallKitServer.groupCall({
userIDList: ['jack', 'tom'],
groupID: "xxx",
type: TUICallType.VIDEO_CALL
});
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
}
The parameters are described below:
Parameter
Type
Required
Meaning
userIDList
Array<String>
Yes
List of called users
type
Yes
The type of media for the call, you can refer to TUICallType for the explanation of parameter values
groupID
String
Yes
Call group ID, the creation of groupID can be referred to chat-createGroup API
roomID
Number
No
Numerical Room ID, range [1, 2147483647]
timeout
Number
No
Call timeout, default: 30s, unit: seconds. timeout = 0, set to no timeout
userData
String
No
Customize the extended fields when initiating a call. The called user has this parameter in the ON_CALL_RECEIVED event.
Object
No
Customize offline message push parameters

setLanguage

Set language, currently supports: Chinese, English, Japanese.
TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn" | "ja_JP"
The parameters are described below:
Parameter
Type
Required
Meaning
lang
String
Yes
Language type en,zh-cn and ja_JP.

setSelfInfo

Set your own nickname and avatar.
Note:
v2.2.0+ supported. If you use this interface to modify user information during a call, the UI will not be updated immediately, and you will need to wait until the next call to see the changes.
try {
await TUICallKitServer.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`;
}
The parameters are described below:
Parameter
Type
Required
Meaning
nickName
String
Yes
own nickname
avatar
String
Yes
own avatar address

setCallingBell

Note:
v3.0.0+ supported.
Customize the user's incoming call ringtone.
The input is restricted to the local MP3 format file address. It is imperative to ensure that the application has access to this file directory.
Use the import method to import the ringtone file.
If you need to restore the default ringtone, just pass empty filePath.
import filePath from '../assets/phone_ringing.mp3';
try {
await TUICallKitServer.setCallingBell(filePath);
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the setCallingBell API. Reason: ${error}`);
}
The parameters are described below:
Parameter
Type
Required
Meaning
filePath
String
Yes
Ringtone file path

enableFloatWindow

Turn on/off the floating window function. The default is false. The floating window button in the upper left corner of the call interface is hidden. It will be displayed after setting it to true.
Note:
v3.1.0+ supported.
try {
const enable = true;
await TUICallKitServer.enableFloatWindow(enable);
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the enableFloatWindow API. Reason: ${error}`);
}
The parameters are described below:
Parameter
Type
Required
Meaning
enable
Boolean
Yes
Turn on/off the floating window function. default false.

enableMuteMode

Turn on/off the ringtone for incoming calls. When turned on, the incoming call ringtone will not be played when a call request is received.
Note:
v3.1.2+ supported.
try {
const enable = true;
await TUICallKitServer.enableMuteMode(enable);
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
}

joinInGroupCall

Join an existing audio-video call in a group.
Note:
v3.1.2+ supported.
Note:
Before joining an existing audio-video call in the group, an IM group must be pre-established or joined, and users in the group must already be engaged in a call. If the group has already been formed, please ignore this requirement.
Instructions for creating a group can be found at IM Group Management. Alternatively, you may directly utilize IM TUIKit for an all-in-one integration of chat, call and other scenarios.
import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-react';
try {
const params = {
type: TUICallType.VIDEO_CALL,
groupID: "xxx",
roomID: 234,
};
await TUICallKitServer.joinInGroupCall(params);
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);
}
The parameters are described below:
Parameter
Type
Required
Meaning
type
Yes
The media type of communication, for instance, video calls, voice calls
groupID
string
Yes
The group ID for this group call
roomID
number
Yes
Audio and video room ID for this call

enableVirtualBackground

Turn on/off the blurred background function. If you want to set the picture background to be blurry, please refer to. By calling the interface, you can display the blurred background function button on the UI, and click the button to directly enable the blurred background function.
Note:
v3.2.4+ supported.
import { TUICallKitServer } from "@tencentcloud/call-uikit-react";
const enable = true;
TUICallKitServer.enableVirtualBackground(enable);
The parameters are described below:
Parameter
Type
Required
Meaning
enable
boolean
Yes
enable = true, show blur background button
enable = false, don't show blur background button

destroyed

Terminate the TUICallKit instance.
This method won't automatically log out of tim, manual logging out is required: tim.logout();.
try {
await TUICallKitServer.destroyed();
} catch (error: any) {
console.error(`[TUICallKit] Failed to call the destroyed API. Reason: ${error}`);
}

TUICallKit Type Definition

videoDisplayMode

There are three values for the videoDisplayMode display mode:
VideoDisplayMode.CONTAIN
VideoDisplayMode.COVER
VideoDisplayMode.FILL, the default value is VideoDisplayMode.COVER.
Attribute
Value
Description
videoDisplayMode
VideoDisplayMode.CONTAIN
Ensuring the full display of video content is our top priority.
The dimensions of the video are scaled proportionally until one side aligns with the frame of the viewing window.
In case of discrepancy in sizes between the video and the display window, the video is scaled - on the premise of maintaining the aspect ratio - to fill the window, resulting in a black border around the scaled video.
VideoDisplayMode.COVER
Priority is given to ensure that the viewing window is filled.
The video size is scaled proportionally until the entire window is filled.
If the video's dimensions are different from those of the display window, the video stream will be cropped or stretched to match the window's ratio.
VideoDisplayMode.FILL
Ensuring that the entire video content is displayed while filling the window does not guarantee preservation of the original video's proportion.
The dimensions of the video will be stretched to match those of the window.

videoResolution

The resolution videoResolution has three possible values:
VideoResolution.RESOLUTION_480P
VideoResolution.RESOLUTION_720P
VideoResolution.RESOLUTION_1080P, the default value is VideoResolution.RESOLUTION_480P.
Resolution Explanation:
Video Profile
Resolution (W x H)
Frame Rate (fps)
Bitrate (Kbps)
480p
640 × 480
15
900
720p
1280 × 720
15
1500
1080p
1920 × 1080
15
2000
Frequently Asked Questions:
iOS 13&14 does not support encoding videos higher than 720P. It is suggested to limit the highest collection to 720P on these two system versions. Refer to iOS Safari known issue case 12.
Firefox does not permit the customization of video frame rates (default is set to 30fps).
Due to the influence of system performance usage, camera collection capabilities, browser restrictions, and other factors, the actual values of video resolution, frame rate, and bit rate may not necessarily match the set values exactly. In such scenarios, the browser will automatically adjust the Profile to get as close to the set values as feasible.

STATUS

STATUS attribute value
Description
STATUS.IDLE
Idle status
STATUS.BE_INVITED
Received an Audio/Video Call Invite
STATUS.DIALING_C2C
Initiating a one-to-one call
STATUS.DIALING_GROUP
Initiating a group call
STATUS.CALLING_C2C_AUDIO
Engaged in a 1v1 Audio Call
STATUS.CALLING_C2C_VIDEO
In the midst of a one-to-one video call
STATUS.CALLING_GROUP_AUDIO
Engaged in Group Audio Communication
STATUS.CALLING_GROUP_VIDEO
Engaged in group video call

TUICallType

TUICallType Type
Description
TUICallType.AUDIO_CALL
Audio Call
TUICallType.VIDEO_CALL
Video Call

offlinePushInfo

Parameter
Type
Required
Meaning
offlinePushInfo.title
String
No
Offline Push Title (Optional)
offlinePushInfo.description
String
No
Offline Push Content (Optional)
offlinePushInfo.androidOPPOChannelID
String
No
Setting the channel ID for OPPO phones with 8.0 system and above for offline pushes (Optional)
offlinePushInfo.extension
String
No
Offline push through content (optional) (tsignaling version >= 0.9.0)