tencent cloud

文档反馈

通话状态回调

最后更新时间:2024-04-18 16:25:19
    为了方便您精细化控制您的通话业务,音视频通话 Call(TUICallKit)提供了通话状态回调。您的业务后台可以通过该回调实时查看用户的通话结果,如未接听、拒接等,您可以据此进行实时数据统计等操作。回调配置方式参见 回调配置 API 列表

    使用条件

    仅开通了音视频通话 Call(TUICallKit) 群组通话版的应用(SDKAppId)可以使用通话状态回调,您也可以开通体验版免费试用,版本说明及开通指引参见 音视频通话能力版本
    目前各平台仅在特定版本的 TUICallKit 可使用通话状态回调,详见下表:
    平台/框架
    版本号
    Android/iOS/Flutter/uni-app(客户端)
    ≥ 1.7.1
    Web
    ≥ 1.4.6
    微信小程序
    ≥ 1.5.1
    注意:
    参与通话的所有平台/框架升级到上述新的版本后,才可在控制台上查看到对应的通话信息。

    注意事项

    要启用回调,必须配置回调 URL,并打开本条命令字的开关,请参见 创建回调配置
    回调的方向是 Callkit 后台向 App 后台发起 HTTP POST 请求。
    App 后台在收到回调请求之后,务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。

    可能触发该回调的场景

    App 用户通过客户端进行通话所产生的动作,例如挂断等。

    回调的发生时机

    通话结束后。

    可能发生的回调结果

    回调状态
    结果表示
    未接听:被叫方超时未接听
    not_answer
    拒接:被叫方拒接
    reject
    忙线:通话忙线
    call_busy
    取消:主叫方在接通前取消通话
    cancel
    完成:通话接通并正常结束
    normal_end
    中断:网络等原因导致通话中断
    interrupt

    接口说明

    请求URL

    以下示例中 App 配置的回调 URL 为 https://www.example.com示例:
    $http://www.example.com?sdkappid=$sdkappid&command=$command&contenttype=json&clientip=$clientip&optplatform=$optplatform

    请求参数说明

    参数
    说明
    http
    请求协议为 HTTPS 或 HTTP,请求方式为 POST
    www.example.com
    回调 URL
    sdkappid
    创建应用时在即时通信 IM 控制台分配的 SDKAppID
    command
    请参见:回调命令字列表
    contenttype
    固定值为 json
    clientip
    客户端 IP,格式如:127.0.0.1
    optplatform
    客户端平台,可能是 iOS、Android、Web、miniProgram
    具体的回调内容在 HTTP 请求包体中,参见下文回调示例。

    回调示例

    回调请求示例:
    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
    }

    请求包字段说明

    字段
    类型
    说明
    UserId
    String
    操作的用户 ID
    RoomId
    String
    操作的房间 ID
    TotalNum
    Integer
    参与通话人数
    MediaType
    String
    媒体类型:
    audio音频通话
    video视频通话
    CallType
    String
    通话类型:
    single音频通话
    group视频通话
    CallId
    String
    通话唯一 ID
    Role
    String
    角色:
    caller主叫 userId
    callee被叫 userId
    CallResult
    String
    通话结果,仅在结束事件中填写,其余为空:
    cancel 取消:主叫方在接通前取消通话
    reject 拒接:被叫方拒接
    not_answer 未接听:被叫方超时未接听
    normal_end 完成:通话接通并正常结束
    call_busy 忙线:通话忙线
    interrupt 中断:网络等原因导致通话中断
    EventTime
    Integer
    操作发生的时间戳(秒级)
    StartCallTs
    Integer
    通话发起的时间戳(秒级)只有在normal_end才会回调此值
    AcceptTs
    Integer
    通话接听的时间戳(秒级)只有在normal_end才会回调此值
    EndTs
    Integer
    通话结束的时间戳(秒级)只有在normal_end才会回调此值
    说明:
    CallResult 字段仅一对一通话可能显示所有类型,群聊仅有normal_end

    回调应答示例

    App 后台同步数据后,发送回调应答包。
    {
    "ErrorCode": 0,
    "ErrorMessage": "Success"
    }

    应答包字段说明

    字段
    类型
    说明
    ErrorCode
    Integer
    0 为成功,其余为失败
    ErrorMessage
    String
    您的服务器响应可以自定义携带错误信息
    注意:
    您的服务器在正确接收到请求包时,建议您及时回复正确的应答包,否则会触发系统重试,重试机制如下。

    重试机制

    触发重试的时机
    ErrorCode = 0 视为回调成功,否则会触发重试。
    向您的 appServer 发 http 请求报错也会触发重试。
    重试间隔
    重试间隔为0s, 1s, 1s, 2s, 3s, 5s若均为成功则放弃。

    错误码

    错误码
    含义说明
    0
    请求成功
    50001
    当前应用需要购买 TUICallKit 群组通话版套餐包方可使用
    999
    回调不存在
    70001
    请求参数无效,请检查必填参数是否缺失或填错
    70002
    UserSig 无效
    70003
    UserSig 过期
    70004
    请求用户非超级管理员
    70005
    请求被限频
    未知错误码
    系统内部错误,请 提交工单 联系技术人员
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持