tencent cloud

The event callback service can notify your server of TRTC events in the form of HTTP/HTTPS requests, including some events of the room and media event groups. To enable the service, you need to provide configuration information to Tencent Cloud.

Configuration Information

You can configure callback information in the TRTC console, and will receive event callback notifications after the configuration. For detailed directions, see Callback Configuration.

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 5 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 1 minute after the first try.

Format of Callback Messages

Callbacks are sent to your server in the form of HTTP/HTTPS POST requests, which consist of the following parts:

• 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.
• Packet body sample: Below is an example of the packet body for room entry under the room event group.
  {
      "EventGroupId": 1,        #Room event group
      "EventType": 103,        #Room entry event
      "CallbackTs": 1615554923704,        #Callback time, in milliseconds
      "EventInfo": {
          "RoomId": 12345,        #Numeric room number
          "EventTs": 1615554922,        #Event occurrence time, in seconds
          "UserId": "test",        #User ID
          "UniqueId": 1615554922656,        #Unique identifier
          "Role": 20,                     #User role: Anchor
          "TerminalType": 3,        #Device type: iOS
          "UserType": 3,        #User type: Native SDK
          "Reason": 1        #Reason: Voluntary entry
      }
  }

Parameters

Callback message parameters

• The header of a callback message contains the following fields.

  Field	Value
  Content-Type	application/json
  Sign	Signature value
  SdkAppId	SDK application ID

• The body of a callback message contains the following fields.

  Field	Type	Description
  EventGroupId	Number	Event group ID
  EventType	Number	Type of callback event
  CallbackTs	Number	Unix timestamp (ms) of callback sending
  EventInfo	JSON Object	Event information

Event group ID

Field	Value	Description
EVENT_GROUP_ROOM	1	Room event group
EVENT_GROUP_MEDIA	2	Media event group

Event type

Field	Value	Description
EVENT_TYPE_CREATE_ROOM	101	Creating room
EVENT_TYPE_DISMISS_ROOM	102	Closing room
EVENT_TYPE_ENTER_ROOM	103	Entering room
EVENT_TYPE_EXIT_ROOM	104	Leaving room
EVENT_TYPE_CHANGE_ROLE	105	Switching roles
EVENT_TYPE_START_VIDEO	201	Starting pushing video data
EVENT_TYPE_STOP_VIDEO	202	Stopping pushing video data
EVENT_TYPE_START_AUDIO	203	Starting pushing audio data
EVENT_TYPE_STOP_AUDIO	204	Stopping pushing audio data
EVENT_TYPE_START_ASSIT	205	Starting pushing substream data
EVENT_TYPE_STOP_ASSIT	206	Stopping pushing substream data

Event information

Field	Type	Description
RoomId	String/Number	Room ID, which is of the same type as the room ID on the client
EventTs	Number	Unix timestamp (seconds) of event occurrence. This field is reserved for compatibility purposes.
EventMsTs	Number	Unix timestamp (ms) of event occurrence
UserId	String	User ID
UniqueId	Number	Unique identifier, optional, carried by 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 that the multiple exits and entries are by the same user.
Role	Number	Role type, optional, carried during room entry/exit
TerminalType	Number	Device type, optional, carried during room entry
UserType	Number	User type, optional, carried during room entry
Reason	Number	Reason, optional, carried during room entry/exit

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: Co-anchoring
Room exit	1: Voluntary exit 2: Timeout 3: Removed from the room 4: Co-anchoring was canceled. 5: The process was force-killed. Note: TRTC cannot capture a force-kill 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="{\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}"