物联网开发平台应用端接入

本文介绍腾讯云物联网（IoT）应用端 SDK 中视频通话（TXIoTCallSession）相关 API 的使用方法。完成 快速接入 并登录 SDK 后，您可以通过本文实现设备与 App 之间的实时音视频通话。
前提条件
已集成 IoT 应用端 SDK 并完成初始化。
已调用 TXIoTEngine.login 登录，且登录未过期。
目标设备已绑定到当前登录账户名下（详见 设备管理）。未绑定的设备没有通话权限，相关接口会返回权限相关错误。
注意：
呼叫方向限制：本套视频通话接口仅支持应用端主动呼叫设备端，应用端只能发起通话（callDevice），不能接听来电。
通话优先级：视频通话的优先级高于实时监控，若设备当前正处于实时监控拉流状态，应用端发起视频通话会打断该设备的实时监控（详见 实时监控），设备会切换到视频通话状态。
使用建议
发起通话前先完成设备绑定与登录，并检查设备在线状态。
在调用 callDevice 前注册监听，避免漏掉 onCallBegin 与错误回调。
视频通话务必设置本地预览视图与远端渲染视图，且确保视图可见。
通话结束后及时调用 hangup、停止远端视图并移除监听，释放摄像头与麦克风等资源。
摄像头/麦克风需在 Info.plist（iOS）或 AndroidManifest（Android）中声明并动态申请权限。
获取通话会话对象
视频通话通过 TXIoTCallSession 对象进行。该对象由 TXIoTEngine 管理，无需手动创建，直接通过引擎获取即可：
Android：TXIoTEngine.getInstance(context).getCallSession()
iOS：[TXIoTEngine getInstance] getCallSession
若返回 null（Android）或 nil（iOS），通常表示当前未登录或登录已过期，请先调用 TXIoTEngine.login 登录成功后再获取。建议在每次发起通话前重新获取，避免因会话失效导致调用失败。
警告：
视频通话对象为单例，同一时刻只存在一个视频通话。若已有视频通话正在进行（已调用 callDevice 且尚未 hangup），再次调用 callDevice 会被直接忽略，不会打断或切换已有视频通话；无需也不能重复获取多个会话实例。
设置通话监听
在发起通话前，请先注册通话监听器，用于接收通话开始/结束、对方状态变化、网络质量、错误等回调。通话结束或页面销毁时记得移除监听，避免内存泄漏。
方法
说明
﻿addListener﻿
添加通话状态与错误的监听器，回调接口定义见 通话事件回调（iOS 方法名为 addDelegate）。
﻿removeListener﻿
移除已注册的监听（iOS 方法名为 removeDelegate）。
Android
iOS
TXIoTCallSession callSession = TXIoTEngine.getInstance(context).getCallSession();
if (callSession == null) {
    // 未登录或登录过期，请先登录。
    return;
}
callSession.addListener(new TXIoTCallListener() {
    @Override
    public void onError(TXIoTErrorCode code, String msg) {
        // 通话发生错误。
    }
﻿
    @Override
    public void onCallBegin(TXIoTCallMediaType mediaType) {
        // 通话开始。
    }
﻿
    @Override
    public void onCallEnd(TXIoTCallMediaType mediaType, TXIoTCallEndReason reason) {
        // 通话结束。
    }
    // 其余回调省略，详见“通话状态与回调通知”。
});
TXIoTCallSession *callSession = [[TXIoTEngine getInstance] getCallSession];
if (callSession == nil) {
    // 未登录或登录过期，请先登录。
    return;
}
[callSession addDelegate:self];
// 在 delegate 对象中实现 TXIoTCallDelegate 协议方法：
// - (void)onError:(TXIoTErrorCode)errorCode errorMessage:(NSString *)errorMessage;
// - (void)onCallBegin:(TXIoTCallMediaType)mediaType;
// - (void)onCallEnd:(TXIoTCallMediaType)mediaType reason:(TXIoTCallEndReason)reason;
// 其余回调省略，详见“通话状态与回调通知”。
注意：
请在发起通话（callDevice）之前完成监听注册；否则可能漏掉 onCallBegin、onError 等关键回调。
发起与结束通话
调用 callDevice 向指定设备发起音视频通话，需传入目标设备的 TXIoTDeviceId 与通话类型（TXIoTCallMediaType）。通话过程中调用 hangup 结束通话。
方法
说明
﻿callDevice﻿
向 deviceId（TXIoTDeviceId）指定的设备发起通话，callType（TXIoTCallMediaType）为通话类型。
﻿hangup﻿
挂断并结束当前通话。
Android
iOS
// 通过 TXIoTDeviceManager.getDeviceList、TXIoTDeviceManager.getDeviceListSharedWithMe
// 获取有权限通话的设备列表
TXIoTDeviceId deviceId = ...;
callSession.callDevice(deviceId, TXIoTCallMediaType.VIDEO);
// 通过 TXIoTDeviceManager.getDeviceList、TXIoTDeviceManager.getDeviceListSharedWithMe
// 获取有权限通话的设备列表
TXIoTDeviceId *deviceId = ...;
[callSession callDevice:deviceId callType:TXIoTCallMediaTypeVideo];
调用 callDevice 向设备发起通话后，可能出现以下结果，对应不同回调：
设备接听本次通话 → onCallAccepted，随后媒体就绪 → onCallBegin。
设备拒绝接听 → onCallRejected。
设备在 30 秒内未接听 → onCallNoResponse。
本地摄像头/麦克风未授权，通话无法建立 → 结束原因 CALL_PERMISSION_DENIED，回调 onCallEnd。
远端挂断  → onCallEnd（原因对应 REMOTE_HANGUP）。
网络异常、设备离线等 → onCallEnd（原因对应 NETWORK_ERROR 等）或 onCallUserOffline。
若呼叫时设备已经在与另一个应用端账号在通话中，此时本账号再向同一台设备发送呼叫请求，设备侧也会收到本账号的呼叫请求。设备侧可以决定是拒绝后发的呼叫请求，还是结束正在进行的通话并接受本账号的呼叫请求。
结束通话时，应用端调用 hangup，本机会收到 onCallEnd 收到结束通知（原因为 LOCAL_HANGUP）。
Android
iOS
callSession.hangup();
[callSession hangup];
设置渲染视图
视频通话需要本地预览与远端画面两类渲染视图：
本地预览：openCamera(cameraId, videoView) 开启摄像头并指定预览视图。
远端画面：startRemoteView(callUser, videoView) 开始渲染指定对端的视频，stopRemoteView(callUser) 停止渲染指定对端的视频。
方法
说明
﻿openCamera﻿
开启并预览指定摄像头。
cameraId 为枚举类型 TXIoTCamera（前置/后置摄像头）。
videoView 为渲染视图（Android 为 TXCloudVideoView，iOS 为 UIView）。
﻿startRemoteView﻿
渲染对端画面。
callUser 为 TXIoTCallUser 类型。
videoView 为渲染视图（Android 为 TXCloudVideoView，iOS 为 UIView）。
﻿stopRemoteView﻿
停止渲染指定对端画面。
callUser 为 TXIoTCallUser 类型。
Android
iOS
// 本地预览（传入 TXCloudVideoView）
callSession.openCamera(TXIoTCamera.FRONT, localView);
// 远端渲染
callSession.startRemoteView(callUser, remoteView);
// 停止远端渲染
callSession.stopRemoteView(callUser);
// 本地预览（传入 UIView）
[callSession openCamera:TXIoTCameraFront view:localView];
// 远端渲染
[callSession startRemoteView:callUser view:remoteView];
// 停止远端渲染
[callSession stopRemoteView:callUser];
开关摄像头与切换
通过以下方法控制本地摄像头：开启、关闭、切换前后摄像头。
方法
说明
﻿openCamera﻿
开启并预览指定摄像头，参数 cameraId 为 TXIoTCamera 类型。
﻿closeCamera﻿
关闭本地摄像头。
﻿switchCamera﻿
切换前后摄像头，参数 cameraId 为 TXIoTCamera 类型。
Android
iOS
callSession.openCamera(TXIoTCamera.BACK, localView);
callSession.switchCamera(TXIoTCamera.FRONT);
callSession.closeCamera();
[callSession openCamera:TXIoTCameraBack view:localView];
[callSession switchCamera:TXIoTCameraFront];
[callSession closeCamera];
开关麦克风与切换
控制本地麦克风采集的开启与关闭，并选择通话音频的播放设备（听筒或扬声器）。
方法
说明
﻿openMicrophone﻿
开启本地麦克风采集、传输。
﻿closeMicrophone﻿
关闭本地麦克风采集、传输。
﻿selectAudioPlaybackDevice﻿
选择通话音频的播放设备，device 为 TXIoTAudioPlaybackDevice（听筒或扬声器）类型。
Android
iOS
callSession.openMicrophone();
callSession.closeMicrophone();
callSession.selectAudioPlaybackDevice(TXIoTAudioPlaybackDevice.SPEAKER_PHONE);
[callSession openMicrophone];
[callSession closeMicrophone];
[callSession selectAudioPlaybackDevice:TXIoTAudioPlaybackDeviceSpeakerphone];
通话状态与回调通知
通过 TXIoTCallListener（iOS 为 TXIoTCallDelegate）监听通话全生命周期事件。注册方式见 设置通话监听。下方表格列出各回调的含义与触发时机：
回调
触发时机 / 说明
onError
通话发生错误时回调错误码与信息（如摄像头/麦克风权限被拒、设备离线、网络异常等）。
onCallBegin
通话建立。
onCallAccepted
设备接听本次通话。
onCallEnd
通话结束。参数中带结束原因（如 LOCAL_HANGUP、REMOTE_HANGUP、CALL_PERMISSION_DENIED、NETWORK_ERROR 等）。
onCallRejected
设备拒绝接听本次通话。
onCallNoResponse
设备在 30 秒内未接听，通话超时。
onCallUserOffline
对端设备通话过程中离线。
onCallUserAudioAvailable
对方音频可用状态变化。
onCallUserVideoAvailable
对方视频可用状态变化。
onCallNetworkQualityChanged
本地与远端网络质量变化。
错误处理
所有异步通话操作通过监听器 onError 返回错误，下面是通话场景可能回调的错误码表，完整错误码定义见 TXIoTErrorCode。
Android
iOS
错误码
说明
建议处理方式
ERR_SUCCESS
成功。
无需处理（调用成功）。
ERR_FAILED
通用失败。
结合 onError 返回的 errMsg 排查具体失败原因。
ERR_INVALID_PARAMETER
参数不合法。
检查 deviceId、callType 等参数是否为空或格式错误。
ERR_INVALID_ACCESS_TOKEN
登录凭证无效。
重新登录 SDK 后再发起通话。
ERR_RATE_LIMITED
请求被限频。
降低调用频率后重试。
ERR_UNAUTHORIZED_OPERATION
当前用户无权限（常见于设备未绑定）。
确认目标设备已绑定到当前账户（见 前提条件）。
ERR_DEVICE_NOT_EXIST
设备不存在。
确认 deviceId 是否正确、设备是否已绑定。
ERR_DEVICE_OFFLINE
设备离线。
确认设备在线后重试。
ERR_CAMERA_START_FAIL
摄像头启动失败。
检查摄像头是否被占用或硬件异常。
ERR_CAMERA_NOT_AUTHORIZED
摄像头无权限。
在工程中申请并获取摄像头权限。
ERR_CAMERA_OCCUPY
摄像头被占用。
停止其他占用摄像头的功能后再试。
ERR_MIC_START_FAIL
麦克风启动失败。
检查麦克风是否被占用或硬件异常。
ERR_MIC_NOT_AUTHORIZED
麦克风无权限。
在工程中申请并获取麦克风权限。
ERR_MIC_OCCUPY
麦克风被占用。
停止其他占用麦克风的功能后再试。
ERR_SPEAKER_START_FAIL
扬声器启动失败。
检查音频输出设备是否正常。
错误码
数值
说明
建议处理方式
TXIoTErrorCodeSuccess
0
成功
无需处理（调用成功）。
TXIoTErrorCodeFailed
-1
通用失败
结合 onError 返回的 errMsg 排查具体失败原因。
TXIoTErrorCodeInvalidParameter
-2
参数不合法
检查 deviceId、callType 等参数是否为空或格式错误。
TXIoTErrorCodeInvalidAccessToken
-3
登录凭证无效
重新登录 SDK 后再发起通话。
TXIoTErrorCodeRateLimited
-4
请求被限频
降低调用频率后重试。
TXIoTErrorCodeUnauthorizedOperation
-5
当前用户无权限（常见于设备未绑定）
确认目标设备已绑定到当前账户（见前提条件）。
TXIoTErrorCodeDeviceNotExist
-1009
设备不存在
确认 deviceId 是否正确、设备是否已绑定。
TXIoTErrorCodeDeviceOffline
-1010
设备离线
确认设备在线后重试。
TXIoTErrorCodeCameraStartFail
-2000
摄像头启动失败
检查摄像头是否被占用或硬件异常。
TXIoTErrorCodeCameraNotAuthorized
-2001
摄像头无权限
在工程中申请并获取摄像头权限。
TXIoTErrorCodeCameraOccupy
-2002
摄像头被占用
释放其他占用摄像头的功能后再试。
TXIoTErrorCodeMicStartFail
-2003
麦克风启动失败
检查麦克风是否被占用或硬件异常。
TXIoTErrorCodeMicNotAuthorized
-2004
麦克风无权限
在工程中申请并获取麦克风权限。
TXIoTErrorCodeMicOccupy
-2005
麦克风被占用
释放其他占用麦克风的功能后再试。
TXIoTErrorCodeSpeakerStartFail
-2006
扬声器启动失败
检查音频输出设备是否正常。

方法	说明
addListener	添加通话状态与错误的监听器，回调接口定义见通话事件回调（iOS 方法名为 `addDelegate`）。
removeListener	移除已注册的监听（iOS 方法名为 `removeDelegate`）。

方法	说明
callDevice	向 `deviceId`（TXIoTDeviceId）指定的设备发起通话，`callType`（TXIoTCallMediaType）为通话类型。
hangup	挂断并结束当前通话。

方法	说明
openCamera	开启并预览指定摄像头。 `cameraId` 为枚举类型 TXIoTCamera（前置/后置摄像头）。 `videoView` 为渲染视图（Android 为 `TXCloudVideoView`，iOS 为 `UIView`）。
startRemoteView	渲染对端画面。 `callUser` 为 TXIoTCallUser 类型。 `videoView` 为渲染视图（Android 为 `TXCloudVideoView`，iOS 为 `UIView`）。
stopRemoteView	停止渲染指定对端画面。 `callUser` 为 TXIoTCallUser 类型。

方法	说明
openMicrophone	开启本地麦克风采集、传输。
closeMicrophone	关闭本地麦克风采集、传输。
selectAudioPlaybackDevice	选择通话音频的播放设备，`device` 为 TXIoTAudioPlaybackDevice（听筒或扬声器）类型。

回调	触发时机 / 说明
`onError`	通话发生错误时回调错误码与信息（如摄像头/麦克风权限被拒、设备离线、网络异常等）。
`onCallBegin`	通话建立。
`onCallAccepted`	设备接听本次通话。
`onCallEnd`	通话结束。参数中带结束原因（如 LOCAL_HANGUP、REMOTE_HANGUP、CALL_PERMISSION_DENIED、NETWORK_ERROR 等）。
`onCallRejected`	设备拒绝接听本次通话。
`onCallNoResponse`	设备在 30 秒内未接听，通话超时。
`onCallUserOffline`	对端设备通话过程中离线。
`onCallUserAudioAvailable`	对方音频可用状态变化。
`onCallUserVideoAvailable`	对方视频可用状态变化。
`onCallNetworkQualityChanged`	本地与远端网络质量变化。

错误码	说明	建议处理方式
`ERR_SUCCESS`	成功。	无需处理（调用成功）。
`ERR_FAILED`	通用失败。	结合 `onError` 返回的 `errMsg` 排查具体失败原因。
`ERR_INVALID_PARAMETER`	参数不合法。	检查 `deviceId`、`callType` 等参数是否为空或格式错误。
`ERR_INVALID_ACCESS_TOKEN`	登录凭证无效。	重新登录 SDK 后再发起通话。
`ERR_RATE_LIMITED`	请求被限频。	降低调用频率后重试。
`ERR_UNAUTHORIZED_OPERATION`	当前用户无权限（常见于设备未绑定）。	确认目标设备已绑定到当前账户（见前提条件）。
`ERR_DEVICE_NOT_EXIST`	设备不存在。	确认 `deviceId` 是否正确、设备是否已绑定。
`ERR_DEVICE_OFFLINE`	设备离线。	确认设备在线后重试。
`ERR_CAMERA_START_FAIL`	摄像头启动失败。	检查摄像头是否被占用或硬件异常。
`ERR_CAMERA_NOT_AUTHORIZED`	摄像头无权限。	在工程中申请并获取摄像头权限。
`ERR_CAMERA_OCCUPY`	摄像头被占用。	停止其他占用摄像头的功能后再试。
`ERR_MIC_START_FAIL`	麦克风启动失败。	检查麦克风是否被占用或硬件异常。
`ERR_MIC_NOT_AUTHORIZED`	麦克风无权限。	在工程中申请并获取麦克风权限。
`ERR_MIC_OCCUPY`	麦克风被占用。	停止其他占用麦克风的功能后再试。
`ERR_SPEAKER_START_FAIL`	扬声器启动失败。	检查音频输出设备是否正常。

错误码	数值	说明	建议处理方式
`TXIoTErrorCodeSuccess`	0	成功	无需处理（调用成功）。
`TXIoTErrorCodeFailed`	-1	通用失败	结合 `onError` 返回的 `errMsg` 排查具体失败原因。
`TXIoTErrorCodeInvalidParameter`	-2	参数不合法	检查 `deviceId`、`callType` 等参数是否为空或格式错误。
`TXIoTErrorCodeInvalidAccessToken`	-3	登录凭证无效	重新登录 SDK 后再发起通话。
`TXIoTErrorCodeRateLimited`	-4	请求被限频	降低调用频率后重试。
`TXIoTErrorCodeUnauthorizedOperation`	-5	当前用户无权限（常见于设备未绑定）	确认目标设备已绑定到当前账户（见前提条件）。
`TXIoTErrorCodeDeviceNotExist`	-1009	设备不存在	确认 `deviceId` 是否正确、设备是否已绑定。
`TXIoTErrorCodeDeviceOffline`	-1010	设备离线	确认设备在线后重试。
`TXIoTErrorCodeCameraStartFail`	-2000	摄像头启动失败	检查摄像头是否被占用或硬件异常。
`TXIoTErrorCodeCameraNotAuthorized`	-2001	摄像头无权限	在工程中申请并获取摄像头权限。
`TXIoTErrorCodeCameraOccupy`	-2002	摄像头被占用	释放其他占用摄像头的功能后再试。
`TXIoTErrorCodeMicStartFail`	-2003	麦克风启动失败	检查麦克风是否被占用或硬件异常。
`TXIoTErrorCodeMicNotAuthorized`	-2004	麦克风无权限	在工程中申请并获取麦克风权限。
`TXIoTErrorCodeMicOccupy`	-2005	麦克风被占用	释放其他占用麦克风的功能后再试。
`TXIoTErrorCodeSpeakerStartFail`	-2006	扬声器启动失败	检查音频输出设备是否正常。

应用端接入

本页目录：

前提条件

使用建议

获取通话会话对象

设置通话监听

发起与结束通话

设置渲染视图

开关摄像头与切换

开关麦克风与切换

通话状态与回调通知

错误处理