设备服务请求接口

本页说明设备侧通过 TiRtcServiceRequest 访问的微信VoIP通话服务接口。

这类接口由 Nano SDK 使用设备身份签名访问，内部会向 TiRTC 云端发起 HTTP 请求。设备应用只需要传入接口路径、JSON 请求体和回调；不要自行拼接 HTTP 地址、签名头或 access token。

int TiRtcServiceRequest(const char *path,
                        const char *json_body,
                        const char *token,
                        TIRTCSERVICEREQUESTCALLBACK cb,
                        void *user_data);

参数	说明
path	服务接口路径，例如 /v1/wxvoip/reject。
json_body	请求 JSON 字符串；传 NULL 时使用 GET，否则使用 POST。
token	作为客户端访问时授权 token；作为设备时传 NULL。
cb	平台返回的数据（如果有的话）回调。
user_data	透传给 cb 的用户上下文指针。

接口列表

方法	路径	说明
POST	/v1/wxvoip/reject	接通前拒接或忙线。

拒接：POST /v1/wxvoip/reject

用途

小程序呼叫设备时，设备在接通前拒接或忙线，需要调用本接口通知微信VoIP通话云端结束振铃。

此时设备尚未建立 TiRTC 连接，不能通过命令通道发送挂断命令（cmdw=0x2001）。已建立 TiRTC 连接后的挂断、拒接、忙线等状态，按 微信VoIP通话命令 使用挂断命令（cmdw=0x2001）。

请求

TiRtcServiceRequest("/v1/wxvoip/reject", json_body, NULL, cb, user_data);

Body（JSON）

字段	类型	必填	说明
wx_app_id	string	是	小程序 appId。来自业务服务端下发的 wxa_join_voip_room。
wx_model_id	string	是	微信硬件设备的微信VoIP通话模型 ID。
wx_session_token	string	是	微信 join_voip_room 通知中的 server_token；示例载荷中常命名为 wxa_server_token。
wx_room_id	string	是	微信房间 ID。
wx_payload	string	否	主叫透传 payload；不传时默认为空字符串。
hangup_reason	number	是	挂断原因值，见 挂断原因。

常用 hangup_reason：

场景	值
设备忙线	5
用户拒接	7

示例

{
  "wx_app_id": "wx0123456789abcdef",
  "wx_model_id": "model-1",
  "wx_session_token": "server-token",
  "wx_room_id": "room-123",
  "wx_payload": "",
  "hangup_reason": 7
}

响应

成功时回调中的响应体形态如下：

{
  "code": 0,
  "msg": "ok"
}

失败时 code 非 0，msg 包含失败原因。设备应用应记录失败响应，必要时按业务策略结束本地振铃状态。

可能的错误码：

code	典型场景
40001	读取请求 body 失败。
40013	JSON 解析失败、缺少必填字段，或 hangup_reason 超出 0..20。
40103	授权失败，通常为设备密码错误或设备时间偏差过大。
50001	tgwxvoip --hangup 执行失败或未配置可执行路径。

返回值

TiRtcServiceRequest 的同步返回值表示请求是否成功发起，实际业务响应通过回调返回：

返回值	说明
0	请求已成功发起；响应通过回调返回。
< 0	SDK 参数、状态或网络等错误。
> 0	HTTP 非 200；具体错误见平台回调数据。