Overview
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: Swift Access to 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 |
Initialize the `TUICallKit` component instance | |
Initiate a one-on-one call | |
Initiate a group call | |
Actively join the ongoing group call | |
Establish a personalised ringtone for incoming calls | |
Configure the user's nickname and profile photo | |
Toggle On/Off the ringtone for incoming calls | |
Activate/Deactivate the floating window function | |
Set the call language for the TUICallKit component | |
Terminate the TUICallKit component instance |
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
import { TUICallKit, VideoDisplayMode, VideoResolution } from "@tencentcloud/call-uikit-react";<TUICallKitvideoDisplayMode={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, which should be accomplished prior to 'call' and 'groupCall'.
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});alert("[TUICallKit] Initialization succeeds.");} catch (error: any) {alert(`[TUICallKit] Initialization failed. Reason: ${error}`);}
The parameters are described below:
Parameter | Type | Required | Meaning |
SDKAppID | Number | Yes | SDKAppID of the cloud communication application |
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 | A safeguard signature designed by Tencent Cloud. For acquisition method, kindly refer to the calculation of UserSig |
tim | Any | No | The tim parameter is viable if a TIM instance already exists in the business, to ensure the uniqueness of the TIM instance |
call
Initiate a one-on-one call.
try {await TUICallKitServer.call({userID: callUserID,type: TUICallType.VIDEO_CALL,});} catch (error: any) {alert(`[TUICallKit] Call failed. Reason: ${error}`);}
The parameters are described below:
Parameter | Type | Required | Meaning |
userID | String | Yes | target user's userId |
type | Yes | ||
roomID | Number | No | Numerical Room ID, range [1, 2147483647] |
timeout | Number | No | Call timeout duration, 0 signifies no timeout, unit s(seconds) (optional) - Default 30s |
userData | String | No | Extension field: Used to enhance the invitation signal with additional information |
Object | No | Customize offline message pushing |
groupCall
Initiate group communication.
try {await TUICallKitServer.groupCall({userIDList: ['jack', 'tom'],groupID: "xxx",type: TUICallType.VIDEO_CALL});} catch (error: any) {alert(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);}
The parameters are described below:
Parameter | Type | Required | Meaning |
userIDList | Array<String> | Yes | Invitation list member lists |
type | Yes | The type of media for the call, you can refer to TUICallType for the explanation of parameter values | |
groupID | String | Yes | |
roomID | Number | No | Numerical Room ID, range [1, 2147483647] |
timeout | Number | No | Call timeout duration, 0 signifies no timeout, unit s(seconds) (optional) - Default 30s |
userData | String | No | Extended field: Utilized for amplifying details in the invitation signaling |
Object | No | Customize offline message pushing |
setLanguage
Language configuration.
TUICallKitServer.setLanguage("zh-cn"); // "en" | "zh-cn"
The parameters are described below:
Parameter | Type | Required | Meaning |
lang | String | Yes | Language type en or zh-cn |
setSelfInfo
Note:Vue ≥ v2.2.0 is supported. Using this interface to modify user information during a call will not immediately update the UI. Changes will be visible in the next call.
Setting user nickname and profile picture.
try {await TUICallKitServer.setSelfInfo({ nickName: "xxx", avatar: "http://xxx" });} catch (error: any) {alert(`[TUICallKit] Failed to call the setSelfInfo API. Reason: ${error}`;}
The parameters are described below:
Parameter | Type | Required | Meaning |
nickName | String | Yes | User's nickname |
avatar | String | Yes | User profile picture URL |
setCallingBell
Note:Vue ≥ v3.0.0 is 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 ES6 import method to import the ringtone file.
try {await TUICallKitServer.setCallingBell(filePath?: string)} catch (error: any) {alert(`[TUICallKit] Failed to call the setCallingBell API. Reason: ${error}`);}
enableFloatWindow
Note:Vue ≥ v3.1.0 is supported
Enable/Disable floating window functionality.
By default, the floating window button in the top left corner of the call interface is hidden (
false
). It is displayed when set to true.try {await TUICallKitServer.enableFloatWindow(enable: Boolean)} catch (error: any) {alert(`[TUICallKit] Failed to call the enableFloatWindow API. Reason: ${error}`);}
enableMuteMode
Note:Vue ≥ v3.1.2 is supported
Enable/Disable incoming call ringtone.
After enabling, the incoming call ringtone will not be played when a call request is received.
try {await TUICallKitServer.enableMuteMode(enable: boolean)} catch (error: any) {alert(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);}
joinInGroupCall
Note:Vue ≥ v3.1.2 is supported
Join an existing audio-video call in a group.
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.
try {const params = {type: TUICallType.VIDEO_CALL,groupID: "xxx",roomID: 0,};await TUICallKitServer.joinInGroupCall(params);} catch (error: any) {alert(`[TUICallKit] Failed to call the enableMuteMode API. Reason: ${error}`);}
Parameter list:
Parameter | Type | Required | Meaning |
type | Yes | The media type of communication, for instance, video calls, voice calls | |
groupID | string | Yes | Group ID associated with this group call |
roomID | number | Yes | Audio-Video Room ID for this call |
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) {alert(`[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) |