***

id: 922026e9-1a65-4b5b-b786-ca7918b72cf1
title: record
slug: /reference/record
description: >-
Record the call audio in the foreground pausing further SWML execution until
recording ends.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

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`](/docs/swml/reference/record-call)

## **Properties**

<ParamField path="record" type="object" required={true} toc={true}>
  An object that accepts the following properties.
</ParamField>

<Indent>
  <ParamField path="record.stereo" type="boolean" default="false" toc={true}>
    Whether to record in stereo mode
  </ParamField>

  <ParamField path="record.format" type="string" default="wav" toc={true}>
    Format (`"wav"`, `"mp3"`, or `"mp4"`)
  </ParamField>

  <ParamField path="record.direction" type="string" default="speak" toc={true}>
    Direction of the audio to record: `"speak"` for what party says, `"listen"` for what party hears
  </ParamField>

  <ParamField path="record.terminators" type="string" default="#" toc={true}>
    String of digits that will stop the recording when pressed
  </ParamField>

  <ParamField path="record.beep" type="boolean" default="false" toc={true}>
    Whether to play a beep before recording
  </ParamField>

  <ParamField path="record.input_sensitivity" type="number" default="44.0" toc={true}>
    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`.
  </ParamField>

  <ParamField path="record.initial_timeout" type="number" default="4.0 seconds" toc={true}>
    How long, in seconds, to wait for speech to start?
  </ParamField>

  <ParamField path="record.end_silence_timeout" type="number" default="5.0 seconds" toc={true}>
    How much silence, in seconds, will end the recording?
  </ParamField>

  <ParamField path="record.max_length" type="number" toc={true}>
    Maximum length of the recording in seconds.
  </ParamField>

  <ParamField path="record.status_url" type="string" toc={true}>
    HTTP or HTTPS URL to deliver record status events. Learn more about [status callbacks][statuscallbacks].
  </ParamField>
</Indent>

## **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:

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.record` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing recording-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.control_id" type="string" toc={true}>
    The control ID for this record operation.
  </ParamField>

  <ParamField path="params.state" type="string" toc={true}>
    The current recording state. **Valid values:** `recording`, `paused`, `finished`, `no_input`, `error`.
  </ParamField>

  <ParamField path="params.url" type="string" toc={true}>
    URL to download the recording.
  </ParamField>

  <ParamField path="params.duration" type="number" toc={true}>
    Recording duration in seconds. Present when `state` is `finished` or `no_input`.
  </ParamField>

  <ParamField path="params.size" type="number" toc={true}>
    Recording file size in bytes. Present when `state` is `finished` or `no_input`.
  </ParamField>

  <ParamField path="params.recording_id" type="string" toc={true}>
    The unique identifier for the recording. Present when available.
  </ParamField>

  <ParamField path="params.start_time" type="number" toc={true}>
    Unix timestamp (seconds, float) when the recording started. Present when the recording has ended.
  </ParamField>

  <ParamField path="params.end_time" type="number" toc={true}>
    Unix timestamp (seconds, float) when the recording ended. Present when the recording has ended.
  </ParamField>

  <ParamField path="params.pause_behavior" type="string" toc={true}>
    How paused recording handles audio. Only present when `state` is `paused`. **Valid values:** `silence`, `skip`.
  </ParamField>

  <ParamField path="params.record" type="object" toc={true}>
    Recording configuration details.
  </ParamField>

  <Indent>
    <ParamField path="record.audio.format" type="string" toc={true}>
      Recording format. **Valid values:** `wav`, `mp3`.
    </ParamField>

    <ParamField path="record.audio.direction" type="string" toc={true}>
      Direction of the audio recorded: `speak` or `listen`.
    </ParamField>

    <ParamField path="record.audio.stereo" type="boolean" toc={true}>
      Whether the recording was made in stereo mode.
    </ParamField>
  </Indent>
</Indent>

### Raw JSON example

```json
{
  "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
      }
    }
  }
}
```

***

## **Examples**

### Record some audio and play it back

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    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}'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "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}"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>