Agora Cloud Recording Overview

Agora Cloud Recording is based on the RESTful API. It is configured with API calls in Bubble.

Prerequisites

Create an account with Agora.IO

You must have an account with Agora.IO to interact with the API. Create your development account at: https://docs.agora.io/en

How to find the Agora Console

Where to create a project or find settings for existing projects?

How to setup cloud recording for streaming

To use the recording functionality, you need an Agora account and a storage account (for example, Amazon S3). Here is the guide that will help you set up the Agora cloud recording for your app:

You need to create or use an existing Agora application

💡
How to create a new project? If you want to create a new project, use the "Create" button. This button can be found on the Projects page of the Agora Console.
💡
How to use an existing project? If you want to use an existing project, use the "Config" button. This button can be found in the row with the corresponding project.
Image without caption

Enable cloud recording

  1. Go to the project settings ("Config" button).
  1. Find "Cloud Recording" in Extensions.
  1. Press "Enable" button for Cloud Recording
Image without caption
Image without caption
Image without caption

Enable App Certificate

Scroll to the top and find "Primary Certificate" block
Image without caption
Enable it using the toggle
Image without caption
And confirm action
Image without caption

Copy the App ID and Certificate into the plugin settings

Image without caption
Place App ID and Certificate to the corresponding fields in the plugin tab of your app
Image without caption

Get Authorization header

To use Agora's RESTful API you need to get a Customer ID and Customer Secret Go to RESTful API page.
Image without caption
Image without caption
Use "Add a secret" button
Image without caption
Download Customer Secret
Image without caption
Open downloaded file with any text editor
Image without caption
Now using Customer Key and Customer Secret we can generate Authorization header
These credentials (Customer Key and Secret) must be base64 encoded using the following formula: customerKey:customerSecret - (https://www.base64encode.org/ here you can do it).
Take the resulting code and paste it into the plugin field for authorization with the word “Basic
Example:
Basic NTM0YzU0ZWU0M2MxNDMyNGJkZqa2YjhhMzVlNGI4YmY6MWJhOTc2MGM4MDYyNGRhNWIyOWMzOGVkZGVhOMmU1
Image without caption

Setup Cloud Recording in your Bubble App

On page load create 2 states for Room Name and Unique ID.
Image without caption
Image without caption
Now, create button. This button will be used to start cloud recording.
Image without caption
And setup it workflow:
1) Need to generate token for recording. Use plugin action "Generate recording token".
Image without caption
2) Use API Call named "Get resource ID"
💡
You can find detailed description of action "Get resource ID" in Common API Calls part of this document
Image without caption
3) Store *resourceId *returned by "Get resource ID" in state
Image without caption
4) Use API Call "Start stream cloud recording" to start cloud recording.
💡
You can find detailed description of action "Start stream cloud recording" in Streaming API Calls part of this document
Image without caption
Image without caption
5) Save returned by "Start stream cloud recording" sid in state
Image without caption
Add another button. This button will be used to stop cloud recording.
Image without caption
Setup workflow of this button:
1) Use API Call "Stop stream cloud recording" to stop recording
💡
You can find detailed description of action "Stop stream cloud recording" in Streaming API Calls part of this document
Image without caption
💡
Full setup of stream cloud recording you can see on our demo page: !!!!HERE WILL BE the LINK TO DEMO PAGE!!!!

How to set up cloud recording for a conference

You need to create or use an existing Agora application

💡
How to create a new project? If you want to create a new project, use the "Create" button. This button can be found on the Projects page of the Agora Console.
💡
How to use an existing project? If you want to use an existing project, use the "Config" button. This button can be found in the row with the corresponding project.
Image without caption

Enable cloud recording

  1. Go to the project settings ("Config" button).
  1. Find "Cloud Recording" in Extensions.
  1. Press "Enable" button for Cloud Recording
Image without caption
Image without caption
Image without caption

Copy the App ID into the plugin settings

Image without caption
Place App ID in the plugin tab of your app
Image without caption

Setup cloud recording in your Bubble App

Place the button on the page. Clicking this button recording will be started.
Image without caption
And setup it workflow:
1) Create state with unique id generation
Image without caption
2) Generate *resourceId *using API Call "Get resource ID"
💡
You can find detailed description of action "Get resource ID" in Common API Calls part of this document
Image without caption
3) Start recording using API Call "Start composite cloud recording"
💡
You can find detailed description of action "Start composite cloud recording" in Conference API Calls part of this document
Image without caption
4) Store in states resourceId and sid
Image without caption
Add another button to the page. This button will be used to stop cloud recording.
Image without caption
And setup it workflow:
1) Use API Call "Stop composite cloud recording"
💡
You can find detailed description of action "Stop composite cloud recording" in Conference API Calls part of this document
Image without caption
💡
Full setup of conference cloud recording you can see on our demo page: !!!!HERE WILL BE LINK TO DEMO PAGE!!!!

Common API Сalls

💡
Common API Calls is used for both conference and streaming recordings

Get resource ID

Image without caption
Title
Description
appid
Your App ID
unicID
A string that contains the UID of the recording client, for example "527841".
resourceExpiredHour
Time limit (in hours) for the Cloud Recording RESTful API calls. It must be between 1 and 720
channel_name
Set the name of the channel to be recorded
Returned value:
resourceId - String. The resource ID for cloud recording. The resource ID is valid for five minutes.

Query status

Query status method works only with an ongoing recording session. If you call query after a recording ends or after, it starts with an error, you get a 404 (Not Found) error.
Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID is returned by the Get resource ID method.
sID
The recording ID created by the Start composite cloud recording or one of Start stream cloud recording methods.
mode
The recording mode. Supports individual mode (individual) or composite mode (mix).individual - is used for stream (individual) recording mix- is used for conferece (composite) recording
Returned values:
  • resourceId - String. The resource ID for cloud recording. The resource ID is valid for five minutes.
  • sid - String. The recording ID. The unique identification of the current recording.
  • serverResponse status - Number. The status of the cloud service.
  • serverResponse fileList - When fileListMode is "string", fileList is a string that represents the filename of the M3U8 file. When fileListMode is "json", fileList is a JSONArray that contains the details of each recorded file.
  • serverResponse fileListMode -  String. The data type of fileList
  • serverResponse sliceStartTime - Number. The Unix time (ms) when the recording starts.
serverResponse status** codes and descriptions:**
  • 0: The cloud service has not started.
  • 1: The initialization is complete.
  • 2: The cloud service is starting.
  • 3: The cloud service is partially ready.
  • 4: The cloud service is ready.
  • 5: The cloud service is in progress.
  • 6: The cloud service receives the request to stop.
  • 7: The cloud service stops.
  • 8: The cloud service exits.
  • 20: The cloud service exits abnormally.

Streaming API Calls

💡
Individual Recording - Records the audio and video of each user ID in separate files and uploads the recorded files to a third-party cloud storage service.

Start stream cloud recording

Start audio and video recording in a channel
Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID returned by the Get resource ID method
channel_name
Set the name of the channel to be recorded
token
String. The dinamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application.
storage_accessKey
String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.
storage_region
Number. The region information is specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type-
storage_bucket
String. The bucket name of the third-party cloud storage.
storage_secretKey
String. The secret key of the third-party cloud storage.
Directory_1
Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9 |
| storage_vendor | Number. The third-party cloud storage vendor.Vendor numbers:* 0: Qiniu Cloud
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the Get resource ID method. | | Directory_2 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", and Directory_2 = "directory2", Agora Cloud Recording will add the prefix "directory1/directory2/" before the name of the recorded file, that is, directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9 |
Returned values:
  • resourceId - String. The resource ID for cloud recording.
  • sid - String. The recording ID. The unique identification of the current recording.

Start stream cloud recording (video only)

Start video recording in a channel
Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID returned by the Get resource ID method
channel_name
Set the name of the channel to be recorded
token
String. The dinamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application.
storage_accessKey
String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.
storage_region
Number. The region information specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type-
storage_bucket
String. The bucket name of the third-party cloud storage.
storage_secretKey
String. The secret key of the third-party cloud storage.
Directory_1
Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9 |
| storage_vendor | Number. The third-party cloud storage vendor.Vendor numbers:* 0: Qiniu Cloud
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the Get resource ID method. |
Returned values:
  • resourceId - String. The resource ID for cloud recording.
  • sid - String. The recording ID. The unique identification of the current recording.

Start stream cloud recording (audio only)

Start audio recording in a channel
Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID returned by the Get resource ID method
channel_name
Set the name of the channel to be recorded
token
String. The dinamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application.
storage_accessKey
String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.
storage_region
Number. The region information specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type-
storage_bucket
String. The bucket name of the third-party cloud storage.
storage_secretKey
String. The secret key of the third-party cloud storage.
Directory_1
Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9 |
| storage_vendor | Number. The third-party cloud storage vendor.Vendor numbers:* 0: Qiniu Cloud
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the Get resource ID method. |
Returned values:
  • resourceId - String. The resource ID for cloud recording.
  • sid - String. The recording ID. The unique identification of the current recording.

Stop stream cloud recording

Stop recording on the channel
Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID returned by the Get resource ID method.
sID
The recording ID created by the start method.
unicID
A string that contains the user ID of the recording client. Must be the same uid used in the Get resource ID method.
channel_name
Name of the channel to be recorded.
  • resourceId - String. The resource ID for cloud recording.
  • sid - String. The recording ID. The unique identification of the current recording.

Conference API Calls

💡
Composite recording - Records the audio and video of multiple user IDs in a single file and uploads the recorded file to a third-party cloud storage service.

Start composite cloud recording

Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID returned by the Get resource ID method
channel_name
Set the name of the channel to be recorded
token
String. The dynamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application.
storage_accessKey
String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.
storage_region
Number. The region information is specified for the third-party cloud storage. The recording service only supports regions in the following lists:-unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type--unhandled content type-
storage_bucket
String. The bucket name of the third-party cloud storage.
storage_secretKey
String. The secret key of the third-party cloud storage.
Directory_1
Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", Agora Cloud Recording will add the prefix "directory1/" before the name of the recorded file, that is, directory1/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9 |
| storage_vendor | Number. The third-party cloud storage vendor.Vendor numbers:* 0: Qiniu Cloud
| unicID | A string containing the user ID of the recording client. Must be the same uid used in the Get resource ID method. | | Directory_1 | Sets the path of the recorded files in the third-party cloud storage. For example, if Directory_1 = "directory1", and Directory_2 = "directory2", Agora Cloud Recording will add the prefix "directory1/directory2/" before the name of the recorded file, that is, directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:* The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9 |
Returned values:
  • resourceId - String. The resource ID for cloud recording.
  • sid - String. The recording ID. The unique identification of the current recording.

Stop composite cloud recording

Image without caption
Title
Description
appID
Your App ID
resourceID
The resource ID is returned by the Get resource ID method.
sID
The recording ID is created by the start method.
unicID
A string that contains the user ID of the recording client. Must be the same uid used in the Get resource ID method.
channel_name
Name of the channel to be recorded.
  • resourceId - String. The resource ID for cloud recording.
  • sid - String. The recording ID. The unique identification of the current recording.
  • serverResponse fileListMode - String. The data type of fileList
  • serverResponse fileList - When fileListMode is "string", fileList is a string that represents the filename of the M3U8 file. When fileListMode is "json", fileList is a list that contains the details of each recorded file.
  • serverResponse uploadingStatus String. The upload status.
    • "uploaded": All the recorded files are uploaded to the third-party cloud storage.
    • "backuped": Some of the recorded files fail to upload to the third-party cloud storage and upload to Agora Cloud Backup instead. Agora Cloud Backup automatically uploads these files to your cloud storage.
    • "unknow": Unknown status.