Call
  • Web
    • Overview
      • Product Introduction
      • Activate the Service
      • 价格中心
        • 免费时长
        • Call 包月套餐
        • 订阅套餐时长计费说明
    • Get Started
      • Run Sample Code
      • Integration (React)
      • Integration (Vue3)
      • Secure authentication with userSig
    • Basic Features
      • UI Customization
      • Configuring Nickname and Avatar
      • GroupCall
      • 悬浮窗
      • 自定义铃声
      • 设置分辨率和填充模式
      • 监控通话状态
    • Advanced Features
      • 虚拟背景
      • AI 降噪
      • 云端录制
    • 客户端 API
      • UIKit APIs
        • API Overview
        • TUICallKit
      • Engine APIs
        • TUICallEngine
        • TUICallEvent
    • 服务端 API
      • 通话状态回调
        • 通话状态回调
        • 通话事件回调
        • 回调配置
          • 回调配置接口列表
          • 创建回调配置
          • 查询回调配置
          • 更新回调配置
          • 删除回调配置
      • REST 接口
        • REST 接口简介
        • 通过 callId 获取记录
        • 通过条件获取记录
    • FAQs
      • All Platfroms
      • Web
      • ErrorCode
      • 发布说明
  • Android
    • Overview
      • Product Introduction
      • Activate the Service
      • Pricing
        • Free Minutes
        • Call Monthly Packages
        • Billing Explanation for Subscription Package Duration
    • Get Started
      • 跑通 Demo
      • 集成
      • Secure authentication with userSig
    • Basic Features
      • UI 定制
      • 离线通话推送
      • Configuring Nicknames and Avatars
      • 群组通话
      • 悬浮窗
      • 自定义铃声
      • 监控通话状态
    • 更多功能
      • 虚拟背景
      • AI 降噪
      • 云端录制
    • 客户端 API
      • UIKit APIs
        • 接口概述
        • TUICallKit
        • TUICallObserver
        • 类型定义
      • Engine APIs
        • TUICallEngine
    • 服务端 API
      • 通话状态回调
        • 通话状态回调
        • 通话事件回调
        • 回调配置
          • 回调配置接口列表
          • 创建回调配置
          • 查询回调配置
          • 更新回调配置
          • 删除回调配置
      • REST 接口
        • REST 接口简介
        • 通过 callId 获取记录
        • 通过条件获取记录
    • FAQs
      • All Platforms
      • Android
      • ErrorCode
      • 发布说明
  • iOS
    • Overview
      • Product Introduction
      • Activate the Service
      • Pricing
        • Free Minutes
        • Call Monthly Packages
        • Billing Explanation for Subscription Package Duration
    • Get Started
      • 跑通 Demo
      • 集成
      • Secure authentication with userSig
    • Basic Features
      • UI 定制
      • 离线通话推送
        • VoIP
        • APN
      • 设置昵称和头像
      • 群组通话
      • 悬浮窗
      • 自定义铃声
      • 监控通话状态
    • 更多功能
      • 虚拟背景
      • AI 降噪
      • 云端录制
    • 客户端 API
      • UIKit APIs
        • 接口概述
        • TUICallKit
        • TUICallObserver
        • 类型定义
      • Engine APIs
        • TUICallEngine
    • 服务端 API
      • 通话状态回调
        • 通话状态回调
        • 通话事件回调
        • 回调配置
          • 回调配置接口列表
          • 创建回调配置
          • 查询回调配置
          • 更新回调配置
          • 删除回调配置
      • REST 接口
        • REST 接口简介
        • 通过 callId 获取记录
        • 通过条件获取记录
    • FQAs
      • All Platform
      • iOS
      • ErrorCode
      • 发布说明
  • Flutter
    • Overview
      • 产品概述
      • 开通服务
      • Pricing
        • Free Minutes
        • Call Monthly Packages
        • Billing Explanation for Subscription Package Duration
    • Get Started
      • 跑通 Demo
      • 集成
      • Secure authentication with userSig
    • Basic Features
      • UI 定制
      • 离线通话推送
        • 通知
        • VoIP(可选)
      • 设置昵称和头像
      • 群组通话
      • 悬浮窗
      • 自定义铃声
      • 监控通话状态
    • 更多功能
      • 虚拟背景
      • AI 降噪
      • 云端录制
      • 美颜特效
    • 客户端 API
      • 接口概述
      • TUICallKit
      • TUICallEngine
      • TUICallObserver
      • 类型定义
    • 服务端 API
      • 通话状态回调
        • 通话状态回调
        • 通话事件回调
        • 回调配置
          • 回调配置接口列表
          • 创建回调配置
          • 查询回调配置
          • 更新回调配置
          • 删除回调配置
      • REST 接口
        • REST 接口简介
        • 通过 callId 获取记录
        • 通过条件获取记录
    • FQAs
      • All Platform
      • Flutter
      • ErrorCode
      • 升级
      • 发布说明
Call

通话状态回调

为了方便您精细化控制您的通话业务,音视频通话 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
请求被限频
未知错误码
系统内部错误,请 提交工单 联系技术人员