Call Status Callback
To facilitate refined control of your call services, the TRTC Call (TUICallKit) offers call status callbacks. Your business backend can use these callbacks to peek at users' call results in real-time, such as missed calls, rejections, etc., and based on this, perform real-time data analytics and other operations. For calling configuration methods, see Callback Configuration API List.
Use Conditions
Only applications (SDKAppId) that have activated the Group Call Version of TRTC Call can use the call status callback. You can also activate the trial version for free to test. For version descriptions and activation instructions, refer to Activate the Service.
Currently, call status callbacks are available only in specific versions of TUICallKit across various platforms, as detailed in the table below:
Platform/Framework | Version number |
Android/iOS/Flutter/uni-app (client) | ≥ 1.7.1 |
Web | ≥ 1.4.6 |
WeChat Mini Program | ≥ 1.5.1 |
Note:
Only after all participating platforms/frameworks are upgraded to the versions mentioned above, can the corresponding call information be peeked at in the console.
Notes
To enable the callback, you must configure the callback URL and enable the switch for this command. Please refer to Create Callback Configuration.
The direction of the callback is from the Callkit backend to the app backend via an HTTP POST request.
After receiving the callback request, the app backend must check whether the SDKAppID contained in the request URL is consistent with its own SDKAppID.
Scenarios that may trigger this callback
Actions performed by app users through the client during a call, such as hanging up, etc.
Timing of the callback
After the call ends.
Possible callback results
Callback status | Result indication |
Missed call: Recipient timeout before answering | not_answer |
Declined call: Recipient declined the call | reject |
Busy Line: Busy line | call_busy |
Cancel: Caller canceled the call before connecting | cancel |
Completion: Call connected and ended normally | normal_end |
Interruption: Call interrupted due to network or other reasons | interrupt |
API description
Request URL
In the following example, the callback URL configured in the app is
https://www.example.com.
Example:$http://www.example.com?sdkappid=$sdkappid&command=$command&contenttype=json&clientip=$clientip&optplatform=$optplatform
Request parameters
Parameter | Description |
http | Request protocol is HTTPS or HTTP, request method is POST |
www.example.com | Callback URL |
sdkappid | SDKAppID assigned by the Instant Messaging console when an application is created |
command | |
contenttype | Fixed value: json |
clientip | Client IP, such as 127.0.0.1 |
optplatform | Client platforms may include iOS, Android, Web, miniProgram |
The specific callback content is included in the HTTP request body. See the callback examples below for details.
Callback Example
Webhook request example:
POST /?sdkappid=8888888&command=call_end&contenttype=json&clientip=127.0.0.1&optplatform=iOS HTTP/1.1Host: www.example.comContent-Length: 337{"UserId": "Alice","RoomId": "Alice's Room","TotalNum": 2,"MediaType": "audio","CallType": "single","CallId": "aheahfo-eqwnknoihfsd-qweqf","Role": "caller","CallResult": "normal_end","EventTime": 170485688,"StartCallTs": 1704856873,"AcceptTs": 1704856876,"EndTs": 1704856885}
Request packet fields
Field | Type | Description |
UserId | String | Operating User ID |
RoomId | String | Operating Room ID |
TotalNum | Integer | Number of Participants in Call |
MediaType | String | Media Type: Audio Audio CallVideo Video Call |
CallType | String | Call Type: Single Audio CallGroup Video Call |
CallId | String | Call Unique ID |
Role | String | role : Caller User IDCallee User ID |
CallResult | String | Call Result, only filled in during the end event, otherwise empty: Cancel: Caller canceled the call before connectionReject Declined: Recipient declined the callNot_answer Missed call: Recipient did not answer in timeNormal_end Completion: Call connected and ended normallyCall_busy Busy line: Busy line during callInterrupt Interruption: Call interrupted due to network or other reasons |
EventTime | Integer | Timestamp of operation (second-level) |
StartCallTs | Integer | Timestamp when call is initiated (second-level) only returned on normal_end |
AcceptTs | Integer | Timestamp when call is answered (second-level) only returned on normal_end |
EndTs | Integer | Timestamp when call ends (second-level) only returned on normal_end |
Note:
CallResult field shows all types only for one-on-one calls, group chat only has
normal_end.Callback Response Example
A callback response packet is sent after the app backend synchronizes the data.
{"ErrorCode": 0,"ErrorMessage": "Success"}
Response Packet Field Description
Field | Type | Description |
ErrorCode | Integer | 0 indicates success, all other values indicate failure |
ErrorMessage | String | Your server response can carry error information as defined |
Note:
It is recommended that your server responds with the correct response packet promptly after receiving the request packet correctly, otherwise, it will trigger a system retry. The retry mechanism is as follows.
Retry mechanism
When to trigger a retry
ErrorCode = 0 is considered a successful callback, otherwise, it will trigger a retry.
An HTTP request error to your appServer will also trigger a retry.
Retry interval
Retry interval:
0s, 1s, 1s, 2s, 3s, 5s. If all attempts fail, the process will be abandoned.Error code
Error code | Description |
0 | Request succeeded |
50001 | The current application needs to purchase the TUICallKit Group Call Version Package to use |
999 | Callback does not exist |
70001 | Invalid request parameters, please check whether mandatory parameters are missing or incorrectly entered |
70002 | UserSig is invalid |
70003 | UserSig has expired |
70004 | Requesting user is not a Super Administrator |
70005 | Request frequency limited |
Unknown error code |