tencent cloud

实时音视频

文档实时音视频视频通话 SDK客户端 APIAndroidCallStore

CallStore

Download
聚焦模式
字号
最后更新时间： 2026-07-29 14:36:00

简介

音视频通话功能通过 CallStore 实现用户之间的实时音视频互动。CallStore 提供了一套全面的 API 来管理整个通话生命周期。 在接入 CallStore 时，请务必了解以下运行时特性：
异常处理（Error Handling）：主动调用 API（如 calls）时，若因参数校验或状态冲突等导致调用本身失败，通常会以异步抛出错误事件或返回错误码的形式通知。网络或远端异常也会通过 onCallEnded 携带错误原因下发。
线程模型与释放：所有的状态更新（CallState）和事件回调（CallEvent / CallEventListener）通常保证在主线程（Main Thread）触发，可直接用于刷新 UI。全局单例模式下，请务必在组件销毁时（如 deinit / onDestroy）反注册监听器，避免内存泄漏。
重要：
请在 SDK 初始化成功后，通过 CallStore.shared 单例获取 CallStore 实例，不要尝试直接初始化，否则将无法接收通话状态更新。
说明：
通话状态更新通过 observerState 发布者传递。订阅它以接收通话数据的实时更新。
警告：
请确保在通话结束后正确处理 UI 状态，避免出现界面异常。

功能特性

发起音视频通话：支持向单个或多个用户发起音频通话或视频通话，可配置超时时间、自定义数据等参数。
接听/拒绝音视频通话：收到来电邀请时，可选择接听或拒绝。
挂断音视频通话：结束当前正在进行的音视频通话。
群组通话管理：支持加入已存在的群组通话，或在通话中邀请其他用户加入。
通话记录管理：查询最近的通话记录（支持分页），删除指定的通话记录。
事件驱动架构：提供通话开始、收到邀请、通话结束等事件监听。
状态订阅：实时订阅当前通话状态，包括参与者列表、音量信息、网络质量等。

可订阅数据

CallState 的字段描述如下：
属性名
类型
描述
activeCall
StateFlow<CallInfo>
当前活跃的通话信息。 【生命周期约定】：在触发 onCallEnded 时，该对象不会被立即置空，而是保留通话终态供 UI 展示结束动画（此时 CallInfo.result 或其它参数反映结束原因）。若业务重新发起或接到新通话，会自动覆盖。开发者可通过重置 CallStore 相关状态进行手动清理。
recentCalls
StateFlow<LinkedHashSet<CallInfo>>
最近通话记录列表。
注意：
每次调用 queryRecentCalls 后，该状态当前表现为覆盖更新，而不是自动追加（Append）。如需实现无限滚动效果，业务层需自行将新到达的数据拼接到原有列表中。
cursor
StateFlow<String>
分页游标，用于查询更多通话记录。
selfInfo
当前用户自身信息。
allParticipants
StateFlow<LinkedHashSet<CallParticipantInfo>>
当前通话所有参与者列表。
speakerVolumes
StateFlow<MutableMap<String, Int>>
参与者音量信息，key 为用户 ID，value 为音量值。
networkQualities
StateFlow<MutableMap<String, NetworkQuality>>
参与者网络质量信息，key 为用户 ID，value 为网络质量。

API 列表

函数名
描述
获取 CallStore 单例实例。
通话事件发布者。
通话事件发布者。
发起通话。
接听通话。
拒绝通话。
挂断通话。
加入群组通话。
邀请用户加入通话。
查询最近通话记录。
删除通话记录。
调用实验性 API。

获取实例

CallStore.shared

获取 CallStore 单例实例。

观察状态和事件

addListener

添加通话事件回调监听器。
abstract fun addListener(listener: CallListener)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
listener
监听器。

removeListener

移除通话事件回调监听器。
abstract fun removeListener(listener: CallListener)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
listener
监听器。

通话操作

calls

向指定用户发起音频或视频通话，支持单人通话和多人通话。
abstract fun calls(
    participantIds: List<String>,
    mediaType: CallMediaType,
    params: CallParams?,
    completion: CompletionHandler?
)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
participantIds
List<String>
被呼叫者 ID 列表，支持单人或多人。
mediaType
通话媒体类型（音频/视频）。
params
通话参数配置。
completion
CompletionHandler?
完成回调（成功/失败状态）。

accept

接听通话。收到来电邀请时调用此方法接听通话。
abstract fun accept(completion: CompletionHandler?)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
completion
CompletionHandler?
完成回调（成功/失败状态）。

reject

拒绝通话。收到来电邀请时调用此方法拒绝通话。
abstract fun reject(completion: CompletionHandler?)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
completion
CompletionHandler?
完成回调（成功/失败状态）。

hangup

挂断并结束当前正在进行的通话。
abstract fun hangup(completion: CompletionHandler?)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
completion
CompletionHandler?
完成回调（成功/失败状态）。

join

使用特定的 Call ID 加入一个正在进行中的群组通话。
abstract fun join(callId: String, completion: CompletionHandler?)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
callId
String
要加入的通话 ID。
completion
CompletionHandler?
完成回调（成功/失败状态）。

invite

在通话进行中邀请其他用户加入。
abstract fun invite(
    participantIds: List<String>,
    params: CallParams?,
    completion: CompletionHandler?
)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
participantIds
List<String>
被邀请者 ID 列表。
params
通话参数配置。
completion
CompletionHandler?
完成回调（成功/失败状态）。

通话记录

queryRecentCalls

查询最近的通话记录。 【当前限制】：目前查询结果每次都会覆盖（重置） state.recentCalls 列表，而不是自动追加。
abstract fun queryRecentCalls(
    cursor: String,
    count: Int,
    completion: CompletionHandler?
)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
cursor
String
分页游标，首次查询时传空字符串。
count
Int
查询数量。
completion
CompletionHandler?
完成回调。

deleteRecentCalls

删除指定的通话记录。
abstract fun deleteRecentCalls(
    callIdList: List<String>,
    completion: CompletionHandler?
)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
callIdList
List<String>
要删除的通话 ID 列表。
completion
CompletionHandler?
完成回调（成功/失败状态）。

实验性接口

callExperimentalAPI

调用实验性 API。
abstract fun callExperimentalAPI(jsonStr: String)
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
jsonStr
String
包含 API 名称和参数的 JSON 字符串。

数据结构

CallMediaType

通话媒体类型，用于指定发起音频通话还是视频通话。
枚举值
值
说明
Audio
1
音频通话。
Video
2
视频通话。

CallEndReason

通话结束原因，用于标识音视频通话是如何结束的（正常挂断、拒绝、超时等）。
枚举值
值
说明
Unknown
0
未知原因。
Hangup
1
正常挂断。
Reject
2
拒绝接听。
NoResponse
3
无响应。
Offline
4
对方离线。
LineBusy
5
对方忙线。
Canceled
6
通话被取消。
OtherDeviceAccepted
7
其他设备已接听。
OtherDeviceReject
8
其他设备已拒绝。
EndByServer
9
后台结束通话。

CallDirection

通话方向，用于标识通话是呼入、呼出还是未接来电。
枚举值
值
说明
Unknown
0
未知。
Missed
1
未接来电。
Incoming
2
呼入。
Outgoing
3
呼出。

CallParticipantStatus

通话参与者状态，用于标识参与者当前是等待中还是已接听。
枚举值
值
说明
None
0
无状态（未在通话中）。
Waiting
1
等待中（呼叫中/被呼叫中）。
Accept
2
已接听。

CloudRecordPolicy

音视频通话的云端录制策略，用于配置某次通话是否开启云端录制。
枚举值
值
说明
FollowConsoleConfig
0
跟随控制台的全局配置（默认）。
Enable
1
开启云端录制，覆盖控制台配置。
Disable
2
关闭云端录制，覆盖控制台配置。

CallListener

通话事件，用于接收通话过程中的各种事件通知。
方法
方法名
说明
onCallStarted
通话事件开始启动的回调。 时机说明：它表示“当前已经成功进入通话流程（如发起了 calls 并被内部接受）”，但并不表示音视频房间已经接通或建立。建议仅用于做最初始的界面跳转（主叫侧）。
onCallReceived
收到新通话邀请的回调。 字段建议：事件参数仅透传 callId、mediaType 和 userData。如果需要读取邀请人、房间 ID 或绑定的群组 ID 等全量信息，请在收到该事件后通过 state.activeCall 读取。
onCallEnded
通话统一结束事件回调。 场景说明：无论是接通后挂断、未接听超时、被远端取消，还是其他设备已接听，都会最终触发此事件。开发者必须通过参数中的 reason 来判断具体的原因以展示对应的 UI 文案或进行分支处理。 获取通话时长：该事件的参数中不包含通话时长字段。如需获取通话时长，请在收到此回调时通过 state.activeCall.duration 读取，单位为秒。通话接通后 SDK 内部会每秒递增该值；通话结束时 activeCall 不会被立即置空，因此可在本回调中安全读取。
onSuggestSwitchToCellular
当系统检测到 WiFi 质量较差并建议切换到蜂窝网络时触发的回调。

CallParams

通话参数配置，用于发起音视频通话时设置房间 ID、超时时间、自定义数据等参数。
属性
类型
说明
roomId
String
TRTC 房间 ID（CallStore 的媒体流管理使用了腾讯云 TRTC 服务）。可选参数。 不传时由服务端自动生成；如果业务需要指定或复用 TRTC 房间，可传入指定的字符串。
timeout
Int
振铃超时时间（秒）。可选参数。 仅控制从发起呼叫（calls）到接听的未接听超时阶段。对已接通后的通话或 invite 操作不生效。 设为0时，将使用服务端默认值（30s）。
userData
String
呼叫时附带的自定义透传数据。可选参数。 该数据主要通过被叫端的 onCallReceived 事件暴露给业务侧读取。
注意：
它不会进入长期的 CallInfo 状态，也不会被持久化到通话记录中。建议传入简短的 JSON 字符串。
chatGroupId
String
腾讯云 Chat 的群组 ID。可选参数。
仅在“群聊发起的通话”场景下需要传入，传入后系统会将信令路由并把该通话关联至此群组的通话记录，用于在该群聊中发送通话开始/结束等状态消息，以及在通话过程中邀请群成员加入。
一对一通话、或非固定群组的临时多人通话，请务必留空。
注意：
该字段在首次 calls 时生效，后续 invite 传参无法更改此通话绑定的群组。
isEphemeralCall
Boolean
无痕通话。可选参数。 设为 true 时，本次通话结束后不再产生通话消息，常见场景：1v1聊天中发起通话，不希望显示通话消息。
cloudRecordPolicy
本次通话的云端录制策略。生效前提是已经在控制台开通相关能力。
followConsoleConfig（默认）：跟随控制台的全局配置。
enable：强制开启云端录制，覆盖控制台的全局配置。
disable：强制关闭云端录制，覆盖控制台的全局配置。
offlinePushTitle
String
离线推送通知标题。 非空时覆盖默认标题（登录用户昵称）。
offlinePushDescription
String
离线推送通知描述。 非空时覆盖默认描述。

CallParticipantInfo

通话参与者信息，包含用户 ID、昵称、头像、参与状态、麦克风/摄像头开关状态等。
属性
类型
说明
id
String
用户 ID。
name
String
用户昵称。
avatarURL
String
用户头像 URL。
remark
String
好友备注。
status
参与者状态。
isMicrophoneOpened
Boolean
麦克风是否开启。
isCameraOpened
Boolean
摄像头是否开启。

CallInfo

通话信息，包含通话 ID、房间 ID、发起者、被邀请者、媒体类型、通话方向、开始时间、时长等完整信息。
属性
类型
说明
callId
String
通话 ID。
roomId
String
房间 ID。
inviterId
String
发起者 ID。
inviteeIds
LinkedHashSet<String>
被邀请者 ID 列表。
chatGroupId
String
Chat 群组 ID。
mediaType
通话媒体类型。
注意：
在早期事件阶段、未知类型，或历史通话记录（recent calls）未完整回填该字段时可能为空（null / nil），业务需注意可选解包。
result
通话方向/记录类型（如呼入、呼出、未接）。
注意：
这不代表通话挂断的具体原因，结束原因请参考 CallEndReason 枚举。
startTime
Long
通话真正开始（接通）的时间戳。(单位：毫秒)。
duration
Long
通话时长（秒）。

CallState

通话状态数据，管理当前通话的实时数据状态。
属性
类型
说明
activeCall
StateFlow<CallInfo>
当前活跃的通话信息。 【生命周期约定】：在触发 onCallEnded 时，该对象不会被立即置空，而是保留通话终态供 UI 展示结束动画（此时 CallInfo.result 或其它参数反映结束原因）。若业务重新发起或接到新通话，会自动覆盖。开发者可通过重置 CallStore 相关状态进行手动清理。
recentCalls
StateFlow<LinkedHashSet<CallInfo>>
最近通话记录列表。
注意：
每次调用 queryRecentCalls 后，该状态当前表现为覆盖更新，而不是自动追加（Append）。如需实现无限滚动效果，业务层需自行将新到达的数据拼接到原有列表中。
cursor
StateFlow<String>
分页游标，用于查询更多通话记录。
selfInfo
当前用户自身信息。
allParticipants
StateFlow<LinkedHashSet<CallParticipantInfo>>
当前通话所有参与者列表。
speakerVolumes
StateFlow<MutableMap<String, Int>>
参与者音量信息，key 为用户 ID，value 为音量值。
networkQualities
StateFlow<MutableMap<String, NetworkQuality>>
参与者网络质量信息，key 为用户 ID，value 为网络质量。

使用示例

import io.trtc.tuikit.atomicxcore.api.call.*
// 发起视频通话
CallStore.shared.calls(
    participantIds = listOf("mike"),
    mediaType = CallMediaType.Video,
    params = null
) { code, message ->
}

上一篇: TUICallKit（含 UI）下一篇: CallCoreView

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈