帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>通用功能（应用端）>微信通话>小程序呼叫设备

小程序呼叫设备

最近更新时间：2026-09-20 16:47:02
我的收藏

本页目录：

本文将介绍小程序端如何接入 TWeCall（微信通话），实现向设备端发起音视频呼叫，帮助您快速完成小程序呼叫设备场景的接入。
TWeCall 是腾讯云物联网开发平台提供的设备与微信小程序之间的双向音视频通话能力。小程序端通过 TXIoTCallSession 发起呼叫，设备端接听后即可进行音视频通话。

前提条件

已完成 集成与登录 文档中的登录功能，小程序成功登录。
已在物联网开发平台完成 TWeCall 服务激活与小程序授权，详见 开通微信通话服务。

接入流程

小程序向设备端发起呼叫分为以下三步：
1. 绑定设备到家庭：设备须先归属某个家庭，才能对其发起通话。
2. 添加渲染组件：在通话页面放置 iot-pusher 与 iot-player 组件。
3. 发起通话：获取通话会话、监听通话事件、绑定渲染组件后呼叫设备。

接入步骤

步骤 1：绑定设备到家庭

设备必须先绑定到家庭后才能发起通话。通过 bindDevice 使用设备绑定签名直接绑定，详细流程请参见 设备绑定。
const plugin = requirePlugin('tx-iot-sdk');
const engine = plugin.TXIoTEngine.getInstance();
const familyManager = engine.getFamilyManager();
const deviceManager = engine.getDeviceManager();

// 1. 获取家庭列表；首次使用可先通过 createFamily 创建家庭
const families = await familyManager.getFamilyList();
const familyId = families[0]?.familyId;

// 2. 使用设备绑定签名将设备绑定到家庭
// deviceBindSignature 由设备配网流程或扫描设备机身二维码获取
const deviceBindSignature = 'YOUR_DEVICE_BIND_SIGNATURE';
const deviceInfo = await deviceManager.bindDevice(familyId, deviceBindSignature);
绑定成功后，设备会出现在 getDeviceList 的返回结果中。

步骤 2：添加渲染组件

通话页面需要放置两个渲染组件：iot-pusher 负责本端音视频的采集与推流，openMicrophone、openCamera 等接口采集的声音和画面通过该组件推送给设备端；iot-player 负责渲染设备端的音视频画面与声音。
首先在页面 JSON 中声明组件：
{
  "usingComponents": {
    "iot-pusher": "plugin://tx-iot-sdk/iot-pusher",
    "iot-player": "plugin://tx-iot-sdk/iot-player"
  }
}
然后在页面 wxml 中放置组件，并通过 component-id 指定组件 ID（后续 setIoTPlayer 绑定时需要用到）：
<!-- 本端画面预览与推流 -->
<iot-pusher />

<!-- 远端画面与声音渲染 -->
<iot-player component-id="remotePlayer" />
注意：
即使发起的是音频通话，也需要放置 iot-player 组件——通话中远端的声音通过该组件播放。

步骤 3：发起通话

3.1 获取通话会话

登录成功后，通过 TXIoTEngine.getCallSession 获取通话会话对象：
const callSession = engine.getCallSession();
说明：
未登录或初始化未完成时 getCallSession 返回 null，请先确认登录成功后再调用。

3.2 监听通话事件

通过 addListener 注册事件回调，只需实现自己关心的回调方法，未实现的方法不会被调用：
callSession.addListener({
  onCallBegin: (mediaType) => {
    // 通话接通
  },
  onCallEnd: (mediaType, reason) => {
    // 通话结束，reason 为结束原因
  },
  onCallRejected: (callUser) => {
    // 对方拒接
  },
  onCallNoResponse: (callUser) => {
    // 对方无应答
  },
  onCallLineBusy: (callUser) => {
    // 对方占线
  },
  onCallUserOffline: (callUser) => {
    // 对方离线
  },
  onCallUserVideoAvailable: (callUser, available) => {
    // 远端视频可用；
  },
  onCallUserAudioAvailable: (callUser, available) => {
    // 远端音频可用性变化
  },
  onError: (code, msg) => {
    // 通话发生错误
  },
});

3.3 绑定渲染组件

通过 setIoTPlayer 将远端用户与 iot-player 组件绑定，SDK 会在该组件上渲染远端用户的音视频。CallSession.setIoTPlayer 第二个参数 iotPlayerComponentId 传入 wxml 中 component-id 指定的值：
const sdk = requirePlugin('tx-iot-sdk');

// 构造对端用户；deviceId 为被叫设备的设备标识（含 productId / deviceName）
const deviceId = { productId: 'YOUR_PRODUCT_ID', deviceName: 'YOUR_DEVICE_NAME' };
const callUser = new sdk.TXIoTCallUser(deviceId);

// 与 wxml 中的 <iot-player component-id="remotePlayer" /> 绑定
callSession.setIoTPlayer(callUser, 'remotePlayer');
callSession.startRemoteView(callUser);

3.4 发起呼叫

调用 callDevice 向设备发起通话，callType 指定通话类型：AUDIO 音频通话、VIDEO 视频通话（见 TXIoTCallMediaType）：
// 发起视频通话；音频通话传 sdk.TXIoTCallMediaType.AUDIO
callSession.callDevice(deviceId, sdk.TXIoTCallMediaType.VIDEO);
呼叫结果通过 第3.2步 注册的回调通知：接通时收到 onCallBegin；对端拒接、无应答、占线、离线时分别收到 onCallRejected、onCallNoResponse、onCallLineBusy、onCallUserOffline。

3.5 开启本端媒体

通话接通前后，都可以按需开启本端媒体：
// 开启本端麦克风
callSession.openMicrophone();

// 视频通话：开启本端摄像头（前置）
callSession.openCamera(sdk.TXIoTCamera.FRONT);

3.6 挂断通话

调用 hangup 挂断当前通话。通话结束后收到 onCallEnd 回调，reason 为结束原因（本端挂断、对端挂断、网络错误等，见 TXIoTCallEndReason）：
callSession.hangup();
完整的通话接口说明（含 switchCamera 切换摄像头、selectAudioPlaybackDevice 切换扬声器/听筒等）请参见 TXIoTCallSession。

常见问题

通话接通后听不到远端声音？

确认页面已放置 iot-player 组件。音频通话场景下远端声音也通过该组件播放，组件缺失会导致无声。

getCallSession 返回 null？

getCallSession 依赖 TXIoTEngine 创建与登录完成。请在登录成功的回调之后再获取通话会话对象，并确认 tx-iot-sdk 插件已正确集成。

呼叫后立即收到对端离线回调？

收到 onCallUserOffline 表示设备端不在线。请确认设备已激活 TWeCall 服务并成功登录上线，设备端接入流程请参见 设备端接入。

相关文档

设备端接入：设备侧接入流程，含呼叫小程序与接听小程序呼叫。
设备呼叫小程序：对端方向（设备呼叫微信）的小程序端接入。
TXIoTCallSession：通话接口的完整说明。
TXIoTDeviceManager：设备绑定等接口的完整说明。
中国站