- 动态与公告
- 产品简介
- 购买指南
- 新手指引
- Demo 体验
- 视频通话（含 UI）
- 多人会议（含 UI）
- 在线直播（含 UI）
- 语音聊天室（含 UI）
- 无 UI 集成
- 高级功能
- 服务端 API
- 控制台指南
- 解决方案
- 常见问题
- 旧版文档
- 协议与策略
- TRTC 政策
- 词汇表
- 动态与公告
- 产品简介
- 购买指南
- 新手指引
- Demo 体验
- 视频通话（含 UI）
- 多人会议（含 UI）
- 在线直播（含 UI）
- 语音聊天室（含 UI）
- 无 UI 集成
- 高级功能
- 服务端 API
- 控制台指南
- 解决方案
- 常见问题
- 旧版文档
- 协议与策略
- TRTC 政策
- 词汇表
为了方便您精细化控制您的通话业务，音视频通话 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.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}
请求包字段说明
字段 | 类型 | 说明 |
UserId | String | 操作的用户 ID |
RoomId | String | 操作的房间 ID |
TotalNum | Integer | 参与通话人数 |
MediaType | String | 媒体类型： audio音频通话video视频通话 |
CallType | String | 通话类型： single音频通话group视频通话 |
CallId | String | 通话唯一 ID |
Role | String | 角色： caller主叫 userIdcallee被叫 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 | 请求被限频 |
未知错误码 |
是
否
本页内容是否解决了您的问题？