tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Tencent Real-Time Communication
    Documentation
    Download PDF

    TUICallKit

    Last updated: 2024-06-28 14:38:07
    Download PDF

      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
      Hidden Button, v3.2.9+ support
      Set the background image for the local user's call interface, v3.2.9+ support
      Set the background image for the remote user's call interface, v3.2.9+ support
      Set the call interface layout mode, v3.3.0+ support
      et whether the camera is opened by default, v3.3.0+ support
      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]
      strRoomID
      String
      No
      String room ID. v3.3.1+ supported range：
      Limited to 64 bytes in length. The supported character set range is as follows (a total of 89 characters):
      Lowercase and uppercase English letters.（a-zA-Z）；
      Number（0-9）；
      Spaces、!、#、$、%、&、(、)、+、-、:、;、<、=、.、>、?、@、[、]、^、_、{、}、|、~、,。
      1. roomID and strRoomID are mutually exclusive, if you use strRoomID, then roomID should be 0. If you use both, the SDK will prioritize the roomID. 2.
      2. don't mix roomID and strRoomID, because they are not interchangeable, for example, the number 123 and the string "123" are two completely different rooms.
      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]
      strRoomID
      String
      No
      String room ID. v3.3.1+ supported range：
      Limited to 64 bytes in length. The supported character set range is as follows (a total of 89 characters):
      Lowercase and uppercase English letters.（a-zA-Z）；
      Number（0-9）；
      Spaces、!、#、$、%、&、(、)、+、-、:、;、<、=、.、>、?、@、[、]、^、_、{、}、|、~、,。
      1. roomID and strRoomID are mutually exclusive, if you use strRoomID, then roomID should be 0. If you use both, the SDK will prioritize the roomID. 2.
      2. don't mix roomID and strRoomID, because they are not interchangeable, for example, the number 123 and the string "123" are two completely different rooms.
      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 see Web. 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}`);
      }

      hideFeatureButton

      Hidden feature buttons, currently only support Camera, Microphone, and Switch Camera Button.
      Note：
      v3.2.9+ supported.
      TUICallKitServer.hideFeatureButton(buttonName: FeatureButton);
      The parameters are described below:
      Parameter
      Type
      Required
      Meaning
      buttonName
      Yes
      Button Name

      setLocalViewBackgroundImage

      Set the background image for the local user's call interface.
      Note：
      v3.2.9+ supported.
      TUICallKitServer.setLocalViewBackgroundImage(url: string);
      The parameters are described below:
      Parameter
      Type
      Required
      Meaning
      url
      string
      Yes
      Image Address (supports Local Path and Network Address)

      setRemoteViewBackgroundImage

      Set the background image for the remote user's call interface.
      Note：
      v3.2.9+ supported.
      TUICallKitServer.setRemoteViewBackgroundImage(userId: string, url: string);
      The parameters are described below:
      Parameter
      Type
      Required
      Meaning
      userId
      string
      Yes
      Remote User userId, setting to '*' means it applies to all Remote Users
      url
      string
      Yes
      Image Address (supports Local Path and Network Address)

      setLayoutMode

      Set the call interface layout mode.
      Note：
      upported from v3.3.0+.
      Vue
      React
      import { TUICallKitServer, LayoutMode } from "@tencentcloud/call-uikit-vue";
      TUICallKitServer.setLayoutMode(LayoutMode.LocalInLargeView);
      import { TUICallKitServer, LayoutMode } from "@tencentcloud/call-uikit-react";
      TUICallKitServer.setLayoutMode(LayoutMode.LocalInLargeView);
      Parameter list:
      Parameter
      Type
      Required
      Meaning
      layoutMode
      Yes
      User flow layout mode

      setCameraDefaultState

      Set whether the camera is on by default.
      Note：
      upported from v3.3.0+.
      TUICallKitServer.setCameraDefaultState(true);
      Parameter list:
      Parameter
      Type
      Required
      Meaning
      isOpen
      boolean
      Yes
      Whether to enable the camera

      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. Can be used to set Android Notification mode and VoIP mode. Default: Notification mode, it will be a notification from the system; VoIP mode is required to pass the field.
      offlinePushInfo.ignoreIOSBadge
      Boolean
      No
      Ignore badge count for offline push (only for iOS), if set to true, the message will not increase the unread count of the app icon on the iOS receiver's side.
      v3.3.0+ supported
      offlinePushInfo.iOSSound
      String
      No
      Offline push sound setting (only for iOS). v3.3.0+ supported
      offlinePushInfo.androidSound
      String
      No
      Offline push sound setting. v3.3.0+ supported
      offlinePushInfo.androidVIVOClassification
      Number
      No
      Classification of VIVO push messages (deprecated interface, VIVO push service will optimize message classification rules on April 3, 2023. It is recommended to use setAndroidVIVOCategory to set the message category). 0: Operational messages, 1: System messages. The default value is 1. v3.3.0+ supported
      offlinePushInfo.androidXiaoMiChannelID
      String
      No
      Set the channel ID for Xiaomi phones with Android 8.0 and above systems. v3.3.0+ supported
      offlinePushInfo.androidFCMChannelID
      String
      No
      Set the channel ID for google phones with Android 8.0 and above systems. v3.3.0+ supported
      offlinePushInfo.androidHuaWeiCategory
      String
      No
      Classification of Huawei push messages. v3.3.0+ supported
      offlinePushInfo.isDisablePush
      Boolean
      No
      Whether to turn off push notifications (default is on). v3.3.0+ supported
      offlinePushInfo.iOSPushType
      Number
      No
      iOS offline push type，default is 0。0-APNs；1-VoIP. v3.3.0+ supported

      Android Notification Mode

      const extension = {
        timPushFeatures: {        
          fcmPushType: 0, // 0, VoIP; 1, notification
        }
      };
      offlinePushInfo.extension = JSON.stringify(extension);

      Android VoIP Mode

      const extension = {
        timPushFeatures: {        
          fcmPushType: 0, // 0, data; 1, notification
          fcmNotificationType: 1, // 0, TIMPush implementation； 1, business implementation after transparent transmission 
        }
      };
      offlinePushInfo.extension = JSON.stringify(extension);

      FeatureButton

      FeatureButton Type
      Description
      FeatureButton.Camera
      Camera Button
      FeatureButton.Microphone
      Microphone Button
      FeatureButton.SwitchCamera
      Switches between the front and rear cameras.

      LayoutMode

      LayoutMode type
      Description
      LayoutMode.LocalInLargeView
      Local user in large window display
      LayoutMode.RemoteInLargeView
      Remote user in large window display
      Contact Us

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

      Contact Us
      Technical Support

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

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy