CallAPI 参考 | 声网文档中心

声网为 1v1 私密房解决方案提供 CallAPI，本文提供相应的 API 参考。

除了 CallAPI，你还需要使用 RTC API 来实现初始化等功能。你可以参考 RTC API 来了解详细的 RTC API 用法。

接口概述

CallAPI 是声网为 1v1 私密房解决方案提供的场景化 API，包含如下接口：

ICallApi，包含实现一对一私密互动的核心方法。
ICallApiListener，包含一对一私密互动的相关事件和状态回调。
ISignalClient，包含信令系统发送消息等基本操作。
ISignalClientListener，包含信令接收到消息的回调等操作。

注意

本文适用于 CallAPI 最新版本 v2.1.0，建议使用最新版本。

ICallApi

initialize

Kotlin

fun initialize(config: CallConfig)

初始化 CallAPI。

参数	类型	含义
`config`	`CallConfig`	初始化配置对象。详见 `CallConfig`。

deinitialize

释放 CallAPI 的缓存。

Kotlin

fun deinitialize(completion: (() -> Unit))

参数	类型	含义
`completion`	Closure	释放完成回调。

renewToken

更新 RTC 服务的 Token。

Kotlin

fun renewToken(rtcToken: String)

在收到 tokenPrivilegeWillExpire 回调后，你需要生成新的 Token，然后调用该方法将新的 Token 传给 SDK。

参数	类型	含义
`rtcToken`	String	RTC 服务 Token，详见使用 RTC Token 鉴权。

prepareForCall

准备通话环境。

Kotlin

fun prepareForCall(prepareConfig: PrepareConfig, completion: ((AGError?) -> Unit)?)

调用 prepareForCall 成功准备通话环境后，你才能调用 call 发起呼叫。该方法可以重复调用，用来更换通话的 RTC 频道。

该方法只有在通话状态不是 calling、connecting、connected 时才能调用。

注意

主叫发起呼叫后，被叫会获取到主叫在准备通话环境中设置的 roomId，从而加入对应的 RTC 频道进行通话。通话结束后，如果主叫不更新 roomId 就发起新的呼叫，可能会有一定的安全风险。

以用户 A、B、C 为例，主叫 A 向用户 B 发起呼叫后，B 就获取了 A 的 RTC 频道名（roomId）。呼叫结束后，如果 A 不更新 roomId 就向用户 C 发起呼叫，用户 B 可以通过技术手段使用之前的 roomId 和通配 Token 加入用户 A 的频道进行盗流。

因此为确保通话安全，我们建议在每次发起呼叫前，都调用 prepareForCall 方法更新 roomId，以保证每次通话使用不同的 RTC 频道，进而确保通话的私密性。

参数	类型	含义
`prepareConfig`	`PrepareConfig`	通话配置对象，详见 `PrepareConfig`。
`completion`	Closure	通话准备完成回调。

addListener

添加想要监听的事件回调。

Kotlin

fun addListener(listener: ICallApiListener)

参数	类型	含义
`listener`	`ICallApiListener`	需要添加监听的事件回调。详见 `ICallApiListener`。

removeListener

移除指定的回调事件。

Kotlin

fun removeListener(listener: ICallApiListener)

参数	类型	含义
`listener`	`ICallApiListener`	需要移除监听的事件回调。详见 `ICallApiListener`。

call[1/2]

发起视频通话。

Kotlin

fun call(remoteUserId: Int, completion: ((AGError?) -> Unit)?)

该方法由主叫调用，通过 prepareForCall 设置的 RTC 频道号，与远端用户建立 RTC 通话连接。

注意

该方法仅在通话状态为 prepared，即空闲时调用才生效。
成功发起通话后，只有当如下一种情况发生时，才能重新调用该方法发起通话：
- 主叫调用 cancelCall 或 hangup 取消或挂断当前通话。
- 被叫收到呼叫后调用 reject 拒绝接听通话。
为了保证通话安全性，建议每次呼叫前调用 prepareForCall 更新 roomId，并确保 PrepareConfig 中的其他属性均已设置。prepareForCall 会对 PrepareConfig 进行全量更新。

参数	类型	含义
`remoteUserId`	Int	呼叫目标用户的用户 ID。
`completion`	Closure	呼叫完成回调。

call[2/2]

发起视频或音频通话（v2.1.0 开始支持）。

Kotlin

fun call(remoteUserId: UInt, callType: CallType, callExtension: Map<String, Any>, completion: ((AGError?) -> Unit)?)

该方法由主叫调用，通过 prepareForCall 设置的 RTC 频道号，与远端用户建立 RTC 通话连接。

注意

该方法仅在通话状态为 prepared，即空闲时调用才生效。
成功发起通话后，只有当如下一种情况发生时，才能重新调用该方法发起通话：
- 主叫调用 cancelCall 或 hangup 取消或挂断当前通话。
- 被叫收到呼叫后调用 reject 拒绝接听通话。
为了保证通话安全性，建议每次呼叫前调用 prepareForCall 更新 roomId，并确保 PrepareConfig 中的其他属性均已设置。prepareForCall 会对 PrepareConfig 进行全量更新。

参数	类型	含义
`remoteUserId`	UInt	呼叫目标用户的用户 ID。
`callType`	CallType	呼叫类型，指定是视频呼叫还是音频呼叫。
`callExtension`	Map<String, Any>	呼叫时想要传递的自定义参数。
`completion`	Closure	呼叫完成回调。

cancelCall

取消正在发起的通话。

Kotlin

fun cancelCall(completion: ((AGError?) -> Unit)?)

该方法由主叫调用。

参数	类型	含义
`completion`	Closure	取消完成回调。

accept

接受呼叫邀请。

Kotlin

fun accept(remoteUserId: Int, completion: ((AGError?) -> Unit)?)

该方法由被叫调用。

参数	类型	含义
`remoteUserId`	Int	呼叫目标用户的用户 ID。
`completion`	Closure	接受完成回调。

reject

拒绝呼叫邀请。

Kotlin

fun reject(remoteUserId: Int, reason: String?, completion: ((AGError?) -> Unit)?)

该方法由被叫调用。拒绝后被叫的通话状态变更为 prepared。

参数	类型	含义
`remoteUserId`	Int	呼叫目标用户的用户 ID。
`reason`	String	（选填）拒绝原因。
`completion`	Closure	拒绝完成回调。

hangup

挂断通话。

Kotlin

fun hangup(remoteUserId: Int, reason: String?, completion: ((AGError?) -> Unit)?)

该方法主叫和被叫均可调用。挂断后主叫和被叫的通话状态变更为 prepared。

参数	类型	含义
`remoteUserId`	Int	呼叫目标用户的用户 ID。
`reason`	String	（选填）挂断原因。
`completion`	Closure	挂断完成回调。

getCallId

获取当前通话的通话 ID。

Kotlin

fun getCallId(): String

通话 ID，即 callId，为当次通话过程中唯一标识。通过该标识，声网后台服务可以查询到当前通话的关键节点耗时，以及状态变迁的时间节点。

返回值

一个字符串类型的调用标识符。

ICallApiListener

onCallStateChanged

状态响应回调。

Kotlin

fun onCallStateChanged(state: CallStateType,
                        stateReason: CallStateReason,
                        eventReason: String,
                        eventInfo: Map<String, Any>)

参数	类型	含义
`state`	CallStateType	状态类型。详见 `CallStateType`。
`stateReason`	CallStateReason	状态变更的原因。详见`CallStateReason`。
`eventReason`	String	事件类型描述。
`eventInfo`	Map<String, Any>	扩展信息，不同事件类型参数不同。

onCallEventChanged

内部详细事件变更回调。

Kotlin

fun onCallEventChanged(event: CallEvent, eventReason: String?) {}

该回调为可选。你可以根据实际业务场景选择是否监听。

参数	类型	含义
`event`	CallEvent	状态类型。详见 `CallEvent`。
`eventReason`	String	事件原因。该参数默认为 `null`。只有当报告特定 `CallEvent` 时，才会有具体含义。例如，`event` 为 `108` 时，你可以通过这个枚举的描述来查看具体的含义。

onCallError

发生错误回调。

Kotlin

fun onCallError(errorEvent: CallErrorEvent,
                        errorType: CallErrorCodeType,
                        errorCode: Int,
                        message: String?) {}

该回调为可选。你可以根据实际业务场景选择是否监听。

参数	类型	含义
`errorEvent`	CallErrorEvent	错误事件。详见 `CallErrorEvent`。
`errorType`	CallErrorCodeType	错误码类型。详见 `CallErrorCodeType`。
`errorCode`	Int	错误码。
`message`	String	错误信息。

onCallConnected

通话开始的回调。

Kotlin

fun onCallConnected(roomId: String,
                    callUserId: Int,
                    currentUserId: Int,
                    timestamp: Long) {}

该回调为可选。你可以根据实际业务场景选择是否监听。

参数	类型	含义
`roomId`	String	通话的频道 ID。
`callUserId`	Int	发起呼叫的用户 ID。
`currentUserId`	Int	当前的用户 ID。
`timestamp`	Long	通话开始的时间戳，指从格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒（北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒）起至现在的总毫秒数。

onCallDisconnected

通话结束的回调。

Kotlin

fun onCallDisconnected(roomId: String,
                       hangupUserId: Int,
                       currentUserId: Int,
                       timestamp: Long,
                       duration: Long) {}

该回调为可选。你可以根据实际业务场景选择是否监听。

参数	类型	含义
`roomId`	String	通话的频道 ID。
`hangupUserId`	Int	挂断的用户 ID。
`currentUserId`	Int	当前的用户 ID。
`timestamp`	Long	通话开始的时间戳，指从格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒（北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒）起至现在的总毫秒数，单位为 `ms`。
`duration`	Long	通话时长，单位为毫秒。

canJoinRtcOnCalling

设置当收到远端呼叫时是否可以直接加入 RTC 频道。

Kotlin

fun canJoinRtcOnCalling(eventInfo: Map<String, Any>) : Boolean?

该回调为可选。你可以根据实际业务场景选择是否监听。你需要通过该回调的返回值设置收到呼叫时是否可以直接加入 RTC 频道。

参数	类型	含义
`eventInfo`	[String: Any]	收到呼叫时远端传递过来的扩展信息

返回值

true：收到呼叫立即加入 RTC 频道并推送视频流。
false：收到呼叫后，需要用户点击接受才加入 RTC 频道并推送视频流。

tokenPrivilegeWillExpire

RTC Token 即将要过期。

Kotlin

fun tokenPrivilegeWillExpire()

收到该回调后，你需要重新获取 RTC 服务的 Token，然后调用 renewToken 将新的 Token 发送给 SDK。

信息

如果你的信令 Token 与 RTC Token 过期时间一致，收到该回调即意味着信令 Token 也已过期。收到该回调后，你可以同步生成并更新信令 Token。例如，如果你使用的是声网的 RTM SDK 实现的信令通道，则可以重新生成 RTM Token，然后调用 AgoraRtmClientKit.revewToken 方法更新信令 Token。

该回调为可选。你可以根据实际业务场景选择是否监听。

callDebugInfo

日志已打印。

Kotlin

fun callDebugInfo(message: String, logLevel: CallLogLevel) {}

参数	类型	含义
`message`	String	日志信息。
`logLevel`	CallLogLevel	日志等级，详见 `CallLogLevel`。

ISignalClient

sendMessage

CallAPI 通过该方法使用信令系统向指定用户发送消息。

Kotlin

fun sendMessage(userId: String, message: String, completion: ((AGError?)-> Unit)?)

参数	类型	含义
`userId`	String	目标用户 ID。
`message`	String	消息对象。
`completion`	Closure	发送完成回调。

addListener

向信令系统添加一个信令监听器。

Kotlin

fun addListener(listener: ISignalClientListener)

参数	类型	含义
`listener`	ISignalClientListener	信令监听器，用于处理消息接收和日志记录。

removeListener

从信令系统移除指定的信令监听器。

Kotlin

fun removeListener(listener: ISignalClientListener)

参数	类型	含义
`listener`	ISignalClientListener	待移除的信令监听器。

ISignalClientListener

onMessageReceive

收到消息的回调。

Kotlin

fun onMessageReceive(message: String)

参数	类型	含义
`message`	String	收到的消息内容。

debugInfo

信令日志回调。

Kotlin

fun debugInfo(message: String, logLevel: Int)

参数	类型	含义
`message`	String	日志消息内容。
`logLevel`	Int	日志等级： `0`：正常日志 `1`：告警日志 `2`：错误日志

该回调为可选。你可以根据实际业务场景选择是否监听。

类型定义

CallConfig

初始化配置对象，在 initialize 中设置。

Kotlin

open class CallConfig(
    var appId: String = "",
    var userId: Int = 0,
    var rtcEngine: RtcEngineEx,
    var signalClient: ISignalClient,
){}

参数	类型	含义
`appId`	String	声网 App ID。
`userId`	Int	用户 ID。
`rtcEngine`	RtcEngineEx	RTC Engine 实例。
`signalClient`	ISignalClient	信令通道对象实例。注意请在该信令对象内自行维护信令的登录状态。

PrepareConfig

通话配置对象，在 prepareForCall 中设置。

Kotlin

open class PrepareConfig(
    var roomId: String = "",
    var rtcToken: String = "",
    var localView: ViewGroup? = null,
    var remoteView: ViewGroup? = null,
    var autoJoinRTC: Boolean = false,
    var callTimeoutMillisecond: Long = 15000L,
    var userExtension: Map<String, Any>? = null
) {}

参数	类型	含义
`roomId`	String	RTC 频道名，用于呼叫对端用户时让对端用户进入加入这个 RTC 频道。
`rtcToken`	String	RTC Token。注意你需要使用通配频道名的 Token，即在生成 Token 时将 `channelName` 设为通配符或空字符串。详见使用通配 Token。请确保生成通配 Token 时填的 `uid` 和 `initialize` 中的 `userId` 一致。
`localView`	ViewGroup	显示本地流的画布。
`remoteView`	ViewGroup	显示远端流的画布。
`autoJoinRTC`	Bool	是否在不呼叫的情况下提前加入 RTC 频道，该设置可以加快呼叫的出图速度。已删除不再支持提前加入频道。
`callTimeoutMillisecond`	Long	呼叫超时时间，单位为毫秒，`0` 表示内部不处理超时。
`userExtension`	Map<String, Any>	（可选）用户扩展字段，收到对端消息而改变状态（如 `calling`/`connecting`）时，可以通过 `"fromUserExtension"` 字段获取。

CallType

发起通话的类型

枚举名	枚举值	描述
`Video`	`0`	视频呼叫。
`Audio`	`1`	音频呼叫。

CallStateType

通话状态枚举，在 onCallStateChanged 回调中报告。

枚举名	枚举值	描述
`Idle`	`0`	未准备好通话状态。如果想要发起通话，需要先通过 `prepareForCall` 准备通话环境。
`Prepared`	`1`	空闲，表示可以进行通话。调用 `prepareForCall`、`cancelCall`、`reject` 或 `hangup` 方法后会进入该状态。
`Calling`	`2`	呼叫中，表示发起了呼叫，或者收到对端用户呼叫。
`Connecting`	`3`	连接中，表示在呼叫中发起了接受（`accept`）或者收到对端用户接受呼叫。
`Connected`	`4`	通话中，表示通话已经建立成功，可以看到对方视频画面。
`Failed`	`10`	出现错误。导致出错的原因是 RTM 服务断线过长时间，或者初始化环境 `prepareForCall` 失败。

CallStateReason

导致状态变更的原因，在 onCallStateChanged 回调中报告。

枚举名	枚举值	描述
`None`	`0`	无。
`JoinRTCFailed`	`1`	加入 RTC 频道失败。
`RtmSetupFailed`	`2`	已删除当前如果 `prepareForCall` 失败，会报告 `None`。
`RtmSetupSuccessed`	`3`	已删除你需要自行维护信令登录的状态。
`MessageFailed`	`4`	消息发送失败。
`LocalRejected`	`5`	本地用户拒绝了呼叫邀请。
`RemoteRejected`	`6`	远端用户拒绝了呼叫邀请。
`RemoteAccepted`	`7`	远端用户接受了呼叫邀请。
`LocalAccepted`	`8`	本地用户接受了呼叫邀请。
`LocalHangup`	`9`	本地用户挂断。
`RemoteHangup`	`10`	远端用户挂断。
`LocalCancelled`	`11`	本地用户取消呼叫。
`RemoteCancelled`	`12`	远端用户取消呼叫。
`RecvRemoteFirstFrame`	`13`	收到远端视频首帧。
`CallingTimeout`	`14`	呼叫超时。
`CancelByCallerRecall`	`15`	同样的主叫呼叫不同频道导致取消。
`RtmLost`	`16`	已删除你可以通过信令管理的实现处理相关的异常。
`RemoteCallBusy`	`17`	远端用户忙。
`RemoteCallingTimeout`	`18`	远端呼叫超时。
`LocalVideoCall`	`30`	本地发起视频呼叫（v2.1.0 开始支持）。
`LocalAudioCall`	`31`	本地发起音频呼叫（v2.1.0 开始支持）。
`RemoteVideoCall`	`32`	远端发起视频呼叫（v2.1.0 开始支持）。
`RemoteAudioCall`	`33`	远端发起音频呼叫（v2.1.0 开始支持）。

CallEvent

详细事件，在 onCallEventChanged 回调中报告。

枚举名	枚举值	描述
`None`	`0`	无。
`Deinitialize`	`1`	调用了 `deinitialize`。
`CallingTimeout`	`3`	呼叫超时。
`JoinRTCSuccessed`	`5`	加入 RTC 频道成功。
`RtmSetupSuccessed`	`7`	已删除你需要自行维护信令设置的状态。
`StateMismatch`	`9`	状态流转异常。
`JoinRTCStart`	`10`	本地已经加入 RTC 频道，但是还未成功（调用了 `joinChannelEx`，但由于延迟还未收到成功回调）。v2.1.0 开始支持。
`RemoteUserRecvCall`	`99`	主叫呼叫成功。
`LocalRejected`	`100`	本地用户拒绝呼叫邀请。
`RemoteRejected`	`101`	远端用户拒绝呼叫邀请。
`OnCalling`	`102`	变成呼叫中。已删除对应事件变更为：`LocalVideoCall`/`LocalAudioCall`/`RemoteVideoCall`/`RemoteAudioCall`
`RemoteAccepted`	`103`	远端用户接收呼叫邀请。
`LocalAccepted`	`104`	本地用户接收呼叫邀请。
`LocalHangup`	`105`	本地用户挂断。
`RemoteHangup`	`106`	远端用户挂断。
`RemoteJoined`	`107`	远端用户加入 RTC 频道。
`RemoteLeft`	`108`	远端用户离开 RTC 频道。`eventReason` 可以参考 `onUserOffline`。
`LocalCancelled`	`109`	本地用户取消呼叫。
`RemoteCancelled`	`110`	远端用户取消呼叫。
`LocalJoined`	`111`	本地用户加入 RTC 频道。
`LocalLeft`	`112`	本地用户离开 RTC 频道。
`RecvRemoteFirstFrame`	`113`	收到远端视频首帧。
`CancelByCallerRecall`	`114`	同样的主叫呼叫不同频道导致取消。
`RtmLost`	`115`	已删除 CallAPI v2.1 升级了 RTM SDK 至 v2.2 后，不再需要考虑该事件。
`RtcOccurError`	`116`	RTC 出现错误。
`RemoteCallBusy`	`117`	远端用户忙。
`CaptureFirstLocalVideoFrame`	`119`	采集到首帧视频帧。
`PublishFirstLocalVideoFrame`	`120`	视频首帧推送成功。
`PublishFirstLocalAudioFrame`	`130`	音频首帧推送成功（v2.1.0 开始支持）。
`LocalVideoCall`	`140`	本地发起视频呼叫（v2.1.0 开始支持）。
`LocalAudioCall`	`141`	本地发起音频呼叫（v2.1.0 开始支持）。
`RemoteVideoCall`	`142`	远端发起视频呼叫（v2.1.0 开始支持）。
`RemoteAudioCall`	`143`	远端发起音频呼叫（v2.1.0 开始支持）。

CallErrorEvent

呼叫错误事件。在 onCallError 回调中报告。

枚举名	枚举值	描述
`NormalError`	`0`	通用错误。
`RtcOccurError`	`100`	RTC 服务出现错误。
`StartCaptureFail`	`110`	RTC 开启采集失败。
`RtmSetupFail`	`200`	已删除你需要自行维护信令的状态。
`SendMessageFail`	`210`	消息发送失败。

CallErrorCodeType

呼叫错误事件的错误码类型。在 onCallError 回调中报告。

枚举名	枚举值	描述
`Normal`	`0`	业务类型的错误，暂无。
`Rtc`	`100`	RTC 服务错误，你可以搭配 `onCallError` 中反馈的 `errorCode` 查看 RTC 错误码文档了解报错原因和解决办法。
`Rtm`	`110`	信令服务的消息错误。使用如果的默认的信令通道（声网 RTM），可以使用 `AgoraRtmErrorCode` 查看报错信息；如果是自定义信令（如环信），则可以参考对应信令服务的错误信息。

CallLogLevel

日志等级，在 callDebugInfo 回调中报告。

枚举名	枚举值	描述
`Normal`	`0`	正常日志。
`Warning`	`1`	告警日志。
`Error`	`2`	错误日志（暂无）。

接口概述Copy Anchor Link

ICallApiCopy Anchor Link

initializeCopy Anchor Link

deinitializeCopy Anchor Link

renewTokenCopy Anchor Link

prepareForCallCopy Anchor Link

addListenerCopy Anchor Link

removeListenerCopy Anchor Link

call[1/2]Copy Anchor Link

call[2/2]Copy Anchor Link

cancelCallCopy Anchor Link

acceptCopy Anchor Link

rejectCopy Anchor Link

hangupCopy Anchor Link

getCallIdCopy Anchor Link

返回值Copy Anchor Link

ICallApiListenerCopy Anchor Link

onCallStateChangedCopy Anchor Link

onCallEventChangedCopy Anchor Link

onCallErrorCopy Anchor Link

onCallConnectedCopy Anchor Link

onCallDisconnectedCopy Anchor Link

canJoinRtcOnCallingCopy Anchor Link

返回值Copy Anchor Link

tokenPrivilegeWillExpireCopy Anchor Link

callDebugInfoCopy Anchor Link

ISignalClientCopy Anchor Link

sendMessageCopy Anchor Link

addListenerCopy Anchor Link

removeListenerCopy Anchor Link

ISignalClientListenerCopy Anchor Link

onMessageReceiveCopy Anchor Link

debugInfoCopy Anchor Link

类型定义Copy Anchor Link

CallConfigCopy Anchor Link

PrepareConfigCopy Anchor Link

CallTypeCopy Anchor Link

CallStateTypeCopy Anchor Link

CallStateReasonCopy Anchor Link

CallEventCopy Anchor Link

CallErrorEventCopy Anchor Link

CallErrorCodeTypeCopy Anchor Link

CallLogLevelCopy Anchor Link

咨询电话

咨询电话

接口概述

ICallApi

initialize

deinitialize

renewToken

prepareForCall

addListener

removeListener

call[1/2]

call[2/2]

cancelCall

accept

reject

hangup

getCallId

返回值

ICallApiListener

onCallStateChanged

onCallEventChanged

onCallError

onCallConnected

onCallDisconnected

canJoinRtcOnCalling

返回值

tokenPrivilegeWillExpire

callDebugInfo

ISignalClient

sendMessage

addListener

removeListener

ISignalClientListener

onMessageReceive

debugInfo

类型定义

CallConfig

PrepareConfig

CallType

CallStateType

CallStateReason

CallEvent

CallErrorEvent

CallErrorCodeType

CallLogLevel