tencent cloud

Feedback

Call Status Callback

Last updated: 2024-04-18 16:25:27
    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
    Please refer to: Callback command list
    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.1
    Host: www.example.com
    Content-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 Call
    Video Video Call
    CallType
    String
    Call Type:
    Single Audio Call
    Group Video Call
    CallId
    String
    Call Unique ID
    Role
    String
    role :
    Caller User ID
    Callee User ID
    CallResult
    String
    Call Result, only filled in during the end event, otherwise empty:
    Cancel: Caller canceled the call before connection
    Reject Declined: Recipient declined the call
    Not_answer Missed call: Recipient did not answer in time
    Normal_end Completion: Call connected and ended normally
    Call_busy Busy line: Busy line during call
    Interrupt 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
    System internal error, please Submit a ticket to contact technical personnel
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support