Skip to navigation
Calling

record

View as MarkdownOpen in Claude

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, "both" for what the party hears and says

record.terminators
stringDefaults to #

String of digits that will stop the recording when pressed

record.beep
booleanDefaults to false

Whether to play a beep when recording starts. Recording starts at the same time as the beep, so the beep can be included in the 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
numberDefaults to 0

Maximum length of the recording in seconds. 0 sets no maximum length; the recording can still end for other reasons, such as a terminator digit or a timeout.

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

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

A POST request will be sent to status_url with a JSON payload like the following for each recording state change:

event_type
string

The type of event. calling.call.record for recording state notifications.

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. Request errors arrive as a separate calling.error event; see error notifications.

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.first_frame_time
number

Unix timestamp (seconds, float) of the first recorded audio frame. Can be present when the recording ends (finished or no_input) and the first-frame time is known.

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.

params.record.audio
object

The audio settings the recording ran with.

params.record.audio.format
string

Recording format. Valid values: wav, mp3, mp4.

params.record.audio.direction
string

Direction of the audio recorded. Valid values: speak, listen, both.

params.record.audio.stereo
boolean

Whether the recording was made in stereo mode.

Raw JSON example

{
"event_type": "calling.call.record",
"event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timestamp": 1640000000.123,
"project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"params": {
"state": "finished",
"control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download",
"duration": 15,
"size": 248320,
"recording_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"start_time": 1640000000.123,
"end_time": 1640000015.623,
"record": {
"audio": {
"format": "wav",
"direction": "speak",
"stereo": false
}
}
}
}

Error notifications

When the record request itself fails, status_url can also receive a separate event with event_type set to calling.error instead of a recording state. Its params.error object carries the error code and message. Not every failure produces this event.


Examples

Record some audio and play it back

version: 1.0.0
sections:
main:
- play:
url: 'say:Start speaking after the beep. Press hash to end recording.'
- record:
end_silence_timeout: 3
beep: true
- play:
url: 'say:Recording ${record_result}. Playing back recording:'
- play:
url: '${record_url}'