tencent cloud

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.

Demo Download

You can download the source code of the web demo at TUICalling.

Environment Requirements

We recommend you use Chrome for PC to run the demo as it offers better support for the features of the TRTC Web SDK. For more information on environment requirements, see Environment Requirements.

URL Protocol Support

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.

Basic SDK APIs

Call operation APIs

Video APIs

API Details

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().

npm i trtc-js-sdk --save
npm i tim-js-sdk --save
npm i tsignaling --save
npm i trtc-calling-js --save
// If you download the dependency using Node.js, you can import it using an import command.
import TRTCCalling from 'trtc-calling-js';
 // If you use JavaScript, you need to manually import the following resources in the specified order.
// trtc.js
<script src="./trtc.js"></script>
// tim-js.js
<script src="./tim-js.js"></script>
// tsignaling.js
<script src="./tsignaling.js"></script>
// trtc-calling-js.js
<script src="./trtc-calling-js.js"></script>
let options = {
SDKAppID: 0, // Replace `0` with the `SDKAppID` of your IM application when connecting
// The `tim` parameter is added starting from v0.10.2
// The parameter guarantees the uniqueness of an existing TIM instance.
tim: tim
};
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 a list of the events, see TRTCCalling Events.

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:

logout()

This API is used to log out.

trtcCalling.logout()

Call operation APIs

call({userID, type, offlinePushInfo})

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

Note：

• The timeout parameter is deleted from v1.0.0 and later versions.
• A new parameter, offlinePushInfo, is introduced for offline notifications, which are supported only on Android and iOS, not on web or WeChat Mini Program.

// Versions earlier than v1.0.0
trtcCalling.call({userID, type, timeout})

// v1.0.0 and later versions
const offlinePushInfo = {
  title: '',
  description: 'You are invited to a call.',
}
trtcCalling.call({userID, type, offlinePushInfo})

The parameters are as detailed below:

offlinePushInfo (in v1.0.0 and later versions)

groupCall({userIDList, type, groupID, offlinePushInfo})

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.

Note：

In v1.0.0 and later versions, a new parameter, offlinePushInfo, is introduced for offline notifications, which are supported only on Android and iOS, not on web or WeChat Mini Program.

// Versions earlier than v1.0.0
trtcCalling.groupCall({userIDList, type, groupID})

// v1.0.0 and later versions
const offlinePushInfo = {
  title: '',
  description: 'You are invited to a call.',
}
trtcCalling.groupCall({userIDList, type, groupID, offlinePushInfo})

The parameters are as detailed below:

offlinePushInfo (in v1.0.0 and later versions)

accept()

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.
• params is deleted from v1.0.0 and later versions.

import TRTCCalling from 'trtc-calling-js';
trtcCalling.on(TRTCCalling.EVENT.INVITED, ({inviteID, sponsor, inviteData}) => {
  // ...
  // Versions earlier than v1.0.0
  const { roomID, callType } = inviteData;
  trtcCalling.accept({inviteID, roomID, callType})
  // v1.0.0 and later versions
  trtcCalling.accept();
})

The parameters are as detailed below:

reject()

This API is used to reject an invitation.

Note：

params is deleted from v1.0.0 and later versions.

import TRTCCalling from 'trtc-calling-js';
trtcCalling.on(TRTCCalling.EVENT.INVITED, ({inviteID, sponsor, inviteData}) => {
  // ...
  // Versions earlier than v1.0.0
  const { callType } = inviteData;
  trtcCalling.reject({inviteID, isBusy, callType})
  // v1.0.0 and later versions
  trtcCalling.reject();
})

The parameters are as detailed below:

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:

stopRemoteView({userID})

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

Note：

videoViewDomID is deleted from v1.0.0 and later versions.

// Versions earlier than v1.0.0
trtcCalling.stopRemoteView({userID, videoViewDomID});
// v1.0.0 and later versions
trtcCalling.stopRemoteView({userID});

The parameters are as detailed below:

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:

stopLocalView({userID})

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

Note：

videoViewDomID is deleted from v1.0.0 and later versions.

// Versions earlier than v1.0.0
trtcCalling.stopLocalView({userID, videoViewDomID});
// v1.0.0 and later versions
trtcCalling.stopLocalView({userID});

The parameters are as detailed below:

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 off

The parameters are as detailed below:

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, or accept to take effect.

trtcCalling.setVideoQuality('720p') // Set video quality to `720p`

The parameters are as detailed below:

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.
• If you receive an error callback (code: 60001), the switching failed.

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.
• If you receive an error callback (code: 60002), the switching failed.

trtcCalling.switchToVideoCall() // Switch from audio call to video call

getCameras()

This API is used to get the camera list.

Note：

This is a new API in v1.0.0 and later versions.

trtcCalling.getCameras() // Get the camera list

getMicrophones()

This API is used to get the mic list.

Note：

This is a new API in v1.0.0 and later versions.

trtcCalling.getMicrophones() // Get the mic list

switchDevice({deviceType, deviceId})

This API is used to switch to a different camera or mic.

Note：

This is a new API in v1.0.0 and later versions.

trtcCalling.switchDevice({deviceType: 'audio', deviceId: deviceId}) // Switch to a different device

The parameters are as detailed below:

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)

Invitation events

Common event callbacks

SDK_READY

The SDK is ready.

Note：

This is a new event callback in v1.0.0 and later versions.

let onSDKReady = function(event) {
  console.log(event)
};
trtcCalling.on(TRTCCalling.EVENT.SDK_READY, onSDKReady);

USER_ENTER

A user entered the room.
This event callback is triggered when a user joins the call.

let handleUserEnter = function({userID}) {
  console.log(userID)
};
trtcCalling.on(TRTCCalling.EVENT.USER_ENTER, handleUserEnter);

The parameters are as detailed below:

USER_LEAVE

A user left the room.
This event callback is triggered when a user leaves the call.

let handleUserLeave = function({userID}) {
  console.log(userID)
};
trtcCalling.on(TRTCCalling.EVENT.USER_LEAVE, handleUserLeave);

The parameters are as detailed below:

GROUP_CALL_INVITEE_LIST_UPDATE

The invitee list for a group call was updated.

Note：

This is a new event callback in v1.0.0 and later versions.

let handleGroupInviteeListUpdate = function(event) {
  console.log(event)
};
trtcCalling.on(TRTCCalling.EVENT.GROUP_CALL_INVITEE_LIST_UPDATE, handleGroupInviteeListUpdate);

CALL_END

The call ended.
This event callback is triggered when a call ends.

let handleCallingEnd = function(event) {
  console.log(event)
};
trtcCalling.on(TRTCCalling.EVENT.CALL_END, handleCallingEnd);

KICKED_OUT

A user was kicked out due to repeated login.
This event callback is triggered if a user logs in with the same account on another page.

let handleKickedOut = function(event) {
  console.log(event)
};
trtcCalling.on(TRTCCalling.EVENT.KICKED_OUT, handleKickedOut);

USER_VIDEO_AVAILABLE

A remote user turned the camera on/off.
This event callback is triggered when a remote user turns the camera on/off.

let handleUserVideoChange = function({userID, isVideoAvailable}) {
  console.log(userID, isVideoAvailable)
};
trtcCalling.on(TRTCCalling.EVENT.USER_VIDEO_AVAILABLE, handleUserVideoChange);

The parameters are as detailed below:

USER_AUDIO_AVAILABLE

A remote user turned the mic on/off.
This event callback is triggered when a remote user turns the mic on/off.

let handleUserAudioChange = function({userID, isAudioAvailable}) {
  console.log(userID, isAudioAvailable)
};
trtcCalling.on(TRTCCalling.EVENT.USER_AUDIO_AVAILABLE, handleUserAudioChange);

The parameters are as detailed below:

Event callbacks received by inviter

REJECT

The user rejected the call.
The inviter of a call will receive this callback if an invitee rejects the call.

let handleInviteeReject = function({userID}) {
  console.log(userID)
};
trtcCalling.on(TRTCCalling.EVENT.REJECT, handleInviteeReject);

The parameters are as detailed below:

NO_RESP

The invitee did not answer.
In cases where a timeout period is specified for a one-to-one or group call, the inviter will receive this callback if an invitee does not answer the call within the specified timeout period.

let handleNoResponse = function({userID, userIDList}) {
  console.log(userID, userIDList)
};
trtcCalling.on(TRTCCalling.EVENT.NO_RESP, handleNoResponse);

The parameters are as detailed below:

LINE_BUSY

The invitee is in a call, i.e., the line is busy.
The inviter of a call will receive this callback if the invitee is already in a call.

let handleLineBusy = function({userID}) {
  console.log(userID)
};
trtcCalling.on(TRTCCalling.EVENT.LINE_BUSY, handleLineBusy);

The parameters are as detailed below:

Event callbacks received by invitee

INVITED

An invitation was received.
A user will receive this callback if he or she is invited to a call.

let handleNewInvitationReceived = function({
    sponsor, userIDList, isFromGroup, inviteData, inviteID
}) {
  console.log(sponsor, userIDList, isFromGroup, inviteData, inviteID)
};
trtcCalling.on(TRTCCalling.EVENT.INVITED, handleNewInvitationReceived);

The parameters are as detailed below:

CALLING_CANCEL

The call is canceled.
An invitee of a call will receive this callback if the call is canceled.

let handleCallingCancel = function(event) {
  console.log(event)
};
trtcCalling.on(TRTCCalling.EVENT.CALLING_CANCEL, handleCallingCancel);

CALLING_TIMEOUT

The call timed out.
In cases where a timeout period is specified for a one-to-one or group call, an invitee will receive this callback if he or she does not answer the call within the specified timeout period.

let handleCallingTimeout = function(event) {
  console.log(event)
};
trtcCalling.on(TRTCCalling.EVENT.CALLING_TIMEOUT, handleCallingTimeout);

TRTCCalling Error Codes

You can register the error callback, as shown below, to handle the errors thrown by the component.

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

Error codes

Update Guide

• Updating to TRTCCalling 1.0.2 or above
  • You need to update TSignaling to v0.9.0 or above.
  • Reason: See Changelog.
• Updating to TRTCCalling 1.0.0 or 1.0.1
  • You need to update TSignaling to v0.8.0 or above.
  • Reason: See Changelog.

FAQs

Why can’t I get through to a user? 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 logs in with the same account multiple times or on different devices, which disrupts signaling.
• Offline signaling: Only online instances can receive messages. Messages sent to offline instances will not be sent again when the instances go online.
  For FAQs about TRTCCalling for web, see TRTCCalling for Web.

Technical Support

If you have other questions, you can fill out a contact form or email colleenyu@tencent.com.

Learn More

• TRTCCalling web demo
• TRTCCalling for npm
• Source code of TRTCCalling web demo
• TRTCCalling web APIs
• FAQs