Domain name for API request: tiw.tencentcloudapi.com.
This API is used to start a whiteboard push task.
A maximum of 20 requests can be initiated per second for this API.
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
Parameter Name | Required | Type | Description |
---|---|---|---|
Action | Yes | String | Common Params. The value used for this API: StartWhiteboardPush. |
Version | Yes | String | Common Params. The value used for this API: 2019-09-19. |
Region | Yes | String | Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-singapore. |
SdkAppId | Yes | Integer | SdkAppId of the whiteboard application. |
RoomId | Yes | Integer | Room ID of the whiteboard push task. Valid range: (1,4294967295). 1. By default, the whiteboard push task uses the RoomId string as the GroupID of the IM group. For example, if the RoomId string is 1234, the GroupID of the IM group is also 1234. Message synchronization requires joining a group. Make sure that an IM group is created before the push starts. Otherwise, the push fails. 2. If neither TRTCRoomId nor TRTCRoomIdStr is specified, the value of RoomId is used as the Tencent Real-Time Communication (TRTC) room ID for the whiteboard push task. |
PushUserId | Yes | String | User ID used by the whiteboard push service for entering the whiteboard room. If IMAuthParam and TRTCAuthParam are not specified, this user ID is used for operations such as logging in to the IM application, joining an IM group, and entering the room for TRTC whiteboard push.The ID cannot exceed 60 bytes in length and must be an unused ID. The whiteboard push service uses the user ID to enter the room for whiteboard audio/video push. If this ID is already used in another scenario, the other scenario and whiteboard push service will conflict, affecting the pushing operation. |
PushUserSig | Yes | String | User's IM signature corresponding to the PushUserId. |
Whiteboard | No | Whiteboard | Whiteboard parameters, such as the width, height, and background color of the whiteboard. |
AutoStopTimeout | No | Integer | Whiteboard push timeout. Unit: seconds. Valid range: [300,259200]. Default value: 1800. If no operation is performed on the whiteboard for the specified period of time, the whiteboard push service automatically stops whiteboard push. |
AutoManageBackup | No | Boolean | Specifies whether to synchronize operations on the primary whiteboard push task to the backup task. |
Backup | No | WhiteboardPushBackupParam | Parameters of the backup whiteboard push task. After the backup parameters are specified, the whiteboard push service adds a relayed video stream. That is, there are two video streams on the whiteboard in the same room. |
PrivateMapKey | No | String | Advanced permission control parameter in TRTC. If the advanced permission control feature is enabled in TRTC, this parameter is required. |
VideoFPS | No | Integer | Frame rate of the whiteboard push video. Valid range: [0,30]. Default value: 20. Unit: fps. |
VideoBitrate | No | Integer | Whiteboard push bitrate. Valid range: [0,2000]. Default value: 1200. Unit: kbps. The bitrate specified here is a reference value. During actual push, a dynamic bitrate is used. The actual bitrate does not remain the specified value but rather fluctuates around it. |
AutoRecord | No | Boolean | Specifies whether to automatically record the whiteboard push when the recording mode in TRTC is set to SubscribeStreamUserIds .Default value: false . If you need to enable automatic whiteboard push recording, set this parameter to true .If the recording mode in TRTC is set to Global Auto Recording , ignore this parameter. |
UserDefinedRecordId | No | String | ID of the whiteboard push recording. The ID is filled in the userdefinerecordid parameter in the callback message after cloud recording is complete in TRTC, helping you identify the recording callback and locate the video file in VOD media resource management.The value can be up to 64 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-). After this parameter is set, automatic whiteboard push recording is enabled regardless of the value of the AutoRecord parameter.Default RecordId generation rule: urlencode(SdkAppID_RoomID_PushUserID) Example: SdkAppID = 12345678,RoomID = 12345,PushUserID = push_user_1 Therefore: RecordId = 12345678_12345_push_user_1 |
AutoPublish | No | Boolean | Specifies whether to enable automatic relay whiteboard push when the relay push mode in TRTC is set to SubscribeRelayUserIds .Default value: false . If you need to enable automatic relay whiteboard push, set this parameter to true .If the recording mode in TRTC is set to Global Auto Relay , ignore this parameter. |
UserDefinedStreamId | No | String | Stream ID used by TRTC for relay whiteboard push. With this ID, you can stream the user’s audio/video by using the domain name and standard streaming solution (FLV or HLS) in TRTC. The value can be up to 64 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-). After this parameter is set, automatic relay whiteboard push is enabled regardless of the value of the AutoPublish parameter.Default StreamID generation rule: urlencode(SdkAppID_RoomID_PushUserID_main) Example: SdkAppID = 12345678,RoomID = 12345,PushUserID = push_user_1 Therefore, StreamID = 12345678_12345_push_user_1_main |
ExtraData | No | String | Internal parameter. You can ignore this parameter. |
TRTCRoomId | No | Integer | TRTC room ID of the numeric type. Valid range: (1,4294967295). If RoomId and TRTCRoomId are both specified, the value of TRTCRoomId takes priority as the room ID for TRTC whiteboard push. If the TRTCRoomIdStr parameter is specified, this parameter is ignored. |
TRTCRoomIdStr | No | String | TRTC room ID of the string type. If TRTCRoomIdStr is specified, its value takes priority as the room ID for TRTC whiteboard push. |
IMAuthParam | No | AuthParam | IM authentication parameters. If the ID of the IM application used by whiteboard messages is different from SdkAppId of the whiteboard application, specify this parameter to provide authentication information of the IM application. If this parameter is specified, the whiteboard push service preferably uses the SdkAppId value in this parameter as the transmission channel for whiteboard messages. If this parameter is left empty, the SdkAppId value in the common parameters is used. |
TRTCAuthParam | No | AuthParam | TRTC authentication parameters, used for room entrance authentication for TRTC push. If the ID of the TRTC application to which the target TRTC room belongs is different from SdkAppId of the whiteboard application, specify this parameter to provide authentication information of the TRTC application. If this parameter is specified, the whiteboard push service preferably uses the SdkAppId value in this parameter as the ID of the target TRTC application. If this parameter is left empty, the SdkAppId value in the common parameters is used. |
TRTCEnterRoomMode | No | String | This parameter is available only to users in the allowlist for trial. TRTC room entrance mode for whiteboard push. Default value: TRTCAppSceneVideoCall .TRTCAppSceneVideoCall : This scenario is most suitable when there are two or more people on a video call. The internal encoders and network protocols are optimized for video smoothness to reduce call latency and lagging.TRTCAppSceneLIVE : This scenario is most suitable when there is only one person speaking or performing for an online audience, and occasionally multiple people interact with one another through video. The internal encoders and network protocols are optimized for performance and compatibility to deliver better performance and video clarity. |
Parameter Name | Type | Description |
---|---|---|
TaskId | String | Push task ID. |
Backup | String | Result parameters of the backup task. Note: This parameter may return null, indicating that no valid values can be obtained. |
RequestId | String | The unique request ID, which is returned for each request. RequestId is required for locating a problem. |
This example shows you how to create a whiteboard push task.
POST / HTTP/1.1
Host: tiw.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartWhiteboardPush
<Common request parameters>
{
"PushUserId": "tic_push_user_1203_141551",
"PushUserSig": "usersig_of_<tic_push_user_1203_141551>",
"RoomId": "1203",
"SdkAppId": "1400000001"
}
{
"Response": {
"Backup": "{\"RequestId\":\"8e9b2bc4-ec7f-46cd-823b-66676e2375f8\",\"TaskId\":\"052lfmu5uc3lp0rrqvvb\"}",
"RequestId": "eac6b301-a322-493a-8e36-83b295459397",
"TaskId": "bj0mt2l23osdj300hl30"
}
}
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
Error Code | Description |
---|---|
AuthFailure | |
InvalidParameter.BodyParameterTypeUnmatched | The parameter type does not match. |
InvalidParameter.InvalidExtra | The specified special feature does not exist. |
InvalidParameter.RecordParameter | The format of the real-time recording parameter is invalid. |
InvalidParameter.SdkAppIdNotFound | The SdkAppId does not exist or is invalid. |
LimitExceeded.TaskConcurrency | The number of concurrent transcoding or recording tasks exceeds the limit. For more information, see the error description or try again later. |
ResourceInUse.RecordUserId | The recording user account for real-time recording has started another recording task. |
ResourceUnavailable.NotRegistered | TIW is not enabled. |
ResourceUnavailable.ServiceExpired | The account is in arrears or the TIW service has expired. |
UnauthorizedOperation.SdkAppId | The SdkAppId does not exist or does not match the current Tencent Cloud account. |
本页内容是否解决了您的问题?