The event callback service can send notifications about TRTC events in the form of HTTP/HTTPS requests to your server. Currently, you can register callbacks for room events, media events, as well as some recording events (for details about on-cloud recording callbacks, see On-Cloud Recording). To receive such callbacks, you need to configure callback information in the TRTC console.
Callback Information
In order to receive event callback notifications, you need to configure callback information in Tencent RTC Console.
Note:
You need to provide the following information:
Required: An HTTP/HTTPS server address to receive callback notifications.
Optional: A custom key containing up to 32 uppercase and lowercase letters and digits, which is needed for the calculation of signatures.
Timeout and Retry
A notification will be considered failed if the callback server does not receive a response from your server within five seconds of message sending. It will try again immediately after the first failure and retry 10 seconds after every subsequent failure. The retries will stop one minute after the first try.
Format of Callback Messages
Callbacks are sent to your server in the form of HTTP/HTTPS POST requests.
Character encoding: UTF-8
Request: JSON for the request body
Response: HTTP STATUS CODE = 200. The server ignores the content of the response packet. For protocol-friendliness, we recommend adding JSON: {"code":0}` to the response.
Parameters
Callback parameters
The header of a callback message contains the following fields.
Field
Value
Content-Type
application/json
Sign
The signature value.
SdkAppId
The SDK application ID.
The body of a callback message contains the following fields.
Room exit will trigger only the 104 callback and not the 202 or 204 callback. 202 and 204 are triggered only if a user manually turns their video and audio off.
Event Callback Example
101
102
103
104
105
201
202
203
204
205
206
{"EventGroupId":1,
"EventType":101,
"CallbackTs":1687770730166,
"EventInfo":{
"RoomId":12345,
"EventTs":1687770730,
"EventMsTs":1687770730160,
"UserId":"test"
}
}
{
"EventGroupId":1,
"EventType":102,
"CallbackTs":1687771618531,
"EventInfo":{
"RoomId":"12345",
"EventTs":1687771618,
"EventMsTs":1687771618457
}
}
{
"EventGroupId":1,
"EventType":103,
"CallbackTs":1687770731932,
"EventInfo":{
"RoomId":12345,
"EventTs":1687770731,
"EventMsTs":1687770731831,
"UserId":"test",
"Role":21,
"TerminalType":2,
"UserType":3,
"Reason":1
}
}
{
"EventGroupId":1,
"EventType":104,
"CallbackTs":1687770731922,
"EventInfo":{
"RoomId":12345,
"EventTs":1687770731,
"EventMsTs":1687770731898,
"UserId":"test",
"Role":20,
"Reason":1
}
}
{
"EventGroupId":1,
"EventType":105,
"CallbackTs":1687772245596,
"EventInfo":{
"RoomId":12345,
"EventTs":1687772245,
"EventMsTs":1687772245537,
"UserId":"test",
"Role":21
}
}
{
"EventGroupId":2,
"EventType":201,
"CallbackTs":1687771803198,
"EventInfo":{
"RoomId":12345,
"EventTs":1687771803,
"EventMsTs":1687771803192,
"UserId":"test"
}
}
{
"EventGroupId":2,
"EventType":202,
"CallbackTs":1687771919458,
"EventInfo":{
"RoomId":12345,
"EventTs":1687771919,
"EventMsTs":1687771919447,
"UserId":"test",
"Reason":0
}
}
{
"EventGroupId":2,
"EventType":203,
"CallbackTs":1687771869377,
"EventInfo":{
"RoomId":12345,
"EventTs":1687771869,
"EventMsTs":1687771869365,
"UserId":"test"
}
}
{
"EventGroupId":2,
"EventType":204,
"CallbackTs":1687770732498,
"EventInfo":{
"RoomId":12345,
"EventTs":1687770732,
"EventMsTs":1687770732383,
"UserId":"test",
"Reason":0
}
}
{
"EventGroupId":2,
"EventType":205,
"CallbackTs":1687772013823,
"EventInfo":{
"RoomId":12345,
"EventTs":1687772013,
"EventMsTs":1687772013753,
"UserId":"test"
}
}
{
"EventGroupId":2,
"EventType":206,
"CallbackTs":1687772015054,
"EventInfo":{
"RoomId":12345,
"EventTs":1687772015,
"EventMsTs":1687772015032,
"UserId":"test",
"Reason":0
}
}
Event information
Field
Type
Description
RoomId
String/Number
The room ID, which is of the same type as the room ID on the client.
EventTs
Number
The Unix timestamp (seconds) of event occurrence. This field is reserved for compatibility purposes.
EventMsTs
Number
The Unix timestamp (ms) of event occurrence.
UserId
String
User ID
UniqueId
Number
The unique identifier of an event (optional), which is valid for the room event group. When a user experiences unusual events such as network change or abnormal exit and reentry, your server may receive multiple callbacks for the entry and exit of the same user. A unique identifier helps identify a room entry or exit.
Role
Number
The role type (optional), which is valid for the room entry/exit callback.
TerminalType
Number
The device type (optional), which is valid for the room entry callback.
UserType
Number
The user type (optional), which is valid for the room entry callback.
Reason
Number
The reason (optional), which is valid for the room entry/exit callback.
Note:
We have developed a policy that prevents repeated callbacks resulting from unusual events on the client. If you start using the callback service after July 30, 2021, the policy will apply by default, and the room event group will no longer carry UniqueId.
Role type
Field
Value
Description
MEMBER_TRTC_ANCHOR
20
Anchor
MEMBER_TRTC_VIEWER
21
Audience
Device type
Field
Value
Description
TERMINAL_TYPE_WINDOWS
1
Windows
TERMINAL_TYPE_ANDROID
2
Android
TERMINAL_TYPE_IOS
3
iOS
TERMINAL_TYPE_LINUX
4
Linux
TERMINAL_TYPE_OTHER
100
Other
User type
Field
Value
Description
USER_TYPE_WEBRTC
1
WebRTC
USER_TYPE_APPLET
2
Mini Program
USER_TYPE_NATIVE_SDK
3
Native SDK
Reason
Field
Description
Room entry
1: Voluntary entry
2: Network change
3: Timeout and retry
4: Cross-room communication
Room exit
1: Voluntary exit
2: Timeout
3: Removed from the room
4: Cross-room communication was canceled
5: The process was force-closed
Note: TRTC cannot capture a force-close event on Android and will send a callback only after timeout (reason = 2).
Signature calculation
Signatures are calculated using the HMAC SHA256 encryption algorithm. Upon receiving a callback message, your server will calculate a signature using the same method, and if the results match, it indicates that the callback is from TRTC and not forged. See below for the calculation method.
// In the formula below, `key` is the key used to calculate a signature.
Sign = base64(hmacsha256(key, body))
Note:
body is the original packet body of the callback request you receive. Do not make any modifications. Below is an example.
//# body: The body returned by the Tencent Cloud callback
//# sign: The sign value returned by the Tencent Cloud callback
//# Return Value:
//# Status: OK indicates that the verification has passed, FAIL indicates that the verification has failed, and the specific reason can be found in the Info
String body ="{\n"+"\t\"EventGroupId\":\t2,\n"+"\t\"EventType\":\t204,\n"+"\t\"CallbackTs\":\t1664209748188,\n"+"\t\"EventInfo\":\t{\n"+"\t\t\"RoomId\":\t8489,\n"+"\t\t\"EventTs\":\t1664209748,\n"+"\t\t\"EventMsTs\":\t1664209748180,\n"+"\t\t\"UserId\":\t\"user_85034614\",\n"+"\t\t\"Reason\":\t0\n"+"\t}\n"+"}";
# body: The body returned by the Tencent Cloud callback
# sign: The sign value returned by the Tencent Cloud callback
# Return Value:
# Status: OK indicates that the verification has passed, FAIL indicates that the verification has failed, and the specific reason can be found in the Info
body ="{\n"+"\t\"EventGroupId\":\t2,\n"+"\t\"EventType\":\t204,\n"+"\t\"CallbackTs\":\t1664209748188,\n"+"\t\"EventInfo\":\t{\n"+"\t\t\"RoomId\":\t8489,\n"+"\t\t\"EventTs\":\t1664209748,\n"+"\t\t\"EventMsTs\":\t1664209748180,\n"+"\t\t\"UserId\":\t\"user_85034614\",\n"+"\t\t\"Reason\":\t0\n"+"\t}\n"+"}"
var data ="{\n\t\"EventGroupId\":\t1,\n\t\"EventType\":\t101,\n\t\"CallbackTs\":\t1608086882372,\n\t\"EventInfo\":\t{\n\t\t\"RoomId\":\t20222,\n\t\t\"EventTs\":\t1608086882,\n\t\t\"UserId\":\t\"222222_phone\"\n\t}\n}"
var key ="789"
//JSRUN engine 2.0, supporting up to 30 types of languages for online running, with full simulation of online interaction for input and output.