Cloud recording: Callbacks

Callbacks provide updates about recording and uploading. You can use callbacks to find a recording. You can also use them to show the status of a recording in your app.

To receive callbacks, include a unique callback URL in the request to start recording. See the Quickstart for a sample workflow.

There are four types of callbacks:

Recording started
Recording stopped
Recording uploaded (includes a link to the file)
Recording upload failed

Callback format

Callbacks are POST requests with JSON in the body.

All callbacks contain the elements in this table. Some callbacks also have extra elements, which you can see in the sections below.

Element		Type	Description
`event`		String	Name of the event. Possible values: `recording-started` `recording-stopped` `recording-uploaded` `recording-upload-failed`
`timestamp`		Number	Current time. Unix epoch time in milliseconds.
`recording`		Object	Object with recording details. This object includes a `reason` string or `location` object for some callbacks.
┗	`url`	String	A unique URL that identifies the recording instance. For the URL you use to stop recording, see Start recording. For the address of the saved file, see Recording uploaded below.
┗	`state`	String	State of the recording.
┗	`startTime`	Number	Start time of the recording. Unix epoch time in milliseconds.
┗	`elapsedTime`	Number	Duration of the recording in milliseconds.

Recording started

You receive this callback when a recording starts.

{
  "event": "recording-started",
  "timestamp": 1665460533516,
  "recording": {
    "url": "http://vandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com:8080/recording/1677608374942-0-503309",
    "state": "started",
    "startTime": 1665460533516,
    "elapsedTime": 0
  }
}

Recording stopped

You receive this callback when a recording stops.

{
  "event": "recording-stopped",
  "timestamp": 1672807265466,
  "recording": {
    "url": "http://vandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com:8080/recording/1677608374942-0-503309",
    "state": "stopped",
    "startTime": 1665460533516,
    "elapsedTime": 23509,
    "reason": "allPublishersLeft"
  }
}

Extra elements for this callback:

Element	Type	Description
`reason`	String	Possible values: `allPublishersLeft`: Recording stopped because all publishers left. `clientStopped`: The client stopped the recording. `serverError`: Recording stopped due to a server error.

Recording uploaded

You receive this callback when a recording is uploaded successfully.

You can use the address element to find the file.

{
  "event": "recording-uploaded",
  "timestamp": 1677023448142,
  "recording": {
    "url": "http://vandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com:8080/recording/1677608374942-0-503309",
    "state": "stopped",
    "startTime": 1665460533516,
    "elapsedTime": 11115,
    "location": {
      "address": "https://youraccount.s3.amazonaws.com/record_1677608374942-0-503309.m4a",
      "region": "us-east-1"
    }
  }
}

Extra elements for this callback:

Element		Type	Description
`location`		Object	Object for the location of the recording.
┗	`address`	String	Address of the uploaded file.
┗	`region`	String	Region for the S3 bucket.

Recording upload failed

You receive this callback when uploading a recording fails.

In this example, the AWS region us-east-1111 is invalid.

{
  "event": "recording-upload-failed",
  "timestamp": 1677025421982,
  "recording": {
    "url": "http://vandenberg-i-0defaf76088193a3b-eu-central-1.prod.airtime.com:8080/recording/1677608374942-0-503309",
    "state": "stopped",
    "startTime": 1665460533516,
    "elapsedTime": 16260,
    "reason": "Inaccessible host: `youraccount.s3.us-east-1111.amazonaws.com' at port `undefined'. This service may not be available in the `us-east-1111' region."
  }
}

Extra elements for this callback:

Element	Type	Description
`reason`	String	Error message from S3.