Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Update task settings

POST
https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update

After starting a recording task, call this endpoint to update the subscription list, pause or resume web page recording, or update the CDN push address.

info
  • This endpoint is only valid within an active recording session. If the recording was not started successfully or has already ended, the request returns 404.
  • If you need to call update multiple times in succession, wait for the previous update response before sending the next request to avoid unexpected results.

Request​

Path parameters​

appid stringrequired

The App ID of your project.

  • For web page recording mode, enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
resourceid stringrequired

The resource ID obtained from the acquire endpoint.

sid stringrequired

The recording ID obtained from the start endpoint.

mode stringrequired

The recording mode:

Request body​

APPLICATION/JSON
BODYrequired
  • cname stringrequired

    The name of the channel being recorded. Must match the cname used in the acquire request.

  • uid stringrequired

    The UID used by the cloud recording service in the channel. Must match the uid used in the acquire request.

  • clientRequest objectrequired
    Show propertiesHide properties
    • streamSubscribe objectnullable

      Updates the subscription lists. Only applicable in individual recording and composite recording modes.

      Show propertiesHide properties
      • audioUidList objectnullable

        The audio subscription list. Only applicable when streamTypes is 0 or 2.

        Show propertiesHide properties
        • subscribeAudioUids array[string]nullable

          Audio streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeAudioUids.

        • unsubscribeAudioUids array[string]nullable

          Audio streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with subscribeAudioUids.

      • videoUidList objectnullable

        The video subscription list. Only applicable when streamTypes is 1 or 2.

        Show propertiesHide properties
        • subscribeVideoUids array[string]nullable

          Video streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeVideoUids.

        • unsubscribeVideoUids array[string]nullable

          Video streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with subscribeVideoUids.

    • webRecordingConfig objectnullable

      Updates web page recording settings. Only applicable in web page recording mode.

      Show propertiesHide properties
      • onhold booleannullable

        Default: false

        Whether to pause web page recording:

        • true: Pauses recording and stops generating slice files.
        • false: Resumes recording and continues generating slice files.
    • rtmpPublishConfig objectnullable

      Updates the CDN push configuration. Only applicable when pushing web page recording to CDN.

      Show propertiesHide properties
      • outputs array[object]nullable
        Show propertiesHide properties
        • rtmpUrl stringnullable

          The CDN URL to push the stream to. Only RTMP and RTMPS protocols are supported. A maximum of one stream can be pushed to CDN at a time.

    • storageConfig objectnullable

      Updates the third-party cloud storage configuration. Use this to refresh an expiring stsToken.

      Show propertiesHide properties
      • vendor numberrequired

        Third-party cloud storage platform:

        • 1: Amazon S3
        • 2: Alibaba Cloud
        • 3: Tencent Cloud
        • 5: Microsoft Azure
        • 6: Google Cloud
        • 7: Huawei Cloud
        • 8: Baidu IntelligentCloud
        • 11: S3-compatible storage. Specify the domain name in extensionParams.endpoint.
      • region numberrequired

        The region of the third-party cloud storage.

        info

        To ensure upload success and real-time performance, the cloud storage region must match the region of the server where you initiate the request. See Third-party cloud storage regions.

      • bucket stringrequired

        The cloud storage bucket name. Must comply with the naming rules of the corresponding cloud storage service.

      • accessKey stringrequired

        The access key for the third-party cloud storage.

      • secretKey stringrequired

        The secret key for the third-party cloud storage.

      • stsToken stringnullable

        A temporary security token issued by the cloud provider's Security Token Service (STS), granting limited access to cloud storage resources. Currently supported only for Amazon S3 (1), Alibaba Cloud (2), and Tencent Cloud (3).

      • stsExpiration numbernullable

        The stsToken expiration time as a Unix timestamp in seconds.

        • Use Uint64 storage to avoid timestamp overflow.
        • Set the longest possible validity period when applying the token. The minimum validity period is 4 hours.
        • If the recording task runs longer than 1 hour, reapply a new stsToken every 60 minutes and call update again to refresh the storageConfig.
      • fileNamePrefix array[string]nullable

        The storage path prefix for recorded files. For example, setting ["directory1","directory2"] results in a file name prefix of directory1/directory2/. The total prefix length, including slashes, cannot exceed 128 characters. Supported characters: lowercase letters a-z, uppercase letters A-Z, digits 0-9.

      • extensionParams objectnullable

        Encryption and tagging settings applied to uploaded recording files by the cloud storage service.

        Show propertiesHide properties
        • sse stringrequired

          The encryption mode for uploaded files. Applicable to Amazon S3 only. See the Amazon S3 documentation.

          • kms: KMS encryption.
          • aes256: AES256 encryption.
        • tag stringrequired

          Tag content applied to uploaded files. Applicable to Alibaba Cloud and Amazon S3 only.

        • endpoint stringnullable

          The domain name for S3 protocol cloud storage. This field is required when you set vendor to 11.

Response​

Response body​

  • If the returned status code is 200, the request was successful.

    OK
    • cname string

      The name of the channel being recorded.

    • uid string

      The UID used by the cloud recording service in the RTC channel.

    • resourceId string

      The resource ID used by cloud recording.

    • sid string

      The recording ID, identifying the current recording session.

  • If the returned status code is not 200, the request failed. See Response status codes for troubleshooting.

Authorization

This endpoint requires Basic Auth.

Request example


_18
curl --request POST \
_18
--url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update \
_18
--header 'Authorization: Basic <credentials>' \
_18
--header 'Content-Type: application/json' \
_18
--data '{
_18
"cname": "httpClient463224",
_18
"uid": "527841",
_18
"clientRequest": {
_18
"streamSubscribe": {
_18
"audioUidList": {
_18
"subscribeAudioUids": ["#allstream#"]
_18
},
_18
"videoUidList": {
_18
"unsubscribeVideoUids": ["444", "555", "666"]
_18
}
_18
}
_18
}
_18
}'

Response example


_6
{
_6
"cname": "httpClient463224",
_6
"uid": "527841",
_6
"resourceId": "JyvK8nXHuV1BE.....",
_6
"sid": "38f8e3c......"
_6
}