Record

Definition

The Record verb records the conversation and stores it as an audio file in the specified container. Once the recording has ended, CarrierX will make a POST or GET request to the action URL.

warning

The verbs listed after the Record verb, which has an action URL specified, will not be executed.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions. If the recording fails, a POST or GET will be sent to the errorAction URL.

info

Accounts come with a limited amount of storage by default. To add more storage, email to support@carrierx.com or contact your account representative.

tip

Refer to our Storage and Recording quick start guide to learn more about how you can use the Record verb for storage and recording options.

Supported Attributes

These attributes can be used to modify the Record verb. They are inserted as name-value pairs in the start-tag.

Attribute	Data Type	Description
action	string	The link to another set of FlexML instructions. This is the link that will be requested after the recording has finished. URLs entered into this field can be absolute or relative. The type of request to this URL is set as the `method` value. Note that if there is no recording or the recording was empty after silence trim (if it was enabled), action does not execute and the next verb following is executed.
backgroundAudioLoop	integer	This attribute defines how many times `backgroundAudioUrl` will be repeated.
backgroundAudioUrl	string	This audio file plays during the recording, but is not recorded. For example, the called party will hear this file, but the recording will only include the audio from the calling party side.
callbackUrl	string	The URL for the callback. Setting the `callbackUrl` will enable accessing data about the recording after it has ended.
containerSid	string	The secure ID of the storage container. If a `fileSid` is specified, this `containerSid` should be left blank and will be ignored.
direction	string	Determines which leg of the call to record. Values accepted in this field are: `any` to record both calling and called parties; `in` to record the calling party only; `out` to record the called party only. The default value is `any`, meaning that both legs are recorded.
errorAction	string	The URL containing the executable FlexML instructions that will be requested if the recording fails.
errorMethod	string	The method used to request the `errorAction` URL containing the executable FlexML instructions if the recording fails.
fileFormat	string	Set as the type of file that will be stored as a recording. Accepted file formats are `wav`, `mp3`, and `ul`. The default value is `wav`.
fileMode	string	This value defines whether new recordings will be appended to the storage file, or will overwrite the existing recordings in the file. Values accepted in this field are `append` and `overwrite`. The default value is `append`.
fileSid	string	The secure ID of the storage file that the recording should be saved to. This is an existing file specified that will override any specified `containerSid`.
finishOnKey	string	The key to press to end the recording. Values accepted in this field are: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `#`, and `*`. By default, pressing any valid key will end the recording. The `none` string value can be passed to disable this feature. Note that multiple values can be passed into a single string. For example, if the `123` string is passed as the `finishOnKey` value, then pressing `1`, `2`, or `3` will end the recording.
integerKey1	integer	An optional integer identifier that can be used for referential purposes. This value is stored as the `integer_key_1` value in the File object.
integerKey2	integer	An optional integer identifier that can be used for referential purposes. This value is stored as the `integer_key_2` value in the File object.
lifecycleAction	string	An action that will be performed for the recording file once the `lifecycleTtl` value is exceeded. The default value is `delete`.
lifecycleTtl	integer	The time in seconds before the `lifecycleAction` is executed for the recording file.
maxLength	integer	The maximum length of the recording, in seconds. Integers entered into this field must be greater than or equal to `1`.
method	string	The type of request made to the `action` URL. Values accepted in this field are `POST` or `GET`. The default value is `POST`.
playBeep	boolean	Plays a beep sounds to indicate that a recording has started. If set to `false`, no beep sound is played. The default value is `false`.
recordingStatusCallback	string	The URL where the callback will be sent after the recording has ended.
recordingStatusCallbackEvent	string	The recording status events on which the callback will be sent to the `recordingStatusCallback` URL. Values accepted in this field are: `completed`, `failed` and `absent`. Inside a request, these values are separated by commas without spaces. The default value is `completed,failed`.
recordingStatusCallbackMethod	string	The method, either `POST` or `GET`, that the callback to `recordingStatusCallback` is sent. The default is `POST`.
recordSession	boolean	If this attribute is set to `true`, the whole session will be recorded in the background. The default value is `false`.
stringKey1	string	An optional string identifier that can be used for referential purposes. This value is stored as the `string_key_1` value in the File object.
stringKey2	string	An optional string identifier that can be used for referential purposes. This value is stored as the `string_key_2` value in the File object.
timeout	integer	The number of seconds of silence allowed before the recording is terminated. Integers entered into this field must be greater than or equal to `1`. The default value is `5`.
transcribe	boolean	Transcribes the audio to the human readable text representation. The default value is `false`. Please note that this is a paid feature. Contact technical support at support@carrierx.com for more information about this.
transcribeCallback	string	The URL where the callback will be sent after the transcription is finished.
transcribeLowConfidenceWordReplacement	string	The word or character that will be used to replace the words with low confidence (that was hard to recognize for the system) in the resulting transcription. The default value is `_`.
transcribeLowConfidenceWordThreshold	number	The confidence level below which the word is considered unrecognized and is replaced with the `transcribeLowConfidenceWordReplacement` word/character. Values accepted in this field are numbers between `0` and `1`. The default value is `0.01`.
transcribeTimeout	integer	The time in seconds during which the system will wait for the transcription callback. If this time is exceeded and no transcription is ready, the system will send the callback with the `timeout` status.
trim	string	Determines whether or not silence is removed from the beginning or ending of a recording. To keep the silence in the recording, set this field to `do-not-trim`. The default value is `trim-silence`.

Example

In this example, a background recording begins because recordSession is set to true. The recording is saved in the specified containerSid. Note that by default, the container used to store the recording will be the one specified in the Endpoint object. However, the container can be overridden by assigning a containerSid, as is shown here. The system will automatically generate a file inside the container, unless a fileSid is specified. The recording will fail if the container or file does not exist or is full.

<Response>
  <Record containerSid="ea55039a-3ee4-48cd-a1ff-dfb7751f1cec" recordSession="true"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Supported External Storage

The following external storage services are supported to store the recording data:

Amazon Simple Storage Service (AWS S3)
Google Cloud Platform (GCP)
Microsoft Azure Blob storage

You will need to provide the credentials and specify the storage location for each of the external storage used. Only one external storage can be used at a time. Refer to the tables below to learn what parameters you need to specify for each storage type.

Amazon Simple Storage Service

Attribute	Data Type	Description
awsAccessKey required	string	The access key used to access AWS S3.
awsBucketName required	string	The bucket name where the recording will be stored.
awsSecretKey required	string	The secret key used to access AWS S3.

Example

In this example, the background recording is saved to the specified awsBucketName of Amazon S3.

<Response>
  <Record recordSession="true" awsAccessKey="_AWS_ACCESS_KEY_" awsBucketName="_AWS_BUCKET_NAME_" awsSecretKey="_AWS_SECRET_ACCESS_KEY_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Google Cloud Platform

Attribute	Data Type	Description
gcpAccessToken	string	The access token used to access Google Cloud Platform. This attribure is only required if you do not specify `gcpRefreshToken`, `gcpClientId`, and `gcpClientSecret`.
gcpBucketName required	string	The bucket name where the recording will be stored.
gcpClientId	string	The client ID used to access Google Cloud Platform. This attribute is only required if you do not specify `gcpAccessToken`.
gcpClientSecret	string	The client secret used to access Google Cloud Platform. This attribute is only required if you do not specify `gcpAccessToken`.
gcpProject required	string	The project that will be used to store the recording.
gcpRefreshToken	string	The refresh token used to access Google Cloud Platform. This attribute is only required if you do not specify `gcpAccessToken`.

Example

In this example, the background recording is saved to the specified gcpBucketName Google Cloud Platform.

<Response>
  <Record recordSession="true" gcpAccessToken="_GCP_ACCESS_TOKEN_" gcpBucketName="_GCP_BUCKET_NAME_" gcpProject="_GCP_PROJECT_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Microsoft Azure Blob Storage

Attribute	Data Type	Description
azureAccountKey	string	The account key used to access Microsoft Azure Blob storage. This attribute is only required if you do not specify `azureSasToken`.
azureAccountName required	string	The account name used to access Microsoft Azure Blob storage.
azureContainerName required	string	The container name where the recording will be stored.
azureSasToken	string	The SAS token used to access Microsoft Azure Blob storage. This attribute is only required if you do not specify `azureAccountKey`.

Example

In this example, the background recording is saved to the specified azureContainerName of Microsoft Azure Blob Storage.

<Response>
  <Record recordSession="true" azureAccountKey="_AZURE_ACCOUNT_KEY_" azureAccountName="_AZURE_ACCOUNT_NAME_" azureContainerName="_AZURE_CONTAINER_NAME_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Callback Returned Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RecordingDuration": 60,
    "RecordingSid": "ea662226-9f71-44fe-858f-f8b624034974",
    "RecordingStatus": "completed",
    "RecordingUrl": "https://storage.carrierx.com/f/ea662226-9f71-44fe-858f-f8b624034974",
    "To":"15162065337",
    "TranscriptionSid": "cac8582f-db8a-4c4d-82e5-3e8026435a54",
    "TranscriptionStatus": "completed",
    "TranscriptionText": "This is a transcribed recorded call text",
    "TranscriptionUrl": ""
}

The following are additional parameters and values that will be returned in action requests.

Attribute	Data Type	Description
RecordingDuration	integer	The length in seconds of the recording.
RecordingSid	string	The secure ID of the recording file. This can be used with the CarrierX Storage API.
RecordingStatus	string	The recording status. Can be one of the following: `completed`, `failed` or `absent`.
RecordingUrl	string	The URL where the recording is located.
TranscriptionSid	string	The identifier of the transcription file.
TranscriptionStatus	string	The status of the transcription.
TranscriptionText	string	The complete text of the recorded call transcription.
TranscriptionUrl	string	The publicly accessible URL of the transcription. Currently, this field is a placeholder and not used.

info

For a list of the other parameters and values to expect in action requests, refer to the FlexML Call Flow section.

Nesting Rules

You cannot nest other verbs or nouns within the Record verb.
You cannot nest the Record verb within other FlexML verbs.

Definition​

Supported Attributes​

Example​

Supported External Storage​

Amazon Simple Storage Service​

Example​

Google Cloud Platform​

Example​

Microsoft Azure Blob Storage​

Example​

Callback Returned Data​

Nesting Rules​

Definition

Supported Attributes

Example

Supported External Storage

Amazon Simple Storage Service

Example

Google Cloud Platform

Example

Microsoft Azure Blob Storage

Example

Callback Returned Data

Nesting Rules