***

id: 5e4a19d3-3f73-42af-83f0-99f62390d983
title: record\_call
slug: /reference/record-call
description: Record call in the background.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

Record call in the background. Unlike the [`record` method](/docs/swml/reference/record), 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_call_record`](/docs/swml/reference/stop-record-call) method.

## **Properties**

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

<Indent>
  <ParamField path="record_call.control_id" type="string" default="Auto-generated, saved to record_control_id variable" toc={true}>
    Identifier for this recording, to use with [`stop_record_call`](/docs/swml/reference/stop-record-call)
  </ParamField>

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

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

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

  <ParamField path="record_call.terminators" type="string" toc={true}>
    String of digits that will stop the recording when pressed. Default is empty (no terminators).
  </ParamField>

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

  <ParamField path="record_call.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_call.initial_timeout" type="number" default="0" toc={true}>
    How long, in seconds, to wait for speech to start?
  </ParamField>

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

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

  <ParamField path="record_call.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\_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.

## **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.record" type="object" toc={true}>
    Recording result details (present when state is `finished`).
  </ParamField>

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

    <ParamField path="record.duration" type="number" toc={true}>
      Recording duration in seconds.
    </ParamField>

    <ParamField path="record.size" type="number" toc={true}>
      Recording file size in bytes.
    </ParamField>

    <ParamField path="record.format" type="string" toc={true}>
      Recording format. **Valid values:** `wav`, `mp3`.
    </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": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "state": "finished",
    "record": {
      "url": "https://your-space.signalwire.com/api/v1/recordings/rec-uuid/download",
      "duration": 15.5,
      "size": 248320,
      "format": "wav"
    }
  }
}
```

***

## **Examples**

### Start an MP3 recording of the call

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - record_call:
            format: mp3
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "record_call": {
              "format": "mp3"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Record and play back

#### Record both sides of the conversation:

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - record_call:
            beep: true
            terminators: '#'
        - play:
            urls:
              - 'say:Leave your message now'
              - 'silence:10'
        - stop_record_call: {}
        - play:
            urls:
              - 'say:Playing back'
              - '${record_call_url}'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "record_call": {
              "beep": true,
              "terminators": "#"
            }
          },
          {
            "play": {
              "urls": [
                "say:Leave your message now",
                "silence:10"
              ]
            }
          },
          {
            "stop_record_call": {}
          },
          {
            "play": {
              "urls": [
                "say:Playing back",
                "${record_call_url}"
              ]
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

#### Record only the speaker's side

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - record_call:
            beep: true
            direction: speak
        - play:
            urls:
              - 'say:Leave your message now'
              - 'silence:10'
        - stop_record_call: {}
        - play:
            urls:
              - 'say:Playing back'
              - '${record_call_url}'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "record_call": {
              "beep": true,
              "direction": "speak"
            }
          },
          {
            "play": {
              "urls": [
                "say:Leave your message now",
                "silence:10"
              ]
            }
          },
          {
            "stop_record_call": {}
          },
          {
            "play": {
              "urls": [
                "say:Playing back",
                "${record_call_url}"
              ]
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>