通话状态回调

最近更新时间:2024-04-18 14:44:21

我的收藏
为了方便您精细化控制您的通话业务,音视频通话 SDK (TUICallKit)提供了通话状态回调。您的业务后台可以通过该回调实时查看用户的通话结果,如未接听、拒接等,您可以据此进行实时数据统计等操作。回调配置方式参见 回调配置 API 列表

使用条件

仅开通了音视频通话 SDK(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",
"CallId": "aheahfo-eqwnknoihfsd-qweqf",
"Role": "caller",
"CallResult": "normal_end",
"EventTime": 1682415761
}

请求包字段说明

字段
类型
说明
UserId
String
操作的用户 ID
RoomId
String
操作的房间 ID
TotalNum
Integer
参与通话人数
MediaType
String
媒体类型:
audio音频通话
video视频通话
CallId
String
通话唯一 ID
Role
String
角色:
caller主叫 userId
callee被叫 userId
CallResult
String
通话结果,仅在结束事件中填写,其余为空:
cancel 取消:主叫方在接通前取消通话
reject 拒接:被叫方拒接
not_answer 未接听:被叫方超时未接听
normal_end 完成:通话接通并正常结束
call_busy 忙线:通话忙线
interrupt 中断:网络等原因导致通话中断
EventTime
Integer
操作发生的时间戳(秒级)
说明:
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
请求被限频
未知错误码
系统内部错误,请 提交工单 联系技术人员