record_call
record_call
Record call in the background. Unlike the record method, the record_call method
will start the recording and continue executing the SWML script while allowing the recording to happen in the background.
To stop call recordings started with record_call, use the stop_record_call method.
Properties
record_call
An object that accepts the following properties.
record_call.control_id
Identifier for this recording, to use with stop_record_call. After variable expansion, the identifier can’t contain {, }, commas, semicolons, apostrophes, backslashes, or ASCII control characters; if it does, the recording fails to start.
record_call.stereo
Whether to record in stereo mode
record_call.format
Format ("wav", "mp3", or "mp4")
record_call.direction
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_call.terminators
String of digits that will stop the recording when pressed. Default is empty (no terminators).
record_call.beep
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_call.input_sensitivity
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. Only used when initial_timeout or end_silence_timeout is greater than 0; with both at their default of 0, the recording is continuous and this setting is ignored.
record_call.initial_timeout
How long, in seconds, to wait for speech to start?
record_call.end_silence_timeout
How much silence, in seconds, will end the recording?
record_call.max_length
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 stop_record_call.
record_call.status_url
HTTP or HTTPS URL to deliver record status events. Learn more about status callbacks.
Variables
Set by the method:
- record_call_url: (out) the URL of the newly started recording.
- record_call_result: (out)
success|failed. - record_control_id: (out) control ID of this recording.
- record_call_start: (out) Unix timestamp, in microseconds, of when SignalWire confirmed that the recording started. Set only when the recording starts successfully; a failed attempt leaves any previous value unchanged. It can be slightly earlier than the first recorded audio frame, which the status callback reports as
params.first_frame_time.
StatusCallbacks
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
The type of event. calling.call.record for recording state notifications.
event_channel
The channel for the event, includes the SWML session ID.
timestamp
Unix timestamp (float) when the event was generated.
project_id
The project ID associated with the call.
space_id
The Space ID associated with the call.
params
An object containing recording-specific parameters.
params.call_id
The call ID.
params.node_id
The node handling the call.
params.control_id
The control ID for this record operation.
params.state
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
URL of the recorded media on files.signalwire.com. Present from the recording state onward.
params.recording_id
ID of the recording, matching the id returned by the Recordings API.
params.duration
Recording duration in seconds. Present when the recording ends.
params.size
Recording file size in bytes. Present when the recording ends.
params.start_time
Unix timestamp (float) when the recording started. Present when the recording ends.
params.end_time
Unix timestamp (float) when the recording ended. Present when the recording ends.
params.first_frame_time
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
How paused recording handles audio. Only present when state is paused. Valid values: silence, skip.
params.segment_id
The call segment the recording belongs to.
params.record
The configuration the recording ran with.
params.record.audio
The audio settings the recording ran with.
params.record.audio.format
Recording format. Valid values: wav, mp3, mp4.
params.record.audio.direction
Direction of the audio recorded. Valid values: speak, listen, both.
params.record.audio.stereo
Whether the recording was made in stereo mode.
Raw JSON example
Error notifications
When the recording 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.