TRTCCalling API(Web)

Last updated: 2021-09-02 09:58:43

TRTCCalling Overview

The TRTCCalling component is based on Tencent Real-Time Communication (TRTC) and Instant Messaging (IM). It supports one-to-one and group audio/video calls. For detailed instructions on how to implement it, see Real-Time Audio Call (Web).

  • TRTC SDK: the TRTC SDK is used as a low-latency audio/video call component.
  • IM SDK: the IM SDK is used to send and process signaling messages.

TRTCCalling APIs

Event subscribing/unsubscribing APIs

This component bases its management on the dispatching of events. The application layer can change UI interactions according to dispatched events.

API Description
on(eventName, callback, context) Subscribes to an event.
off(eventName, callback, context) Unsubscribes from an event.

Basic SDK APIs

API Description
login({userID, userSig}) Logs in to IM. All IM features can be used only after login.
logout() Logs out. No calls can be made after logout.

Call operation APIs

API Description
call({userID, type, timeout})) Makes a one-to-one call.
groupCall({userIDList, type, groupID}) Makes a group call.
accept({inviteID, roomID, callType}) Accepts a call invitation.
reject({inviteID, isBusy, callType}) Rejects a call invitation.
hangup() Hangs up.

Video APIs

API Description
startRemoteView({userID, videoViewDomID}) Starts rendering the image of a remote user.
stopRemoteView({userID, videoViewDomID}) Stops rendering the image of a remote user.
startLocalView({userID, videoViewDomID}) Starts rendering the image of the local user.
stopLocalView({userID, videoViewDomID}) Stops rendering the image of the local user.
openCamera() Turns the camera on.
closeCamera() Turns the camera off.
setMicMute(isMute) Mutes/Unmutes the mic.
setVideoQuality(profile) Sets video quality.
switchToAudioCall() Switches to audio call.
switchToVideoCall() Switches to video call.

Closer Look at TRTCCalling

Creating a TRTCCalling instance

First, create an application in the TRTC console and get the SDKAppID.
Then, obtain an instance of the TRTCCalling component using new TRTCCalling().

let options = {
SDKAppID: 0 // Replace 0 with the SDKAppID of your IM application when connecting
};
let trtcCalling = new TRTCCalling(options);

Event subscribing/unsubscribing APIs

on(eventName, callback, context)

This API is used to subscribe to an event dispatched by the component. For details about the events, see the event list.

let handleInvite = function ({inviteID, sponsor, inviteData}) {
console.log(`inviteID: ${inviteID}, sponsor: ${sponsor}, inviteData: ${JSON.stringify(inviteData)}`);
};
trtcCalling.on('onInvited', handleInvite, this);

off(eventName, callback, context)

This API is used to unsubscribe from an event.

let handleInvite = function ({inviteID, sponsor, inviteData}) {
console.log(`inviteID: ${inviteID}, sponsor: ${sponsor}, inviteData: ${JSON.stringify(inviteData)}`);
};
trtcCalling.off('onInvited', handleInvite, this);

Basic SDK APIs

login({userID, userSig})

This API is used to log in.

trtcCalling.login({userID, userSig})

The parameters are as detailed below:

Parameter Type Description
userID String ID of current user, which is a string that can contain only letters (a-z and A-Z), digits (0-9), hyphens (-), and underscores (_).
userSig String Tencent Cloud's proprietary security signature. For how to calculate it, see FAQs > UserSig.

logout()

This API is used to log out.

trtcCalling.logout()

Call operation APIs

call({userID, type, timeout})

This API is used to make one-to-one calls. type indicates the type of a call. 1: audio call; 2: video call.

trtcCalling.call({userID, type, timeout})

The parameters are as detailed below:

Parameter Type Description
userID String User ID of the invitee
type Number 1: audio call; 2: video call
timeout Number Timeout period in seconds. 0 means the call will never time out.

groupCall({userIDList, type, groupID})

The groupID parameter is the group ID in the IM SDK. If this parameter is set, call invitations will be broadcast by the group messaging system, which is a simple and reliable way of sending call invitations. If this parameter is left empty, the TRTCCalling component will send an invitation to every invitee.

trtcCalling.groupCall({userIDList, type, groupID})

The parameters are as detailed below:

Parameter Type Description
userIDList Array List of the user IDs of invitees
type Number 1: audio call; 2: video call
groupID String ID of the IM group (optional)

accept({inviteID, roomID, callType})

This API is used to accept an invitation.

Note:

If a prior invitation has not been processed, the component will return a message indicating that the line is busy.

import TRTCCalling from 'trtc-calling-js';
trtcCalling.on(TRTCCalling.EVENT.INVITED, ({inviteID, sponsor, inviteData}) => {
// ...
trtcCalling.accept({inviteID, roomID, callType})
})

The parameters are as detailed below:

Parameter Type Description
inviteID String Invitation ID, which identifies an invitation
roomID Number Room ID
callType Number 1: audio call; 2: video call

reject({inviteID, isBusy, callType})

This API is used to reject an invitation.

import TRTCCalling from 'trtc-calling-js';
trtcCalling.on(TRTCCalling.EVENT.INVITED, ({inviteID, sponsor, inviteData}) => {
// ...
trtcCalling.reject({inviteID, isBusy, callType})
})

The parameters are as detailed below:

Parameter Type Description
inviteID String Invitation ID, which identifies an invitation
isBusy Boolean Whether the line is busy
callType Number 1: audio call; 2: video call

hangup()

  1. If you are in a call, you can use this API to end the call.
  2. If your call is not answered yet, you can use this API to cancel the call.
trtcCalling.hangup()

Video APIs

startRemoteView({userID, videoViewDomID})

This API is used to render the camera data of a remote user in a specified DOM node.

trtcCalling.startRemoteView({userID, videoViewDomID})

The parameters are as detailed below:

Parameter Type Description
UserID String User ID
videoViewDomID String The DOM node in which the user’s data is to be rendered. The data will be played via the video tag of the node.

stopRemoteView({userID, videoViewDomID})

This API is used to delete the DOM node in which the camera data of a remote user is rendered.

trtcCalling.stopRemoteView({userID, videoViewDomID})

The parameters are as detailed below:

Parameter Type Description
UserID String User ID
videoViewDomID String The DOM node whose video tag is to be deleted. The playback will stop.

startLocalView({userID, videoViewDomID})

This API is used to render the camera data of the local user in a specified DOM node.

trtcCalling.startLocalView({userID, videoViewDomID})

The parameters are as detailed below:

Parameter Type Description
UserID String User ID
videoViewDomID String The DOM node in which the local user’s data is to be rendered. The data will be played via the video tag of the node.

stopLocalView({userID, videoViewDomID})

This API is used to delete the DOM node in which the camera data of the local user is rendered.

trtcCalling.stopLocalView({userID, videoViewDomID})

The parameters are as detailed below:

Parameter Type Description
UserID String User ID
videoViewDomID String The DOM node whose video tag is to be deleted. The playback will stop.

openCamera()

This API is used to turn the local camera on.

trtcCalling.openCamera()

closeCamera()

This API is used to turn the camera off.

trtcCalling.closeCamera()

setMicMute(isMute)

This API is used to turn the mic on/off.

trtcCalling.setMicMute(true) // Turn the mic on

The parameters are as detailed below:

Parameter Type Description
isMute Boolean
  • true: turns the mic off.
  • false: turns the mic on.
  • setVideoQuality(profile)

    This API is used to set video quality.

    Note:

    • This is a new API in v0.8.0 and later versions.
    • This API must be called before call, groupCall, and accept to take effect.
    trtcCalling.setVideoQuality('720p') // Set video quality to 720p

    The parameters are as detailed below:

    Parameter Type Description
    profile String
  • 480p: 640 x 480
  • 720p: 1280 x 720
  • 1080p: 1920 x 1080
  • switchToAudioCall()

    This API is used to switch from video call to audio call.

    Note:

    • This is a new API in v0.10.0 and later versions.
    • It can be used only in one-to-one calls.
    • Switching fails if an error event (code: 60001) is returned.
    trtcCalling.switchToAudioCall() // Switch from video call to audio call

    switchToVideoCall()

    This API is used to switch from audio call to video call.

    Note:

    • This is a new API in v0.10.0 and later versions.
    • It can be used only in one-to-one calls.
    • Switching fails if an error event (code: 60002) is returned.
    trtcCalling.switchToVideoCall() // Switch from audio call to video call

    TRTCCalling Events

    The code below demonstrates how to listen for TRTCCalling events.

    import TRTCCalling from 'trtc-calling-js';
    // etc
    function handleInviteeReject({userID}) {

    }
    trtcCalling.on(TRTCCalling.EVENT.REJECT, handleInviteeReject)

    Inviter events

    Code Event Recipient Description
    REJECT Inviter The invitee rejected the call.
    NO_RESP Inviter The invitation timed out without response from the invitee.
    LINE_BUSY Inviter The invitee is in a call, i.e., the line is busy.
    INVITED Invitee You received an invitation.
    CALLING_CANCEL Invitee The call is canceled.
    CALLING_TIMEOUT Invitee The invitation timed out.
    USER_ENTER Inviter and invitee A user entered the room.
    USER_LEAVE Inviter and invitee A user left the room.
    CALL_END Inviter and invitee The call ended.
    KICKED_OUT Inviter and invitee A user was kicked out due to repeated login.
    USER_VIDEO_AVAILABLE Inviter and invitee A remote user turned the camera on/off.
    USER_AUDIO_AVAILABLE Inviter and invitee A remote user turned the mic on/off.

    Common event callback APIs

    USER_ENTER

    A user entered the room.

    function handleUserEnter({userID}) {

    }

    The parameters are as detailed below:

    Parameter Type Description
    userID String User ID

    USER_LEAVE

    A user left the room.

    function handleUserLeave({userID}) {

    }
    The parameters are as detailed below:
    Parameter Type Description
    UserID String User ID

    CALL_END

    The call ended.

    function handleCallEnd() {

    }

    KICKED_OUT

    A user was kicked out due to repeated login.

    function handleKickedOut() {

    }

    USER_VIDEO_AVAILABLE

    A remote user turned the camera on/off.

    function handleUserVideoChange({userID, isVideoAvailable}) {

    }

    The parameters are as detailed below:

    Parameter Type Description
    userID String User ID
    isVideoAvailable Boolean
  • true: the remote user turned the camera on.
  • false: the remote user turned the camera off.
  • USER_AUDIO_AVAILABLE

    A remote user turned the mic on/off.

    function handleUserAudioChange({userID, isAudioAvailable}) {

    }

    The parameters are as detailed below:

    Parameter Type Description
    userID String User ID
    isAudioAvailable Boolean
  • true: the remote user turned the mic on.
  • false: the remote user turned the mic off.
  • Inviter event callback APIs

    REJECT

    The user rejected the call.

    function handleInviteeReject({userID}) {

    }

    The parameters are as detailed below:

    Parameter Type Description
    userId String User ID

    NO_RESP

    The invitee did not answer.

    function handleNoResponse({userID, userIDList}) {

    }

    The parameters are as detailed below:

    Parameter Type Description
    UserID String User ID
    userIDList Array List of timed out users

    LINE_BUSY

    The invitee is in a call, i.e., the line is busy.

    function handleInviteeLineBusy({userID}) {

    }

    The parameters are as detailed below:

    Parameter Type Description
    UserID String User ID

    Invitee event callback APIs

    INVITED

    You received an invitation.

    function handleNewInvitationReceived({
    sponsor, userIDList, isFromGroup, inviteData, inviteID
    }
    )
    {

    }

    The parameters are as detailed below:

    Parameter Type Description
    sponsor String Inviter
    userIDList Array Users invited to the same call
    isFromGroup Boolean Whether it is an IM group invitation
    inviteData Object
  • For a new user invitation: {version, callType, roomID}
  • For the last user hanging up: {version, callType, callEnd}
  • inviteID String Invitation ID, which identifies an invitation

    CALLING_CANCEL

    The call is canceled.

    function handleInviterCancel() {

    }

    CALLING_TIMEOUT

    The call timed out.

    function handleCallTimeout() {

    }

    TRTCCalling Error Codes

    You can handle the errors thrown by the TRTCCalling component by listening for the “error” field in events. Below is an example.

    import TRTCCalling from 'trtc-calling-js';
    let onError = function(error) {
    console.log(error);
    };
    trtcCalling.on(TRTCCalling.EVENT.ERROR, onError);

    Error codes

    Code Type Description
    60001 API call failure Failed to call switchToAudioCall.
    60002 API call failure Failed to call switchToVideoCall.

    FAQ

    Why can’t I get through to the invitee? Why am I kicked offline?

    The TRTCCalling component does not support login of multiple instances or offline signaling for the time being. Please make sure that your current login is unique.

    Note:

    • Multiple instances: a user ID logs in multiple times or on different devices, which disrupts signaling.
    • Offline signaling: only online instances can receive a message. Messages sent to offline instances will not be sent again when the instances go online.