tencent cloud

Feedback

TUICallKit

Last updated: 2024-04-03 17:23:11

    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
    init
    Initialize the `TUICallKit` component instance
    call
    Initiate a one-on-one call
    groupCall
    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
    destroyed
    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

    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, 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
    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 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
    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 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)
    
    
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support