Recording In-app voice calls

Overview

With the Sinch platform, you’re able to control the recording of the calls using the Callback API.

Call recording

To enable recording of calls, set the recording flag to true in the Action of the SVAML, in the ICE callback response. Recording options are always required to specify details about the recording.

Recording options

The recording options are sent as part of the callback response when you want to enable recording of a call or a conference.

Copy

Copied

[RecordingOptions]
string - destinationUrl
string - credentials
string - format
bool - notificationEvents
object - [transcriptionOptions]: {
        bool    - enabled,
        string  - locale
        }

example ICE response

Copy

Copied

{
  "action": {
    "name": "connectMXP",
    "destination": {
        "type": "username",
        "endpoint": "johndoe"
    },
    "record": true,
    "recordingOptions": {
      "destinationUrl": "s3://sinch-storage/voice-recordings/my-recording.mp3",
      "credentials": "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY:eu-central-1",
      "notificationEvents": true
    }
  }
}

Property	Description
destinationUrl	Where the recording file should be stored. Sinch supports the following destinations: Amazon S3 Microsoft Azure Blob Storage Google Cloud Storage To read more about how to configure each of these destinations, see the DestinationURL section.
credentials	Specifies the information required for the Sinch platform to authenticate and/or authorize in the destination service in order to be able to store the file.
format	An optional property that specifies the format of the recording file. Default value is `mp3`.
notificationEvents	An optional property that specifies if Sinch should send your backend events when the call recording is finished and when the file is available in the destination URL specified. For more information about notification events, see the Notification Events section. Default value is “true”

DestinationURL

This property is a URI and specifies where the recording file should be stored. Sinch supports multiple platforms for storage and will continue to enable new platforms in the future:

Amazon S3
Microsoft Azure Blob Storage
Google Cloud Storage

Note:

You can, but are not required to specify the filename in the destination. If there is no filename specified in the URI, Sinch will generate a unique name with the following format: (UTCDateyyyyMMddHHmmss)\(applicationKey)_(callId).(format).

Warning!

Sinch doesn't check if a filename exists in the specified path and will overwrite any existing file with the same filename.

DestinationURL: Amazon S3

Using the recordingOptions property, you can direct the Sinch platform to store the recording file to an Amazon S3 bucket. The destinationUrl property should be specified with a s3 schema, followed by the bucket name and optionally destination folder and file:

s3://bucket_name/[[folder]/[file]]

Using the Amazon S3 as a destination requires that the credentials be specified. The format of the credentials is defined with:

(AwsAccessKey):(AwsSecretKey):(AwsRegion)

Example

Copy

Copied

{
  "recordingOptions": {
    "destinationUrl": "s3://sinch-storage/voice-recordings/my-recording.mp3",
    "credentials": "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY:eu-central-1",
    "notificationEvents": true
  }
}

Svaml action example

Copy

Copied

{
"action": {
   "name": "connectMxp",
   ...
   "recordingOptions": {
      "destinationUrl": "s3://sinch-storage/voice-recordings/my-recording.mp3",
      "credentials": "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY:eu-central-1",
      "notificationEvents": true
      }
    }
}

Note:

It's recommended that the credentials you specify authorize the Sinch platform to only write to the destination bucket. Sinch will never request read permissions.

DestinationURL: Microsoft Azure Blob Storage

To store your recordings to a Microsoft Azure Blob Storage container, use the azure schema identifier in the destinationUrl:

Copy

Copied

azure://account_name/container_name/file.ext

You must also provide the access key in the credentials property.

Example

Copy

Copied

{
  "recordingOptions": {
    "destinationUrl": "azure://my-account/test-container/my-recording.mp3",
    "credentials": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==",
    "notificationEvents": true
  }
}

Svaml action example

Copy

Copied

{
    "action": {
        "name": "connectMxp",
    ...
        "recordingOptions": {
            "destinationUrl": "azure://my-account/test-container/my-recording.mp3",
            "credentials": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+Pw==",
            "notificationEvents": true
            }
        }
}

DestinationURL: Google Cloud Storage

Using the recordingOptions property, you can direct the Sinch platform to store the recording file to an GCP Storage bucket. The destinationUrl property should be specified with a gs schema, followed by the bucket name and optionally destination folder and file:

gs://bucket_name/[[folder]/[file]]

Using the Google Cloud Storage as a destination requires that the credentials be specified. The format of the credentials is defined with:

(Access_key):(Secret) Cloud Storage Interoperability key and secret must be used.

See GCP Console link

Example

Copy

Copied

{
  "recordingOptions": {
    "destinationUrl": "gs://sinch-storage/voice-recordings/my-recording.mp3",
    "credentials": "ACCESS_KEY:SECRET",
    "notificationEvents": true
  }
}

Svaml action example

Copy

Copied

{
"action": {
   "name": "connectPstn",
   ...
   "recordingOptions": {
      "destinationUrl": "gs://sinch-storage/voice-recordings/my-recording.mp3",
      "credentials": "ACCESS_KEY:SECRET",
      "notificationEvents": true
      }
    }
}

Note:

It's recommended that the credentials you specify authorize the Sinch platform to only write to the destination bucket. Sinch will never request read permissions.

Notification events

Two notification events are sent to the partner’s backend if notificationEvents are enabled:

Notification event	Description
`recording_finished`	Indicates that the recording for the specified call has been stopped either by a Manage Call request or because the call has ended.
`recording_available`	Indicates that the recording file is available in the specified `destinationUrl` and can be retrieved.

Example call recording

Copy

Copied

    {
        "event": "notify",
        "callid": "01234567-89ab-cdef-fedc-ba9876543210",
        "version": 1,
        "type": "recording_finished"
    }

    {
        "event": "notify",
        "callid": "01234567-89ab-cdef-fedc-ba9876543210",
        "version": 1,
        "type": "recording_available",
        "destination":"https://www.sinch.com/calling/v1/recording/201801010000_01234567-89ab-cdef-fedc-ba9876543210_01234567-89ab-cdef-fedc-ba9876543210.mp3"
    }