tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

StartWhiteboardPush

Last updated: 2023-12-07 10:46:27

    1. API Description

    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.

    We recommend you to use API Explorer
    Try it
    API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

    2. Input Parameters

    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 IMAuthParamand 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.

    3. Output Parameters

    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.

    4. Example

    Example1 Starting a whiteboard push task

    This example shows you how to create a whiteboard push task.

    Input Example

    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"
}

    Output Example

    {
    "Response": {
        "Backup": "{\"RequestId\":\"8e9b2bc4-ec7f-46cd-823b-66676e2375f8\",\"TaskId\":\"052lfmu5uc3lp0rrqvvb\"}",
        "RequestId": "eac6b301-a322-493a-8e36-83b295459397",
        "TaskId": "bj0mt2l23osdj300hl30"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    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.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy