# 设备呼叫小程序 (/zh-CN/api-reference/api-ref/voip-callkit/call-mini-app)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

通过该接口实现设备端向微信小程序发起呼叫。

- OpenAPI: /openapi/voip-callkit/call.zh-CN.yaml
- Operation ID: callMiniApp
- Method: POST
- Path: /v2/miniapp/{appId}/voip/call/miniapp
- Endpoint: https://api.sd-rtn.com/v2/miniapp/{appId}/voip/call/miniapp

## Servers

- https://api.sd-rtn.com

## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `appId` (path, required, string) - 你的声网项目使用的 [App ID](/zh-CN/introduction/glossary#appid)。

## Request body

- `agora` (object, required) - 声网相关配置。
  - `agora.appId` (string, required) - 你的声网项目使用的 [App ID](/zh-CN/introduction/glossary#appid)。
  - `agora.channelName` (string, required) - 设备端加入的 RTC 频道名。
  - `agora.robotUID` (string, required) - 微呼叫服务加入 RTC 频道时使用的 UID。
  - `agora.deviceUID` (string, required) - 设备端加入 RTC 频道时使用的 UID。
  - `agora.token` (string, required) - 微呼叫服务加入 RTC 频道时使用的 [Token](/zh-CN/introduction/glossary#token)。
  - `agora.license` (string, required) - License 值，用于校验呼叫是否合法，校验结果会通过 NCS 事件 98 返回。详见[获取并使用 License](/zh-CN/solutions/voip-call/build/license)。
  - `agora.encryptionMode` (string, required) - 加密模式。可以设为如下值：
- `AES_128_XTS`: 128 位 AES 加密，XTS 模式
- `AES_128_ECB`: 128 位 AES 加密，ECB 模式
- `AES_256_XTS`: 256 位 AES 加密，XTS 模式
- `SM4_128_ECB`: 128 位 SM4 加密，ECB 模式
- `AES_128_GCM`: 128 位 AES 加密，GCM 模式
- `AES_256_GCM`: 256 位 AES 加密，GCM 模式
- `AES_128_GCM2`:（默认）128 位 AES 加密，GCM 模式。该加密模式需要设置盐（encryptionKdfSalt）
- `AES_256_GCM2`: 256 位 AES 加密，GCM 模式。该加密模式需要设置盐（encryptionKdfSalt）

如果不想启用加密，可以设置为 `NONE`。

  - `agora.encryptionKey` (string) - 加密的 Key 值，与设备端对应，encryptionMode 为 `NONE` 时，可以不填。
  - `agora.encryptionKdfSalt` (string) - 盐值，encryptionMode 为 `NONE` 时，可以不填。
  - `agora.source` (object, required) - 从设备端向小程序端发送的视频祯属性。`agora.source` 和 `wechat.sink` 为对应关系，你可以参考 [设置 Source 和 Sink](/zh-CN/solutions/voip-call/build/set-source-sink)了解更多细节。

    - `agora.source.videoCodec` (string, required) - 支持设为 JPEG、H264、H265。
    - `agora.source.videoWidth` (integer, required) - 视频的宽。
    - `agora.source.videoHeight` (integer, required) - 视频的高。
    - `agora.source.videoFrameRate` (integer, required) - 视频帧率。
  - `agora.sink` (object, required) - 设备端接收小程序端的视频祯属性。`agora.sink` 和 `wechat.source` 为对应关系，你可以参考 [设置 Source 和 Sink](/zh-CN/solutions/voip-call/build/set-source-sink)了解更多细节。

    - `agora.sink.videoTranscode` (boolean) - 是否需要对接收到的视频祯进行转码。如果 `agora.sink` 中的 videoCodec 设为 JPEG，则需要设置为 `true`。
    - `agora.sink.audioCodec` (string, required) - 支持设为 PCMU、PCMA、G722、AAC。
    - `agora.sink.videoCodec` (string, required) - 支持设为 JPEG、H264、H265。
    - `agora.sink.videoWidth` (integer, required) - 视频的宽。
    - `agora.sink.videoHeight` (integer, required) - 视频的高。
    - `agora.sink.videoFrameRate` (integer, required) - 视频帧率。
- `wechat` (object, required) - 微信小程序相关配置。
  - `wechat.openId` (string, required) - 小程序用户的唯一 ID。该 ID 需要用户授权。
  - `wechat.appId` (string, required) - 微信小程序的 App ID。
  - `wechat.deviceId` (string, required) - 设备 ID。
  - `wechat.modelId` (string, required) - 设备的 Model ID。
  - `wechat.encodeVideoRotation` (integer) - 设备端接收的视频旋转信息，适用于没有画面旋转能力的设备。可以设为如下值：
- `1`：设备端看到的微信小程序画面永远保持正向
- `2`：保留原有的旋转方向

更多信息可以参考[微信小程序 VoIP 视频流指南](https://developers.weixin.qq.com/miniprogram/dev/framework/device/voip/voip-video.html)。

  - `wechat.landscape` (boolean, required) - 设备端接收小程序推流是否为 4:3 的流。
- `true`: SDK 收到的流为横屏，即宽高比为 4:3。该宽高比下，视频分辨率可以设为 320 × 240、480 × 352、640 × 480、1280 × 720、1920 × 1080
- `false`: SDK 收到的流为竖屏，即宽高比为 3:4。该宽高比下，视频分辨率可以设为 240 × 320、352 × 480、480 × 640、720 × 1080、1080 × 1920

  - `wechat.subscribeVideoLength` (integer, required) - 设备端订阅视频分辨率的固定长边值。适用于不希望收到可变分辨率视频流的设备。如果不使用此功能，SDK 收到的视频流在不同的网络环境下会有不同的分辨率。如果想开通该功能，需要同时向微信提交 App ID，待开通订阅机制后才生效。支持设为如下值：
- `320`: video_landscape = true 时收到的是 320 × 240，video_landscape = false 时收到的是 240 × 320
- `640`: 不支持 video_landscape = true 模式，video_landscape = false 时收到的是 480 × 640

  - `wechat.roomType` (string, required) - 房间类型，支持设为如下值：
- `video`：视频通话
- `voice`：音频通话

  - `wechat.listenerName` (string, required) - 微信端显示呼入名字，在小程序授权设备时指定。该参数设置不生效，可以填写任意字符串，如 `"m"`。
  - `wechat.versionType` (integer, required) - 接听方小程序的类型：
- `0`：正式版
- `1`：开发版
- `2`：体验版

  - `wechat.query` (string, required) - 小程序页面自定义参数。
  - `wechat.callerCameraStatus` (integer, required) - 小程序是否打开远端视图，以便看到拨打方:
- `0`：打开
- `1`：关闭

  - `wechat.listenerCameraStatus` (integer, required) - 小程序是否打开本地视图，以便看到接听方：
- `0`：打开
- `1`：关闭

  - `wechat.source` (object, required) - 从小程序端向设备端发送的视频祯属性。`wechat.source` 和 `agora.sink` 为对应关系，你可以参考 [Source 和 Sink 对应关系](/zh-CN/solutions/voip-call/build/set-source-sink)了解更多细节。

    - `wechat.source.videoCodec` (string, required) - 支持 H264、H265。
    - `wechat.source.videoWidth` (integer, required) - 视频的宽。
    - `wechat.source.videoHeight` (integer, required) - 视频的高。
    - `wechat.source.videoFrameRate` (integer, required) - 视频帧率。
  - `wechat.sink` (object, required) - 小程序端接收设备端发送的视频祯属性。`wechat.sink` 和 `agora.source` 为对应关系，你可以参考 [Source 和 Sink 对应关系](/zh-CN/solutions/voip-call/build/set-source-sink)了解更多细节。

    - `wechat.sink.videoTranscode` (boolean) - 是否需要对接收到的视频祯进行转码。如果 `agora.source` 中的 videoCodec 为JPEG，则需要设置 `true`。
    - `wechat.sink.videoCodec` (string, required) - 支持 H264、H265。
    - `wechat.sink.videoWidth` (integer, required) - 视频的宽。
    - `wechat.sink.videoHeight` (integer, required) - 视频的高。
    - `wechat.sink.videoFrameRate` (integer, required) - 视频帧率。

### Request body example

```json
{
  "agora": {
    "channelName": "voip123456",
    "robotUID": "123",
    "deviceUID": "456",
    "token": "aabxxxxxxxxxxxx63",
    "license": "sdfjiojefkkglekr",
    "appId": "aabxxxxxxxxxxxx63",
    "encryptionMode": "NONE",
    "encryptionKey": "test123",
    "encryptionKdfSalt": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq",
    "source": {
      "videoCodec": "H264",
      "videoWidth": 640,
      "videoHeight": 480,
      "videoFrameRate": 15
    },
    "sink": {
      "audioCodec": "PCMA",
      "videoTranscode": false,
      "videoCodec": "H264",
      "videoWidth": 640,
      "videoHeight": 480,
      "videoFrameRate": 15
    }
  },
  "wechat": {
    "openId": "ox-xxxxxxxxxxxxA",
    "appId": "wxxxxxxxxxxd6",
    "deviceId": "test_sn_1",
    "modelId": "axxxxxxxxw",
    "encodeVideoRotation": 1,
    "landscape": true,
    "subscribeVideoLength": 320,
    "roomType": "video",
    "listenerName": "m",
    "versionType": 1,
    "query": "a=b",
    "callerCameraStatus": 0,
    "listenerCameraStatus": 0,
    "source": {
      "videoCodec": "H264",
      "videoWidth": 1920,
      "videoHeight": 1080,
      "videoFrameRate": 15
    },
    "sink": {
      "videoTranscode": false,
      "videoCodec": "H264",
      "videoWidth": 640,
      "videoHeight": 480,
      "videoFrameRate": 15
    }
  }
}
```

## Responses

### 200

请求成功。

- `code` (integer, required) - 状态码。
- `msg` (string, required) - 提示信息。
- `taskId` (string) - 本次请求的唯一标识符。该字段的值和 NCS 事件中返回的 sid 一致，你可以使用该字段定位出现异常的请求，然后排查问题。
### 非 200

请求失败。可能的原因有：
- 状态码为 400，表示请求异常。可能的原因有参数错误、License 错误、未开通服务等。你可以参考响应 Body 中的 `msg` 信息进行问题排查。
- 状态码为 500，表示服务端异常。可能的原因有连接超时、响应错误等。你可以参考响应 Body 中的 `msg` 信息进行问题排查。


- `code` (integer, required) - 状态码。
- `msg` (string, required) - 提示信息。
- `taskId` (string) - 本次请求的唯一标识符。该字段的值和 NCS 事件中返回的 sid 一致，你可以使用该字段定位出现异常的请求，然后排查问题。

## Response examples

### 200

```json
{
  "code": 200,
  "msg": "ok",
  "taskId": "1NxxxxxxxxxxxxxxxxxV"
}
```
### 非 200

```json
{
  "code": null,
  "msg": "提示信息。",
  "taskId": "本次请求的唯一标识符。该字段的值和 NCS 事件中返回的 sid 一致，你可以使用该字段定位出现异常的请求，然后排查问题。"
}
```