BeeWorks IM SDK Docs
v1
文档/Android SDK/开发指南

即时通话 ​

即时通话通过 BimRtcManager.callService 创建或加入。通话建立后，开发者通过 BimCallSession 控制本地媒体和参与者，通过 BimCallListener 观察来电、状态变化和错误。

适用场景 ​

BimCallTarget 支持三种目标：

目标用途标识
user单聊通话一个用户 ID
discussion群组通话一个群组 ID，可额外指定邀请人
adHoc临时多人通话用户 ID 列表
kotlin
val oneToOne = BimCallTarget.user("u10002")
val group = BimCallTarget.discussion("discussion-001")
val temporary = BimCallTarget.adHoc(listOf("u10002", "u10003"))

目标 ID 会被 SDK 清理空白字符；目标不能使用空 ID。临时多人通话的用户列表会去重，当前登录用户不需要重复放入目标列表。

发起通话 ​

kotlin
val rtc = BimRtcManager.getInstance()
val session = rtc.callService.startCall(
    BimCallStartOptions(
        target = BimCallTarget.user("u10002"),
        mediaType = BimRtcMediaType.VIDEO,
        timeoutSeconds = 30,
        subject = "项目沟通",
        customData = "业务自定义标识",
        initialMicrophoneMuted = false,
        initialCameraEnabled = true,
        preferredAudioOutput = BimRtcAudioOutput.SPEAKER,
    ),
)

BimCallStartOptions 的主要字段：

字段说明
target用户、群组或临时多人目标
mediaTypeAUDIO 或 VIDEO
inviteeUserIds群组或临时多人场景的额外邀请人
timeoutSeconds呼叫等待超时时间，默认 30 秒
subject可选通话主题
customData可选业务扩展数据
initialMicrophoneMuted是否以静音状态进入
initialCameraEnabled是否打开摄像头
preferredAudioOutput初始音频输出设备

发起通话前必须完成核心 IM 登录和 RTC 初始化。失败时 suspend API 抛出 BimRtcError，不会返回一个可继续使用的半初始化会话。

加入来电 ​

当收到来电时，开发者通过 BimCallListener.onCallReceived 获得 BimCallSession。接受或拒绝来电：

kotlin
class CallListener : BimCallListener {
    override fun onCallReceived(session: BimCallSession) {
        lifecycleScope.launch {
            session.accept()
        }
    }

    override fun onCallError(session: BimCallSession?, error: BimRtcError) {
        println("call failed: ${error.code}, ${error.message}")
    }
}

rtc.addCallListener(CallListener())

如果宿主已经通过业务路由拿到 callId，也可以主动加入：

kotlin
val session = rtc.callService.joinCall(callId)

同一时间只能存在一个活动通话。重复创建或加入会话时，SDK 会返回 ALREADY_ACTIVE 或相应的状态错误。

通话状态 ​

通过 BimCallListener.onCallSession 观察完整快照：

kotlin
override fun onCallSession(session: BimCallSession, snapshot: BimCallSnapshot) {
    when (snapshot.state) {
        BimCallState.PREPARING -> showPreparing()
        BimCallState.OUTGOING_RINGING -> showOutgoingRinging()
        BimCallState.INCOMING_RINGING -> showIncomingRinging()
        BimCallState.CONNECTING -> showConnecting()
        BimCallState.CONNECTED -> showInCall(snapshot)
        BimCallState.RECONNECTING -> showReconnecting()
        BimCallState.ENDING, BimCallState.ENDED -> showEnded(snapshot.endReason)
    }
}

BimCallSnapshot 包含：

  • callId、可选 meetingNumber、revision。
  • target、mediaType、role、callerUserId 和 organizerUserId。
  • inviteeUserIds 与 participants。
  • localMediaState，包括麦克风、摄像头、音频输出、摄像头方向和屏幕共享状态。
  • createdAt、connectedAt、endedAt。
  • endReason、结束操作者和终态错误。

会话控制 ​

kotlin
session.accept()
session.reject()
session.hangup()
session.invite(listOf("u10003"))
session.transferOrganizer("u10003")
session.setMicrophoneMuted(true)
session.setCameraEnabled(false)
session.switchCamera()
session.setAudioOutput(BimRtcAudioOutput.BLUETOOTH)
session.setScreenSharing(true)

视频或屏幕共享需要宿主先完成相应的系统权限和设备能力检查。控制操作失败时抛出 BimRtcError，宿主应根据当前快照重新渲染按钮状态。

渲染媒体画面 ​

RTC 会话提供渲染容器绑定：

kotlin
session.attachRenderView(remoteVideoContainer)

// 页面离开或会话结束时
session.detachRenderView()

宿主负责准备 ViewGroup 的页面布局和销毁时机。不要直接获取或操作 RTC 内部媒体对象。

监听器注册 ​

kotlin
val listener = object : BimCallListener {
    override fun onCallReceived(session: BimCallSession) = Unit

    override fun onCallSession(session: BimCallSession, snapshot: BimCallSnapshot) {
        // 更新通话 UI
    }

    override fun onCallError(session: BimCallSession?, error: BimRtcError) {
        // 显示错误或结束页面
    }
}

rtc.addCallListener(listener)
// 功能模块销毁时移除
rtc.removeCallListener(listener)

也可以只在当前会话上监听：

kotlin
session.addListener(listener)
session.removeListener(listener)

监听回调使用 BimRtcConfig.callbackExecutor 配置的 executor；未配置时使用 RTC 默认派发线程。监听器移除后，宿主不应继续持有页面引用。

UI 委托与默认页面 ​

如果宿主需要完全控制来电和去电页面，可以通过 BimRtcUiDelegate 接管：

kotlin
val config = BimRtcConfig(
    uiDelegate = object : BimRtcUiDelegate {
        override fun showIncomingCall(session: BimCallSession): Boolean {
            // 展示宿主来电 UI；已接管时返回 true
            return true
        }

        override fun showOutgoingCall(session: BimCallSession): Boolean {
            return true
        }
    },
)
BimRtcManager.getInstance().init(applicationContext, config)

返回 false 时由 RTC 使用默认的通话页面处理。无论使用哪种方式，最终的权限申请、页面样式和业务路由都属于宿主职责。

结束原因与错误 ​

BimCallEndReason 用于区分正常挂断、拒绝、超时、网络断开、账号变化、其他设备接听等终态。常见 BimRtcError：

错误含义
NOT_INITIALIZEDRTC 尚未初始化
NOT_LOGGED_IN核心 IM 没有有效登录态
ALREADY_ACTIVE已存在活动通话或会议
CALL_NOT_FOUND找不到通话
CALL_EXPIRED通话已过期
PERMISSION_DENIED宿主未授予所需权限
MEDIA_UNAVAILABLE媒体能力不可用
JOIN_ROOM_FAILED加入媒体房间失败
NETWORK_UNAVAILABLE网络不可用

通话状态进入 ENDED 后，不要继续调用会话控制方法；应移除渲染视图和会话监听，等待下一次新的通话。

IM SDK代码示例 ↗