> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# record

> Record the call audio in the foreground pausing further SWML execution until recording ends.

[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/calling/record-call)

## **Properties**

**`record`** `object` — required

An object that accepts the following properties.

---

**`record.stereo`** `boolean` — default: false

Whether to record in stereo mode

---

**`record.format`** `string` — default: wav

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

---

**`record.direction`** `string` — default: speak

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

---

**`record.terminators`** `string` — default: #

String of digits that will stop the recording when pressed

---

**`record.beep`** `boolean` — default: false

Whether to play a beep before recording

---

**`record.input_sensitivity`** `number` — default: 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`** `number` — default: 4.0 seconds

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

---

**`record.end_silence_timeout`** `number` — default: 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][statuscallbacks].

---

## **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](/docs/platform/webhooks#status-callback-reliability).

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

```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

#### 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}'
```

#### 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}"
        }
      }
    ]
  }
}
```

> Record the call audio in the foreground pausing further SWML execution until recording ends.