> This page is for APIs.

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

# calling.record

GET /

Record a call

Reference: https://signalwire.com/docs/apis/relay/server/calling/calling-record

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.record
  version: subpackage_callingRecord.calling.record
  description: Record a call
channels:
  /:
    description: Record a call
    publish:
      operationId: subpackage_callingRecord.calling.record-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_callingRecord.calling.record-server-0-onCallingRecordCallRecordEvent
          - $ref: >-
              #/components/messages/subpackage_callingRecord.calling.record-server-1-onCallingRecordResponse
    subscribe:
      operationId: subpackage_callingRecord.calling.record-subscribe
      summary: calling.record
      message:
        name: callingRecord
        title: calling.record
        payload:
          $ref: '#/components/schemas/calling.record_callingRecordRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_callingRecord.calling.record-server-0-onCallingRecordCallRecordEvent:
      name: onCallingRecordCallRecordEvent
      title: calling.call.record
      payload:
        $ref: '#/components/schemas/calling.record_callRecordEvent'
    subpackage_callingRecord.calling.record-server-1-onCallingRecordResponse:
      name: onCallingRecordResponse
      title: calling.record response
      payload:
        $ref: '#/components/schemas/calling.record_callingRecordResponse'
  schemas:
    ChannelsCallingRecordMessagesCallRecordEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingRecordMessagesCallRecordEventJsonrpc
    ChannelsCallingRecordMessagesCallRecordEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingRecordMessagesCallRecordEventMethod
    ChannelsCallingRecordMessagesCallRecordEventParamsEventType:
      type: string
      enum:
        - calling.call.record
      description: The event type — identifies which event this is.
      title: ChannelsCallingRecordMessagesCallRecordEventParamsEventType
    Calling.CallRecordState:
      type: string
      enum:
        - recording
        - paused
        - finished
        - no_input
      title: Calling.CallRecordState
    CallingCallRecordParamsPauseBehavior:
      type: string
      enum:
        - silence
        - skip
      description: >-
        How paused time is handled in the recording: `silence` inserts silence
        for the paused span, while `skip` leaves it out entirely.
      title: CallingCallRecordParamsPauseBehavior
    Calling.RecordEventDirection:
      type: string
      enum:
        - listen
        - speak
        - both
      title: Calling.RecordEventDirection
    Calling.RecordEventAudio:
      type: object
      properties:
        format:
          type: string
          description: The file format of the recording (for example `mp3` or `wav`).
        stereo:
          type: boolean
          description: Whether the recording was captured in stereo.
        direction:
          $ref: '#/components/schemas/Calling.RecordEventDirection'
          description: Which side(s) of the conversation were captured.
      required:
        - format
        - stereo
        - direction
      description: The audio settings the recording was captured with.
      title: Calling.RecordEventAudio
    Calling.RecordEventSpec:
      type: object
      properties:
        audio:
          $ref: '#/components/schemas/Calling.RecordEventAudio'
          description: The audio settings used for this recording.
      required:
        - audio
      description: >-
        Describes how the recording was made, including the `audio` settings it
        was captured with.
      title: Calling.RecordEventSpec
    Calling.CallRecordParams:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses this call.
            Echo back the value you received; treat it as opaque.
        call_id:
          type: string
          description: Unique identifier of the call.
        segment_id:
          type: string
          description: >-
            Identifier of the call segment this event belongs to, for
            correlating events within the same segment of a call.
        tag:
          type: string
          description: >-
            The `tag` you set when placing the call, echoed back so you can
            match the event to your request.
        control_id:
          type: string
          description: >-
            The `control_id` of the recording this event refers to, returned
            when you started it with `calling.record`.
        state:
          $ref: '#/components/schemas/Calling.CallRecordState'
          description: Where the recording currently stands.
        recording_id:
          type: string
          description: The unique identifier of the recording.
        url:
          type: string
          format: uri
          description: >-
            Where the recording is stored. Can appear on any state; the file is
            complete only once the state is `finished`.
        duration:
          type: number
          format: double
          description: >-
            How long the recording is, in seconds. Set once the state is
            `finished`.
        size:
          type: integer
          format: int64
          description: >-
            How large the recording file is, in bytes. Set once the state is
            `finished`.
        start_time:
          type: number
          format: double
          description: >-
            Unix timestamp for when the recording started, in seconds. Set once
            the state is `finished`.
        first_frame_time:
          type: number
          format: double
          description: >-
            Unix timestamp, in seconds, of the first captured audio. Present
            when available; more precise than `start_time`.
        end_time:
          type: number
          format: double
          description: >-
            Unix timestamp for when the recording ended, in seconds. Set once
            the state is `finished`.
        pause_behavior:
          $ref: '#/components/schemas/CallingCallRecordParamsPauseBehavior'
          description: >-
            How paused time is handled in the recording: `silence` inserts
            silence for the paused span, while `skip` leaves it out entirely.
        record:
          $ref: '#/components/schemas/Calling.RecordEventSpec'
          description: The settings this recording was captured with.
      required:
        - node_id
        - call_id
        - control_id
        - state
        - record
      title: Calling.CallRecordParams
    ChannelsCallingRecordMessagesCallRecordEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallRecordEventParamsEventType
          description: The event type — identifies which event this is.
        event_channel:
          type: string
          description: >-
            The channel the event was delivered on — for Calling events, the
            `protocol`

            string your connection received from `signalwire.connect`.
        timestamp:
          type: number
          format: double
          description: >-
            When the event was emitted, as a Unix timestamp in seconds. Always
            present.
        project_id:
          type: string
          description: >-
            Your project ID. Present on Calling events and most Call Fabric
            events; absent on `call.joined`, `call.left`, `member.joined`, and
            `member.left`.
        space_id:
          type: string
          description: >-
            Your space ID. Present on Calling events and most Call Fabric
            events; absent on `call.joined`, `call.left`, `member.joined`, and
            `member.left`.
        params:
          $ref: '#/components/schemas/Calling.CallRecordParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingRecordMessagesCallRecordEventParams
    calling.record_callRecordEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallRecordEventJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: >-
            Event id — a unique UUID generated for each event. Events are
            notifications: you do not reply to them.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallRecordEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallRecordEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires when a recording starts, pauses, resumes, or finishes. The
        finished event includes the download URL, duration, and file size.
      title: calling.record_callRecordEvent
    ChannelsCallingRecordMessagesCallingRecordResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingRecordMessagesCallingRecordResponseJsonrpc
    Calling.RecordResult:
      type: object
      properties:
        code:
          type: string
          description: >-
            Result code as a string. `"200"` means success. Failures use an
            HTTP-style code

            such as `"400"` (bad request), `"403"`, `"404"` (call not found),
            `"405"`, `"409"`

            (conflict, for example another operation is still running), `"410"`
            (call gone),

            or `"500"`. If the call could not be reached in time, `code` is a
            lowercase error

            identifier instead, such as `response_timeout`, `not_available`, or

            `internal_error`.
        message:
          type: string
          description: >-
            Human-readable description of the result. On failure, it explains
            what went wrong. Always check `code`; `message` may be omitted when
            there is nothing extra to report.
        call_id:
          type: string
          description: The call this result is for, echoed from your request.
        control_id:
          type: string
          description: >-
            Your control identifier for the started action, echoed from your
            request.
        url:
          type: string
          format: uri
          description: >-
            Where the recording will be stored. The file is complete once a
            `calling.call.record` event reports `finished`.
      required:
        - code
        - url
      title: Calling.RecordResult
    JsonRpcErrorCode0:
      type: string
      enum:
        - '-32000'
      title: JsonRpcErrorCode0
    JsonRpcErrorCode1:
      type: string
      enum:
        - '-32001'
      title: JsonRpcErrorCode1
    JsonRpcErrorCode2:
      type: string
      enum:
        - '-32002'
      title: JsonRpcErrorCode2
    JsonRpcErrorCode3:
      type: string
      enum:
        - '-32003'
      title: JsonRpcErrorCode3
    JsonRpcErrorCode4:
      type: string
      enum:
        - '-32004'
      title: JsonRpcErrorCode4
    JsonRpcErrorCode5:
      type: string
      enum:
        - '-32005'
      title: JsonRpcErrorCode5
    JsonRpcErrorCode6:
      type: string
      enum:
        - '-32600'
      title: JsonRpcErrorCode6
    JsonRpcErrorCode7:
      type: string
      enum:
        - '-32601'
      title: JsonRpcErrorCode7
    JsonRpcErrorCode8:
      type: string
      enum:
        - '-32602'
      title: JsonRpcErrorCode8
    JsonRpcErrorCode9:
      type: string
      enum:
        - '-32603'
      title: JsonRpcErrorCode9
    JsonRpcErrorCode10:
      type: string
      enum:
        - '-32700'
      title: JsonRpcErrorCode10
    JsonRpcErrorCode:
      oneOf:
        - $ref: '#/components/schemas/JsonRpcErrorCode0'
        - $ref: '#/components/schemas/JsonRpcErrorCode1'
        - $ref: '#/components/schemas/JsonRpcErrorCode2'
        - $ref: '#/components/schemas/JsonRpcErrorCode3'
        - $ref: '#/components/schemas/JsonRpcErrorCode4'
        - $ref: '#/components/schemas/JsonRpcErrorCode5'
        - $ref: '#/components/schemas/JsonRpcErrorCode6'
        - $ref: '#/components/schemas/JsonRpcErrorCode7'
        - $ref: '#/components/schemas/JsonRpcErrorCode8'
        - $ref: '#/components/schemas/JsonRpcErrorCode9'
        - $ref: '#/components/schemas/JsonRpcErrorCode10'
      title: JsonRpcErrorCode
    JsonRpcError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/JsonRpcErrorCode'
          description: >-
            The error code — a negative integer identifying the failure. See
            `JsonRpcErrorCode` for the full list of values and meanings.
        message:
          type: string
          description: A human-readable description of what went wrong.
        original_request:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            An echo of the request that failed — the full JSON-RPC frame you
            sent

            (`jsonrpc`, `id`, `method`, `params`). Always present.
        requester_nodeid:
          type: string
          description: >-
            The node that sent the failed request. Present only on some routing
            errors.
        requester_identity:
          type: string
          description: >-
            The identity of the requester. Present only on some routing errors;
            same value as `requester_nodeid`.
        responder_nodeid:
          type: string
          description: >-
            The node that was handling the request. Present only on some routing
            errors.
        responder_identity:
          type: string
          description: >-
            The identity of the responder. Present only on some routing errors;
            same value as `responder_nodeid`.
        last_hop_timeout:
          type: boolean
          description: >-
            `true` when the request timed out on its final hop inside
            SignalWire. Present only on some timeout errors.
      required:
        - code
        - message
        - original_request
      description: >-
        A JSON-RPC 2.0 error object, delivered on the `error` field of a
        `JsonRpcResponse` when

        a request fails at the protocol level (bad version, authentication,
        scope, params, or

        your project's connection limit). It replaces `result` — a frame carries
        one or the other, never both.
      title: JsonRpcError
    calling.record_callingRecordResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallingRecordResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Calling.RecordResult'
          description: The method result. Present when the request succeeded.
        error:
          $ref: '#/components/schemas/JsonRpcError'
          description: >-
            Present instead of `result` when the request failed at the protocol
            level.
      required:
        - jsonrpc
        - id
      description: >-
        A JSON-RPC response frame correlated to a request by `id`. On success
        the frame carries

        `result` (the method result). If the request fails at the protocol level
        — an

        incompatible version, failed authentication, insufficient scope, invalid
        params, or your

        project's connection limit — the frame carries `error` instead of
        `result`. Many

        method-level failures (for example most Calling failures) are reported
        the other way: a

        normal `result` whose own `code` is not `"200"`. Each method documents
        which form its

        failures take.


        An `error` returned for `signalwire.connect` is followed by the service
        closing the

        WebSocket; open a new connection to try again. The same happens when

        `signalwire.reauthenticate` sends credentials that are rejected, except
        for a

        Subscriber Access Token. Errors on any other request leave the
        connection open.
      title: calling.record_callingRecordResponse
    ChannelsCallingRecordMessagesCallingRecordRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingRecordMessagesCallingRecordRequestJsonrpc
    ChannelsCallingRecordMessagesCallingRecordRequestMethod:
      type: string
      enum:
        - calling.record
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsCallingRecordMessagesCallingRecordRequestMethod
    CallingRecordAudioFormat:
      type: string
      enum:
        - mp3
        - wav
        - mp4
      default: mp3
      description: Output file format. Default `mp3`.
      title: CallingRecordAudioFormat
    Calling.RecordAudioDirection:
      type: string
      enum:
        - listen
        - speak
        - both
      title: Calling.RecordAudioDirection
    Calling.RecordAudio:
      type: object
      properties:
        beep:
          type: boolean
          default: false
          description: Play a beep before recording starts. Default `false`.
        format:
          $ref: '#/components/schemas/CallingRecordAudioFormat'
          default: mp3
          description: Output file format. Default `mp3`.
        stereo:
          type: boolean
          default: false
          description: >-
            Record the two call directions on separate channels. Default
            `false`.
        direction:
          $ref: '#/components/schemas/Calling.RecordAudioDirection'
          default: speak
          description: Which audio direction(s) to capture. Default `speak`.
        initial_timeout:
          type: number
          format: double
          minimum: 0
          default: 0
          description: >-
            Seconds to wait for speech before giving up. Defaults to `0` —
            continuous

            recording, which runs until the call ends or you send
            `calling.record.stop`.

            Set this together with `end_silence_timeout` for voicemail-style
            recording

            that stops on its own.
        end_silence_timeout:
          type: number
          format: double
          minimum: 0
          default: 0
          description: >-
            Seconds of trailing silence before the recording auto-stops.
            Defaults to `0` —

            continuous recording. Set this together with `initial_timeout` for

            voicemail-style recording.
        terminators:
          type: string
          default: '#'
          description: DTMF (touch-tone) digits that stop the recording. Default `#`.
        input_sensitivity:
          type: number
          format: double
          minimum: 0
          maximum: 100
          default: 44
          description: >-
            Input sensitivity: `0` = hear nothing, `100` = hear everything.
            Default

            `44.0`.
      description: Audio recording settings, passed under `record.audio`.
      title: Calling.RecordAudio
    Calling.RecordSpec:
      type: object
      properties:
        audio:
          $ref: '#/components/schemas/Calling.RecordAudio'
          description: Audio recording settings.
      required:
        - audio
      description: >-
        What to record. Audio is currently the only supported type — put its
        settings under `audio`.
      title: Calling.RecordSpec
    Calling.RecordParams:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses this call.
            Echo back the value you received; treat it as opaque.
        call_id:
          type: string
          description: Unique identifier of the call.
        control_id:
          type: string
          description: >-
            Your own identifier for this recording. Use it to pause, resume, or
            stop the recording later, and it comes back on recording events so
            you can correlate them.
        record:
          $ref: '#/components/schemas/Calling.RecordSpec'
          description: >-
            What to record. Currently audio is the only option — set its
            parameters under `audio`.
      required:
        - node_id
        - call_id
        - control_id
        - record
      title: Calling.RecordParams
    calling.record_callingRecordRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallingRecordRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingRecordMessagesCallingRecordRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Calling.RecordParams'
          description: The method's input parameters.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        A JSON-RPC request frame. `Method` is the method name; `Params` is the
        method's input.
      title: calling.record_callingRecordRequest

```