record

Record the call audio in the foreground pausing further SWML execution until recording ends. Use this, for example, to record voicemails. To record calls in the background in a non-blocking fashion, use the record_call

Properties

record

objectRequired

An object that accepts the following properties.

record.stereo

booleanDefaults to false

Whether to record in stereo mode

record.format

stringDefaults to wav

Format ("wav", "mp3", or "mp4")

record.direction

stringDefaults to speak

Direction of the audio to record: "speak" for what party says, "listen" for what party hears

record.terminators

stringDefaults to #

String of digits that will stop the recording when pressed

record.beep

booleanDefaults to false

Whether to play a beep before recording

record.input_sensitivity

numberDefaults to 44.0

How sensitive the recording voice activity detector is to background noise. A larger value is more sensitive. Allowed values from 0.0 to 100.0.

record.initial_timeout

numberDefaults to 4.0 seconds

How long, in seconds, to wait for speech to start?

record.end_silence_timeout

numberDefaults to 5.0 seconds

How much silence, in seconds, will end the recording?

record.max_length

number

Maximum length of the recording in seconds.

record.status_url

string

HTTP or HTTPS URL to deliver record status events. Learn more about status callbacks.

Variables

Set by the method:

record_url: (out) the URL of the newly created recording.
record_result: (out) success | failed.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.record for this method.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing recording-specific parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.control_id

string

The control ID for this record operation.

params.state

string

The current recording state. Valid values: recording, paused, finished, no_input, error.

params.url

string

URL to download the recording.

params.duration

number

Recording duration in seconds. Present when state is finished or no_input.

params.size

number

Recording file size in bytes. Present when state is finished or no_input.

params.recording_id

string

The unique identifier for the recording. Present when available.

params.start_time

number

Unix timestamp (seconds, float) when the recording started. Present when the recording has ended.

params.end_time

number

Unix timestamp (seconds, float) when the recording ended. Present when the recording has ended.

params.pause_behavior

string

How paused recording handles audio. Only present when state is paused. Valid values: silence, skip.

params.record

object

Recording configuration details.

record.audio.format

string

Recording format. Valid values: wav, mp3.

record.audio.direction

string

Direction of the audio recorded: speak or listen.

record.audio.stereo

boolean

Whether the recording was made in stereo mode.

Raw JSON example

1 {
2   "event_type": "calling.call.record",
3   "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4   "timestamp": 1640000000.123,
5   "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6   "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7   "params": {
8     "state": "finished",
9     "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10     "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11     "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
12     "url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download",
13     "duration": 15,
14     "size": 248320,
15     "recording_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
16     "start_time": 1640000000.123,
17     "end_time": 1640000015.623,
18     "record": {
19       "audio": {
20         "format": "wav",
21         "direction": "speak",
22         "stereo": false
23       }
24     }
25   }
26 }

Examples

Record some audio and play it back

1 version: 1.0.0
2 sections:
3   main:
4     - play:
5         url: 'say:Start speaking after the beep. Press hash to end recording.'
6     - record:
7         end_silence_timeout: 3
8         beep: true
9     - play:
10         url: 'say:Recording ${record_result}. Playing back recording:'
11     - play:
12         url: '${record_url}'

Properties

record

objectRequired

An object that accepts the following properties.

record.stereo

booleanDefaults to false

Whether to record in stereo mode

record.format

stringDefaults to wav

Format ("wav", "mp3", or "mp4")

record.direction

stringDefaults to speak

Direction of the audio to record: "speak" for what party says, "listen" for what party hears

record.terminators

stringDefaults to #

String of digits that will stop the recording when pressed

record.beep

booleanDefaults to false

Whether to play a beep before recording

record.input_sensitivity

numberDefaults to 44.0

How sensitive the recording voice activity detector is to background noise. A larger value is more sensitive. Allowed values from 0.0 to 100.0.

record.initial_timeout

numberDefaults to 4.0 seconds

How long, in seconds, to wait for speech to start?

record.end_silence_timeout

numberDefaults to 5.0 seconds

How much silence, in seconds, will end the recording?

record.max_length

number

Maximum length of the recording in seconds.

record.status_url

string

HTTP or HTTPS URL to deliver record status events. Learn more about status callbacks.

Variables

Set by the method:

record_url: (out) the URL of the newly created recording.
record_result: (out) success | failed.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.record for this method.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing recording-specific parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.control_id

string

The control ID for this record operation.

params.state

string

The current recording state. Valid values: recording, paused, finished, no_input, error.

params.url

string

URL to download the recording.

params.duration

number

Recording duration in seconds. Present when state is finished or no_input.

params.size

number

Recording file size in bytes. Present when state is finished or no_input.

params.recording_id

string

The unique identifier for the recording. Present when available.

params.start_time

number

Unix timestamp (seconds, float) when the recording started. Present when the recording has ended.

params.end_time

number

Unix timestamp (seconds, float) when the recording ended. Present when the recording has ended.

params.pause_behavior

string

How paused recording handles audio. Only present when state is paused. Valid values: silence, skip.

params.record

object

Recording configuration details.

record.audio.format

string

Recording format. Valid values: wav, mp3.

record.audio.direction

string

Direction of the audio recorded: speak or listen.

record.audio.stereo

boolean

Whether the recording was made in stereo mode.

Raw JSON example

1 {
2   "event_type": "calling.call.record",
3   "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4   "timestamp": 1640000000.123,
5   "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6   "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7   "params": {
8     "state": "finished",
9     "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10     "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11     "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
12     "url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download",
13     "duration": 15,
14     "size": 248320,
15     "recording_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
16     "start_time": 1640000000.123,
17     "end_time": 1640000015.623,
18     "record": {
19       "audio": {
20         "format": "wav",
21         "direction": "speak",
22         "stereo": false
23       }
24     }
25   }
26 }

Examples

Record some audio and play it back

1 version: 1.0.0
2 sections:
3   main:
4     - play:
5         url: 'say:Start speaking after the beep. Press hash to end recording.'
6     - record:
7         end_silence_timeout: 3
8         beep: true
9     - play:
10         url: 'say:Recording ${record_result}. Playing back recording:'
11     - play:
12         url: '${record_url}'

1	{
2	"event_type": "calling.call.record",
3	"event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4	"timestamp": 1640000000.123,
5	"project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6	"space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7	"params": {
8	"state": "finished",
9	"control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
10	"call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
11	"node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
12	"url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download",
13	"duration": 15,
14	"size": 248320,
15	"recording_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
16	"start_time": 1640000000.123,
17	"end_time": 1640000015.623,
18	"record": {
19	"audio": {
20	"format": "wav",
21	"direction": "speak",
22	"stereo": false
23	}
24	}
25	}
26	}

1	version: 1.0.0
2	sections:
3	main:
4	- play:
5	url: 'say:Start speaking after the beep. Press hash to end recording.'
6	- record:
7	end_silence_timeout: 3
8	beep: true
9	- play:
10	url: 'say:Recording ${record_result}. Playing back recording:'
11	- play:
12	url: '${record_url}'