实时音视频 CallStore

简介
音视频通话功能通过 CallStore 实现用户之间的实时音视频互动。CallStore 提供了一套全面的 API 来管理整个通话生命周期。 在接入 CallStore 时，请务必了解以下运行时特性：
异常处理（Error Handling）：主动调用 API（如 calls）时，若因参数校验或状态冲突等导致调用本身失败，通常会以异步抛出错误事件或返回错误码的形式通知。网络或远端异常也会通过 onCallEnded 携带错误原因下发。
线程模型与释放：所有的状态更新（CallState）和事件回调（CallEvent / CallEventListener）通常保证在主线程（Main Thread）触发，可直接用于刷新 UI。全局单例模式下，请务必在组件销毁时（如 deinit / onDestroy）反注册监听器，避免内存泄漏。
重要：
请在 SDK 初始化成功后，通过 shared 单例获取 CallStore 实例，不要尝试直接初始化，否则将无法接收通话状态更新。
说明：
通话状态更新通过 state 发布者传递。订阅它以接收通话数据的实时更新。
警告：
请确保在通话结束后正确处理 UI 状态，避免出现界面异常。
功能特性
发起音视频通话：支持向单个或多个用户发起音频通话或视频通话，可配置超时时间、自定义数据等参数。
接听/拒绝音视频通话：收到来电邀请时，可选择接听或拒绝。
挂断音视频通话：结束当前正在进行的音视频通话。
群组通话管理：支持加入已存在的群组通话，或在通话中邀请其他用户加入。
通话记录管理：查询最近的通话记录（支持分页），删除指定的通话记录。
事件驱动架构：提供通话开始、收到邀请、通话结束等事件监听。
状态订阅：实时订阅当前通话状态，包括参与者列表、音量信息、网络质量等。
可订阅数据
CallState 的字段描述如下：
属性名
类型
描述
activeCall
CallInfo
当前活跃的通话信息。
【生命周期约定】：在触发 onCallEnded 时，该对象不会被立即置空，而是保留通话终态供 UI 展示结束动画（此时 CallInfo.result 或其它参数反映结束原因）。若业务重新发起或接到新通话，会自动覆盖。开发者可通过重置 CallStore 相关状态进行手动清理。
recentCalls
[CallInfo]
最近通话记录列表。
注意：
每次调用 queryRecentCalls 后，该状态当前表现为覆盖更新，而不是自动追加（Append）。如需实现无限滚动效果，业务层需自行将新到达的数据拼接到原有列表中。
cursor
String
分页游标，用于查询更多通话记录。
selfInfo
CallParticipantInfo
当前用户自身信息。
allParticipants
[CallParticipantInfo]
当前通话所有参与者列表。
speakerVolumes
[String: Int]
参与者音量信息，key 为用户 ID，value 为音量值。
networkQualities
[String: NetworkQuality]
参与者网络质量信息，key 为用户 ID，value 为网络质量。
API 列表
函数名
描述
shared
获取 CallStore 单例实例。
callEventPublisher
通话事件发布者。
calls
发起通话。
accept
接听通话。
reject
拒绝通话。
hangup
挂断通话。
join
加入群组通话。
invite
邀请用户加入通话。
queryRecentCalls
查询最近通话记录。
deleteRecentCalls
删除通话记录。
获取实例
shared
获取 CallStore 单例实例。
观察状态和事件
callEventPublisher
通话事件发布者。
通话操作
calls
向指定用户发起音频或视频通话，支持单人通话和多人通话。
calls(
  participantIds: string[],
  mediaType: CallMediaType,
  params: CallParams | undefined,
): Promise<void> {
  return this.impl.calls(participantIds, mediaType, params)
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
participantIds
[String]
被呼叫者 ID 列表，支持单人或多人。
mediaType
CallMediaType
通话媒体类型（音频/视频）。
params
CallParams?
通话参数配置。
accept
接听通话。收到来电邀请时调用此方法接听通话。
accept(): Promise<void> {
  return this.impl.accept()
}
版本信息
从3.5版本开始支持。
reject
拒绝通话。收到来电邀请时调用此方法拒绝通话。
reject(): Promise<void> {
  return this.impl.reject()
}
版本信息
从3.5版本开始支持。
hangup
挂断并结束当前正在进行的通话。
hangup(): Promise<void> {
  return this.impl.hangup()
}
版本信息
从3.5版本开始支持。
join
使用特定的 Call ID 加入一个正在进行中的群组通话。
join(callId: string): Promise<void> {
  return this.impl.join(callId)
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
callId
String
要加入的通话 ID。
invite
在通话进行中邀请其他用户加入。
invite(
  participantIds: string[],
  params: CallParams | undefined,
): Promise<void> {
  return this.impl.invite(participantIds, params)
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
participantIds
[String]
被邀请者 ID 列表。
params
CallParams?
通话参数配置。
通话记录
queryRecentCalls
查询最近的通话记录。
【当前限制】：目前查询结果每次都会覆盖（重置） state.recentCalls 列表，而不是自动追加。
queryRecentCalls(cursor: string, count: number): Promise<void> {
  return this.impl.queryRecentCalls(cursor, count)
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
cursor
String
分页游标，首次查询时传空字符串。
count
UInt
查询数量。
deleteRecentCalls
删除指定的通话记录。
deleteRecentCalls(callIdList: string[]): Promise<void> {
  return this.impl.deleteRecentCalls(callIdList)
}
版本信息
从3.5版本开始支持。
参数说明
参数名
类型
描述
callIdList
[String]
要删除的通话 ID 列表。
数据结构
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
关闭云端录制，覆盖控制台配置。
CallEventListener
通话事件，用于接收通话过程中的各种事件通知。
方法
方法名
说明
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
腾讯云 IM 的群组 ID。可选参数。
仅在“群聊发起的通话”场景下需要传入，传入后系统会将信令路由并把该通话关联至此群组的通话记录，用于在该群聊中发送通话开始/结束等状态消息，以及在通话过程中邀请群成员加入。
一对一通话、或非固定群组的临时多人通话，请务必留空。
注意：
该字段在首次 calls 时生效，后续 invite 传参无法更改此通话绑定的群组。
isEphemeralCall
Bool
无痕通话。可选参数。
设为 true 时，本次通话结束后不再产生通话消息，常见场景：1v1聊天中发起通话，不希望显示通话消息。
cloudRecordPolicy
CloudRecordPolicy
本次通话的云端录制策略。生效前提是已经在控制台开通相关能力。
followConsoleConfig（默认）：跟随控制台的全局配置。
enable：强制开启云端录制，覆盖控制台的全局配置。
disable：强制关闭云端录制，覆盖控制台的全局配置。
offlinePushTitle
string
离线推送通知标题。
非空时覆盖默认标题（登录用户昵称）。
offlinePushDescription
string
离线推送通知描述。
非空时覆盖默认描述。
CallParticipantInfo
通话参与者信息，包含用户 ID、昵称、头像、参与状态、麦克风/摄像头开关状态等。
属性
类型
说明
id
String
用户 ID。
name
String
用户昵称。
avatarURL
String
用户头像 URL。
remark
String
好友备注。
status
CallParticipantStatus
参与者状态。
isMicrophoneOpened
Bool
麦克风是否开启。
isCameraOpened
Bool
摄像头是否开启。
CallInfo
通话信息，包含通话 ID、房间 ID、发起者、被邀请者、媒体类型、通话方向、开始时间、时长等完整信息。
属性
类型
说明
callId
String
通话 ID。
roomId
String
房间 ID。
inviterId
String
发起者 ID。
inviteeIds
[String]
被邀请者 ID 列表。
chatGroupId
String
Chat 群组 ID。
mediaType
CallMediaType?
通话媒体类型。
注意：
在早期事件阶段、未知类型，或历史通话记录（recent calls）未完整回填该字段时可能为空（null / nil），业务需注意可选解包。
result
CallDirection
通话方向/记录类型（如呼入、呼出、未接）。
注意：
这不代表通话挂断的具体原因，结束原因请参考 CallEndReason 枚举。
startTime
TimeInterval
通话真正开始（接通）的时间戳。(单位：毫秒)。
duration
TimeInterval
通话时长（秒）。
CallState
通话状态数据，管理当前通话的实时数据状态。
属性
类型
说明
activeCall
CallInfo
当前活跃的通话信息。
【生命周期约定】：在触发 onCallEnded 时，该对象不会被立即置空，而是保留通话终态供 UI 展示结束动画（此时 CallInfo.result 或其它参数反映结束原因）。若业务重新发起或接到新通话，会自动覆盖。开发者可通过重置 CallStore 相关状态进行手动清理。
recentCalls
[CallInfo]
最近通话记录列表。
注意：
每次调用 queryRecentCalls 后，该状态当前表现为覆盖更新，而不是自动追加（Append）。如需实现无限滚动效果，业务层需自行将新到达的数据拼接到原有列表中。
cursor
String
分页游标，用于查询更多通话记录。
selfInfo
CallParticipantInfo
当前用户自身信息。
allParticipants
[CallParticipantInfo]
当前通话所有参与者列表。
speakerVolumes
[String: Int]
参与者音量信息，key 为用户 ID，value 为音量值。
networkQualities
[String: NetworkQuality]
参与者网络质量信息，key 为用户 ID，value 为网络质量。
使用示例
import AtomicXCore
// 发起视频通话
CallStore.shared.calls(participantIds: ["mike"], mediaType: .video, params: nil) { code, message in
}
﻿

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

函数名	描述
shared	获取 CallStore 单例实例。
callEventPublisher	通话事件发布者。
calls	发起通话。
accept	接听通话。
reject	拒绝通话。
hangup	挂断通话。
join	加入群组通话。
invite	邀请用户加入通话。
queryRecentCalls	查询最近通话记录。
deleteRecentCalls	删除通话记录。

参数名	类型	描述
participantIds	[String]	被呼叫者 ID 列表，支持单人或多人。
mediaType	CallMediaType	通话媒体类型（音频/视频）。
params	CallParams?	通话参数配置。

枚举值	值	说明
audio	1	音频通话。
video	2	视频通话。

枚举值	值	说明
unknown	0	未知原因。
hangup	1	正常挂断。
reject	2	拒绝接听。
noResponse	3	无响应。
offline	4	对方离线。
lineBusy	5	对方忙线。
canceled	6	通话被取消。
otherDeviceAccepted	7	其他设备已接听。
otherDeviceReject	8	其他设备已拒绝。
endByServer	9	后台结束通话。

枚举值	值	说明
none	0	无状态（未在通话中）。
waiting	1	等待中（呼叫中/被呼叫中）。
accept	2	已接听。

枚举值	值	说明
followConsoleConfig	0	跟随控制台的全局配置（默认）。
enable	1	开启云端录制，覆盖控制台配置。
disable	2	关闭云端录制，覆盖控制台配置。

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

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

CallStore

本页目录：

简介

功能特性

可订阅数据

API 列表

获取实例

shared

观察状态和事件

callEventPublisher

通话操作

calls

accept

reject

hangup

join

invite

通话记录

queryRecentCalls

deleteRecentCalls

数据结构

CallMediaType

CallEndReason

CallDirection

CallParticipantStatus

CloudRecordPolicy

CallEventListener

CallParams

CallParticipantInfo

CallInfo

CallState

使用示例