Tencent Real-Time Communication Room and Media Callback-No UI Integration-Help & Documentation-Tencent Cloud

The event callback service supports notifying your server of events under the TRTC business in the form of HTTP/HTTPS requests. The event callback service has integrated the Room Event Group and the Media Event Group. You can provide tencent cloud with related configuration information to enable this service.
Configuration Information
Tencent Real-Time Communication (TRTC) Console supports self-service configuration of callback information. After the configuration is complete, event callback notifications can be received. For detailed operation guide, please refer to Callback Configuration.
﻿
﻿
﻿
Note:
You need to prepare the following information in advance.
Required item: The HTTP/HTTPS server address for receiving callback notifications.
Optional: The key for calculated signature. Customize a key with a maximum of 32 characters, consisting of uppercase and lowercase letters and numbers.
Timeout Retry
If the event callback server does not receive a response from your server within 5 seconds after sending a message notification, the notification is considered failed. After the first notification failure, it will retry immediately. Subsequent failures will continue to retry at intervals of 10 seconds until the message retention time exceeds 1 minute, after which no further retries will be made.
Event Callback Message Format
Event callback messages are sent to your server via an HTTP/HTTPS POST request, where:
Character Encoding Format: UTF-8.
Request: The body format is JSON.
Response: HTTP STATUS CODE = 200, the server ignores the specific content of the response packet. For protocol friendliness, it is recommended that customers include JSON in the response content: {"code":0}.
Note:
Your HTTP response packet length (header + body) needs to be controlled within 2000 bytes.
The JSON body of a POST request will not delete existing fields, but will add new fields based on business needs. When integrating callbacks, you need to adapt to these additional fields situation.
Parameter Description
Callback Message Parameters
The header of the event callback message contains the following fields:
Field Name
Value
Content-Type
application/json
Sign
Signature value
SdkAppId
sdk application id
The body of the event callback message contains the following fields:
Field Name
Type
Meaning
EventGroupId
Number
Event Group ID
EventType
Number
Event type of callback notification
CallbackTs
Number
Unix Timestamp of Callback Request Sent by Event Callback Server to Your Server, in milliseconds
EventInfo
JSON Object
Event Information
Event Group ID
Field Name
Value
Meaning
EVENT_GROUP_ROOM
1
Room Event Group
EVENT_GROUP_MEDIA
2
Media event group
Note:
Notes on the recording event group, please see enable cloud recording and playback.
Event Type
Field Name
Value
Meaning
EVENT_TYPE_CREATE_ROOM
101
Create Room
EVENT_TYPE_DISMISS_ROOM
102
Dissolve Room
EVENT_TYPE_ENTER_ROOM
103
Enter room
EVENT_TYPE_EXIT_ROOM
104
Exit room
EVENT_TYPE_CHANGE_ROLE
105
Role switch
EVENT_TYPE_START_VIDEO
201
Start pushing video data
EVENT_TYPE_STOP_VIDEO
202
Stop pushing video data
EVENT_TYPE_START_AUDIO
203
Start pushing audio data
EVENT_TYPE_STOP_AUDIO
204
Stop pushing audio data
EVENT_TYPE_START_ASSIT
205
Start pushing auxiliary route data
EVENT_TYPE_STOP_ASSIT
206
Stop pushing auxiliary route data
Note:
Exiting a room will only trigger the 104 event, not the 202 and 204 events. The 104 event essentially encompasses the 202 and 204 events. Manually turning off video/audio will trigger the 202/204 events.
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 Name
Type
Meaning
RoomId
String/Number
Room name (type consistent with the client room ID type)
EventTs
Number
Unix Timestamp of Event Occurrence, in seconds (compatible and reserved)
EventMsTs
Number
Unix Timestamp of Event Occurrence in milliseconds
UserId
String
User ID
UniqueId
Number
Unique identifier (carried by room event group, optional) 
When the client exhibits some unusual behavior, such as switching networks, abnormal process exits and re-entries, etc., your callback server may receive multiple room entry and exit callbacks for the same user at this time. UniqueId can be used to identify the same user's room entry and exit at the same time.
Role
Number
<Role Type> (option: carrying during room entry/exit)
TerminalType
Number
Terminal type (option: carrying when entering a room)
UserType
Number
User type (option: carrying when entering a room)
Reason
Number
Reason (option: carrying during room entry/exit, stopping media stream)
ClientIpv4
String
Client Ipv4 address (option: carried in event 103 when using Ipv4 to enter a room)
ClientIpv6
String
Client Ipv6 address (option: carried in event 103 when using Ipv6 to enter a room)
Note:
We have released the policy of "filtering repeated callbacks caused by client special behavior". If you are integrating the callback service after July 30, 2021, the new policy will be applied by default, and the Room Event Group will no longer carry the UniqueId (unique identifier). 
Role Type
Field Name
Value
Meaning
MEMBER_TRTC_ANCHOR
20
Broadcaster
MEMBER_TRTC_VIEWER
21
Audience
Terminal Type
Field Name
Value
Meaning
TERMINAL_TYPE_WINDOWS
1
For Windows:
TERMINAL_TYPE_ANDROID
2
Android
TERMINAL_TYPE_IOS
3
iOS
TERMINAL_TYPE_LINUX
4
Linux end
TERMINAL_TYPE_OTHER
100
Others
Type of User
Field Name
Value
Meaning
USER_TYPE_WEBRTC
1
webrtc
USER_TYPE_APPLET
2
WeChat Mini Program
USER_TYPE_NATIVE_SDK
3
Native SDK
Specific Reasons
Field Name
Meaning
Enter room
1: Enter room normally
2: Switch network
3: Timeout and retry.
4: Enter room for cross-room mic-connection
Check out
1: Exit room normally
2: Timeout exit
3: Room user removed
4: Cancel mic connection and exit room
5: Force kill
Note: The Android system cannot capture the forced termination of a process. It can only wait for the backend to time out and exit. At this point, the callback reason is 2.
Stop media stream.
0: Stop normally.
1: Timeout stop.
Note: If the media stream fails to be received in the backend for 30 seconds (default), the callback to stop the media stream event will be triggered, carrying a Reason of 1, indicating a timeout stop.
Calculating Signature
The signature is calculated using the HMAC SHA256 encryption algorithm. After your event callback receiving server receives the callback message, it calculates the signature in the same way. If the signatures match, it indicates that the event callback of Tencent Cloud's Real-Time Communication is authentic and has not been tampered with. The signature calculation is as follows:
//Signature Sign. The key in the computational formula is the encryption key used for calculated signature Sign.
Sign = base64(hmacsha256(key, body))
Note:
The body is the original package body of the callback request you received. Do not perform any conversion. An example is as follows:
body="{\n\t\"EventGroupId\":\t1,\n\t\"EventType\":\t103,\n\t\"CallbackTs\":\t1615554923704,\n\t\"EventInfo\":\t{\n\t\t\"RoomId\":\t12345,\n\t\t\"EventTs\":\t1608441737,\n\t\t\"UserId\":\t\"test\",\n\t\t\"UniqueId\":\t1615554922656,\n\t\t\"Role\":\t20,\n\t\t\"Reason\":\t1\n\t}\n}"
Signature Verification Example
Java
Python
PHP
Golang
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
//# Feature: Third-party callback sign verification
Parameter:
//#   key: console-configured key
//#   body: returned body from Tencent Cloud callback
//#   sign: Signature value sign returned by Tencent Cloud callback
//# Return value:
//#   Status: OK means verification passed, FAIL means verification failure, refer to Info for specific reasons
//#   Info: Success/Failure Information
﻿
public class checkSign {
    public static String getResultSign(String key, String body) throws Exception {
        Mac hmacSha256 = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
        hmacSha256.init(secret_key);
        return Base64.getEncoder().encodeToString(hmacSha256.doFinal(body.getBytes()));
    }
    public static void main(String[] args) throws Exception {
        String key = "123654";
        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" + "}";
        String Sign = "kkoFeO3Oh2ZHnjtg8tEAQhtXK16/KI05W3BQff8IvGA=";
        String resultSign = getResultSign(key, body);
﻿
        if (resultSign.equals(Sign)) {
            System.out.println("{'Status': 'OK', 'Info': 'Verification passed'}");
        } else {
            System.out.println("{'Status': 'FAIL', 'Info': 'Verification failure'}");
        }
    }
}
﻿
# -*- coding: utf8 -*-
import hmac
import base64
from hashlib import sha256
﻿
# Feature: Third-party callback sign verification
# The parameters are as follows:
# Key: key configured in the console
#   body: returned body from Tencent Cloud callback
#   sign: Signature value sign returned by Tencent Cloud callback
# Return value:
#   Status: OK means verification passed, FAIL means verification failure, refer to Info for specific reasons
# Info: Success/Failure Information
﻿
def checkSign(key, body, sign):
    temp_dict = {}
    computSign = base64.b64encode(hmac.new(key.encode('utf-8'), body.encode('utf-8'), digestmod=sha256).digest()).decode('utf-8')
    print(computSign)
    if computSign == sign:
        temp_dict['Status'] = 'OK'
        temp_dict['Info'] = 'Validation passed'
        return temp_dict
    else:
        temp_dict['Status'] = 'FAIL'
        temp_dict['Info'] = 'Verification failure'
        return temp_dict
﻿
if __name__ == '__main__':
    key = '123654'
    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" + "}"
    sign = 'kkoFeO3Oh2ZHnjtg8tEAQhtXK16/KI05W3BQff8IvGA='
    result = checkSign(key, body, sign)
    print(result)
﻿
﻿
﻿
<?php
﻿
class TlsEventSig {
    
    private $key = false;
    private $body = false;
    
    public function __construct( $key, $body ) {
        $this->key = $key;
		$this->body = $body;
    }
﻿
    private function __hmacsha256() {
        $hash = hash_hmac( 'sha256', $this->body, $this->key, true );
		return base64_encode( $hash);
    }
    
    public function genEventSig() {
        return $this->__hmacsha256();
    }
}
﻿
$key="789";
$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}";
﻿
$api = new  TlsEventSig($key, $data);
echo $api->genEventSig();
﻿
﻿
package main
import "fmt"
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
)
﻿
func main () {
    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"
﻿
    fmt.Println(hmacsha256(data,key))
}
﻿
func hmacsha256(data string, key string) string {
	h := hmac.New(sha256.New, []byte(key))
	h.Write([]byte(data))
	return base64.StdEncoding.EncodeToString(h.Sum(nil))
}
Field Name	Value
Content-Type	application/json
Sign	Signature value
SdkAppId	sdk application id
Field Name	Type	Meaning
EventGroupId	Number	Event Group ID
EventType	Number	Event type of callback notification
CallbackTs	Number	Unix Timestamp of Callback Request Sent by Event Callback Server to Your Server, in milliseconds
EventInfo	JSON Object	Event Information
Field Name	Meaning
Enter room	1: Enter room normally 2: Switch network 3: Timeout and retry. 4: Enter room for cross-room mic-connection
Check out	1: Exit room normally 2: Timeout exit 3: Room user removed 4: Cancel mic connection and exit room 5: Force kill Note: The Android system cannot capture the forced termination of a process. It can only wait for the backend to time out and exit. At this point, the callback reason is 2.
Stop media stream.	0: Stop normally. 1: Timeout stop. Note: If the media stream fails to be received in the backend for 30 seconds (default), the callback to stop the media stream event will be triggered, carrying a Reason of 1, indicating a timeout stop.
Room and Media Callback

On this page:

Configuration Information

Timeout Retry

Event Callback Message Format

Parameter Description

Callback Message Parameters

Event Group ID

Event Type

Event Callback Example

Event Information

Role Type

Terminal Type

Type of User

Specific Reasons

Calculating Signature

Signature Verification Example
