Server API

Your business server calls TiRTC cloud tirtc-server-api (TGV1-HMAC-SHA256 authentication) to query device call status and issue WHIP peer_id (service_desc) and Bearer token for device-side TiRtcWhipConnect.

tirtc-server-api base URL: https://api-tirtc.tange365.com.

TGV1-HMAC-SHA256 signing

This is the same as the Tange cloud OpenAPI server-side signing scheme. See Server API signing algorithm demo.

Query device WeChat VoIP call status: GET /v1/device/wxvoip-call-status

Purpose: Before initiating a call, the business server can query whether the specified device is establishing a WeChat VoIP connection, ringing or in a call attempt, or already connected. This endpoint uses TGV1-HMAC-SHA256 authentication and only permits queries for an existing, unexpired device whose product is associated with the authenticated application.

Status reporting and cleanup are subject to delay. Use this result to reduce duplicate calls, not as a race-free device reservation mechanism.

Request

Headers

Header	Description
Authorization	TGV1 authorization line
X-Tg-Algorithm	Algorithm name
X-Tg-Date	Request time (UTC)
X-Tg-App-Id	Application ID; must match credential app_id
X-Tg-Content-Sha256	SHA-256 of the empty request body
X-Tg-Signed-Headers	List of header names included in signing

For these TGV1-related headers, see TGV1-HMAC-SHA256 signing for format and calculation.

Query parameters

Field	Type	Required	Description
device_id	string	Yes	Device ID. The device must exist, be unexpired, and belong to a product associated with the authenticated application.

Response

Success response example:

{
  "code": 0,
  "message": "ok",
  "data": {
    "in_call": true
  }
}

Field	Type	Description
data.in_call	boolean	true means the device is establishing a connection, ringing or in a call attempt, or already connected. false means no such session was found in the current status store; it does not represent an atomic reservation or guarantee that another call cannot start concurrently. Reporting delays or failures may also temporarily hide a session that has already started.

Common business errors:

code	Description
40003	Invalid request parameters, such as a missing device_id
40302	The device product is not associated with the authenticated application
40304	The device has expired
40403	The device does not exist
50000	An internal server error occurred while querying call status

Issue WeChat VoIP call credentials: POST /v1/token/wxvoip

Purpose: Based on the current WeChat VoIP session and device media capabilities, request peer_id and token from the Tange platform. Your business server then delivers both to the device in wxa_join_voip_room.

Request

Headers

Header	Description
Content-Type	application/json
Authorization	TGV1 authorization line
X-Tg-Algorithm	Algorithm name
X-Tg-Date	Request time (UTC)
X-Tg-App-Id	Application id, must match credential app_id
X-Tg-Content-Sha256	Request body SHA-256 (lowercase hex)
X-Tg-Signed-Headers	List of header names included in signing

For these TGV1-related headers, see TGV1-HMAC-SHA256 signing for format and calculation.

Body (JSON)

Field	Type	Description
wx_session_key	string	Required. session_key from WeChat join_voip_room notification
wx_room_id	string	Required. room_id from WeChat notification
wx_session_token	string	Required. server_token from WeChat notification
wx_app_id	string	Required. Mini Program appId
device_id	string	Required. Device identifier, must match the device identity in your push message
wx_model_id	string	Required (configured in the example). WeChat hardware model ID for WeChat VoIP calling
wx_payload	string	Optional. Caller passthrough payload; treated as empty string when omitted
calling_timeout_sec	number	Optional. Ring timeout in seconds, default 30
no_video	boolean	Optional. true for audio-only
video_mt	string	Optional compatibility field; sets both uplink and downlink video format: h264 / mjpeg / none. If up_video_mt/down_video_mt are both provided but inconsistent, the request fails
up_video_mt	string	Video format from device to WeChat Mini Program: h264 / h265 / mjpeg / none; do not use together with video_mt
down_video_mt	string	Video format from WeChat Mini Program to device: h264 / mjpeg / none; do not use together with video_mt
down_video_rotation	number	Optional. Video stream orientation from the WeChat Mini Program to the device. Supported values: 0, 1, and 2; default: 0. 0: use the WeChat SDK default behavior; 1: subscribe to an upright 0° stream while the WeChat side also sets encodeVideoRotation=1; 2: explicitly keep the rotated stream
screen_width / screen_height	number	Screen width and height when not audio-only
video_res_mode	string	Optional. Downlink video resolution mode: auto / fit_screen / fill_screen; omitting it is equivalent to auto
down_audio_mt	string	Audio encoding from WeChat Mini Program to device: alaw / amr / opus; default alaw when omitted
audio_rate	number	Required. Supported values: 8000, 16000
audio_channels	number	Required. Supported values: 1, 2

Your business server usually builds this JSON after receiving WeChat join_voip_room, combining WeChat notification fields with device-reported media capabilities.

Downlink video resolution modes

Mode	Behavior
auto	Passes through the WeChat downlink video without scaling or cropping
fit_screen	Applies a second-stage scale to the WeChat video negotiated under the auto rules so that it fits within the screen boundary
fill_screen	Applies a second-stage scale and center crop to the WeChat video negotiated under the auto rules so that it fills the screen

auto

When video_res_mode is omitted or set to auto, the service passes through the WeChat downlink video without scaling or cropping. The screen size determines the resolution requested from WeChat:

• screen_width × screen_height <= 480 × 240: requests a fixed long edge of 320. The resolution is 320×240 in landscape or 240×320 in portrait.
• screen_width × screen_height > 480 × 240: WeChat adaptively sends a variable resolution with a maximum long edge of 640. The maximum is 640×480 in landscape or 480×640 in portrait.

fit_screen

The service first receives the WeChat downlink video under the auto rules, then scales it down proportionally using screen_width × screen_height as the maximum boundary:

• Preserves the source aspect ratio without stretching, cropping, or adding black bars.
• Scales down only; it does not upscale.
• Rounds each output dimension down to an even number.
• Recalculates the output dimensions and rebuilds the scaler and MJPEG encoder when the WeChat source resolution changes.
• Drops the current frame if scaler or encoder initialization fails; it does not fall back to sending the original-size frame.

fill_screen

The service first receives the WeChat downlink video under the auto rules, then scales it proportionally and center-crops it. The output dimensions exactly match screen_width × screen_height:

• Preserves the source aspect ratio without stretching or adding black bars.
• May upscale and crops the top and bottom or left and right when the aspect ratios differ.
• Recalculates the crop and rebuilds the scaler and MJPEG encoder when the WeChat source resolution changes.
• Drops the current frame if scaler or encoder initialization fails; it does not fall back to sending the original-size frame.

For example, when WeChat sends 240×320 video to a device with a 160×100 screen:

Mode	Output resolution	Result
fit_screen	74×100	Preserves the complete image; the video is narrower than the screen
fill_screen	160×100	Center-crops the top and bottom and fills the screen

Current limitations:

• fit_screen and fill_screen support downlink MJPEG only and require both screen_width and screen_height.
• fill_screen may upscale and crops the top and bottom or left and right when the aspect ratios differ. Both screen dimensions must be even.
• Neither mode rotates the image. The WeChat video negotiation still determines the downlink orientation.

Response

On HTTP 200 with business success, the response uses the unified wrapper, for example:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "peer_id": "whips://wxvoip?x_wx_session_key=...&x_device_id=...",
    "token": "<Bearer token string>"
  }
}

• code !== 0: failure. msg contains details. Do not deliver invalid peer_id / token to the device.
• data.peer_id: the first argument of TiRtcWhipConnect(service_desc, ...) (full whips://wxvoip?... URL).
• data.token: the second argument of TiRtcWhipConnect(..., token, ...).