tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Tencent Real-Time Communication
    Documentation
    Download PDF

    Call Status Callback

    Last updated: 2024-04-18 16:25:27
    Download PDF
      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.

      Contact Us
      Technical Support

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

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy