Device Service Request APIs

This page describes WeChat VoIP calling service APIs that the device accesses through TiRtcServiceRequest.

These APIs are accessed by Nano SDK using the device identity. The SDK internally sends an HTTP request to the TiRTC cloud. Device applications only need to pass the API path, JSON request body, and callback; do not build HTTP URLs, signing headers, or access tokens manually.

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

Parameter	Description
`path`	Service API path, for example `/v1/wxvoip/reject`.
`json_body`	Request JSON string. Passing `NULL` uses GET; otherwise POST is used.
`token`	Authorization token when accessing as a client; pass `NULL` when accessing as a device.
`cb`	Callback for platform response data, if any.
`user_data`	User context pointer passed through to `cb`.

API List

Method	Path	Description
POST	`/v1/wxvoip/reject`	Reject or busy before the call is connected.

Reject: `POST /v1/wxvoip/reject`

Purpose

When the Mini Program calls the device and the device rejects or is busy before connection, call this API to notify the WeChat VoIP calling cloud to end the waiting call.

At this point the device has not established a TiRTC connection, so it cannot send the hang-up command (cmdw=0x2001) over the command channel. After a TiRTC connection has been established, hang-up, reject, busy, and similar states use the hang-up command (cmdw=0x2001) as defined in WeChat VoIP Calling Commands.

Request

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

Body (JSON)

Field	Type	Required	Description
`wx_app_id`	string	Yes	Mini Program `appId`. From `wxa_join_voip_room` delivered by the business server.
`wx_model_id`	string	Yes	WeChat hardware device model ID for WeChat VoIP calling.
`wx_session_token`	string	Yes	`server_token` from the WeChat `join_voip_room` notification; your business payload may name the same value `wxa_server_token`.
`wx_room_id`	string	Yes	WeChat room ID.
`wx_payload`	string	No	Caller passthrough payload. Defaults to an empty string when omitted.
`hangup_reason`	number	Yes	Hang-up reason value; see Hang-up reasons.

Common hangup_reason values:

Scenario	Value
Device busy	`5`
User rejects	`7`

Example

json

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

Response

On success, the callback response body has this shape:

json

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

On failure, code is non-zero and msg contains the reason. Device applications should log failed responses and, if needed, end the local ringing state according to business policy.

Possible error codes:

code	Typical scenario
`40001`	Failed to read request body.
`40013`	JSON parsing failed, a required field is missing, or `hangup_reason` is outside `0..20`.
`40103`	Authorization failed, usually because the device secret is wrong or the device clock skew is too large.
`50001`	`tgwxvoip --hangup` execution failed or the executable path is not configured.

Return Value

The synchronous return value of TiRtcServiceRequest indicates whether the request was started; the actual business response is returned through the callback:

Return value	Description
`0`	Request started successfully; response is returned through the callback.
`< 0`	SDK parameter, state, network, or similar error.
`> 0`	HTTP status is not `200`; see the platform callback data for details.

Device Service Request APIs ​

API List ​

Reject: POST /v1/wxvoip/reject ​

Purpose ​

Request ​

Response ​