SignalWire Calls API

openapi: 3.2.0
info:
  title: Signalwire Calls API
  version: 1.0.0
  description: 'Operations tagged Calls across 2 of this provider''s published API definitions: signalwire-compatibility-openapi.yaml, signalwire-rest-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{space_name}.signalwire.com/api/laml/2010-04-01
  description: SignalWire Compatibility API
  variables:
    space_name:
      default: YOUR_SPACE
      description: Your SignalWire Space name
- url: https://{space_name}.signalwire.com
  description: SignalWire API
  variables:
    space_name:
      default: '{Your_Space_Name}'
      description: Your SignalWire Space name
security:
- SignalWireBasicAuth: []
tags:
- name: Calls
  description: Manage voice calls and call recordings.
  externalDocs:
    url: https://signalwire.com/docs/compatibility-api/rest
    description: Developer documentation on the Compatibility REST API
paths:
  /Accounts/{AccountSid}/Calls:
    get:
      operationId: list_all_calls
      summary: List all Calls
      description: 'List all calls.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/CallsAccountSidPath'
      - name: EndTime
        in: query
        required: false
        description: The time, in RFC 2822 GMT format, on which the call was terminated.
        schema:
          type: string
        explode: false
      - name: EndTime<
        in: query
        required: false
        description: The time before which the call was terminated.
        schema:
          type: string
        explode: false
      - name: EndTime>
        in: query
        required: false
        description: The time after which the call was terminated.
        schema:
          type: string
        explode: false
      - name: From
        in: query
        required: false
        description: The address that initiated the call.
        schema:
          type: string
        explode: false
      - name: ParentCallSid
        in: query
        required: false
        description: The unique identifier for the call that created this call.
        schema:
          $ref: '#/components/schemas/uuid'
        explode: false
      - name: StartTime
        in: query
        required: false
        description: The time, in RFC 2822 GMT format, on which the call began.
        schema:
          type: string
        explode: false
      - name: StartTime<
        in: query
        required: false
        description: The time before which the call began.
        schema:
          type: string
        explode: false
      - name: StartTime>
        in: query
        required: false
        description: The time after which the call began.
        schema:
          type: string
        explode: false
      - name: Status
        in: query
        required: false
        description: The status of the call.
        schema:
          type: string
          enum:
          - queued
          - ringing
          - in-progress
          - canceled
          - completed
          - busy
          - failed
          - no-answer
        explode: false
      - name: To
        in: query
        required: false
        description: The address that received the call.
        schema:
          type: string
        explode: false
      - name: Page
        in: query
        required: false
        description: The page number to retrieve. Page numbers are zero-indexed, so the first page is 0.
        schema:
          type: integer
          format: int32
          minimum: 0
          default: 0
        explode: false
      - name: PageSize
        in: query
        required: false
        description: The number of results to return per page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 1000
          default: 50
        explode: false
      - name: PageToken
        in: query
        required: false
        description: A token used to retrieve a specific page of results. Must start with PA or PB.
        schema:
          type: string
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallListResponse'
        '400':
          description: The request was invalid or cannot be processed. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '401':
          description: Authentication failed. Please verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '422':
          description: The request could not be processed due to validation errors. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
      tags:
      - Calls
    post:
      operationId: create_a_call
      summary: Create a Call
      description: 'Create a call.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/CallsAccountSidPath'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: The request was invalid. Review the errors array for specific issues with your request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorArrayResponse'
        '401':
          description: Authentication failed. Please verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '422':
          description: The request could not be processed due to validation errors. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
    servers:
    - url: https://{space_name}.signalwire.com/api/laml/2010-04-01
      description: SignalWire Compatibility API
      variables:
        space_name:
          default: YOUR_SPACE
          description: Your SignalWire Space name
  /Accounts/{AccountSid}/Calls/{Sid}:
    get:
      operationId: retrieve_a_call
      summary: Retrieve a Call
      description: 'Retrieve a call.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/CallsAccountSidPath'
      - $ref: '#/components/parameters/CallSidPath'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: The request was invalid or cannot be processed. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '401':
          description: Authentication failed. Please verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '404':
          description: The requested resource was not found. Please verify the resource identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
      tags:
      - Calls
    post:
      operationId: update_a_call
      summary: Update a Call
      description: 'Update a call.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/CallsAccountSidPath'
      - $ref: '#/components/parameters/CallSidPath'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '400':
          description: The request was invalid or cannot be processed. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '401':
          description: Authentication failed. Please verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '404':
          description: The requested resource was not found. Please verify the resource identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '422':
          description: The request could not be processed due to validation errors. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '503':
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateCallRequest'
    delete:
      operationId: delete_a_call
      summary: Delete a Call
      description: 'Delete a call record from your account. If the delete is successful, a 204 response, with no body, will be returned.


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.


        Learn more about API scopes.'
      parameters:
      - $ref: '#/components/parameters/CallsAccountSidPath'
      - $ref: '#/components/parameters/CallSidPath'
      responses:
        '204':
          description: 204 No Content response.
        '400':
          description: The request was invalid or cannot be processed. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '401':
          description: Authentication failed. Please verify your credentials and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '404':
          description: The requested resource was not found. Please verify the resource identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
        '422':
          description: The request could not be processed due to validation errors. Check the error details for more information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompatibilityErrorResponse'
      tags:
      - Calls
    servers:
    - url: https://{space_name}.signalwire.com/api/laml/2010-04-01
      description: SignalWire Compatibility API
      variables:
        space_name:
          default: YOUR_SPACE
          description: Your SignalWire Space name
  /api/calling/calls:
    post:
      operationId: call-commands
      summary: Send call commands
      description: 'Unified JSON-RPC style endpoint for executing call methods through command-based dispatch.

        Send a request with the appropriate `command` field to invoke the desired call operation.

        Only the commands listed below are supported. Most operate on an already-active call; `dial` creates a new one. All commands are sent over HTTP (no persistent WebSocket connection required) and return immediately; operations that continue asynchronously deliver their results to your `status_url` webhooks.


        ## Supported Commands


        Use one of the following commands in the `command` field of the request body to perform the corresponding action on an active call.

        For more details on each command, refer to the individual API reference documentation linked below.


        | Command | Description |

        |---------|-------------|

        | `dial` | Create and initiate a new outbound call |

        | `update` | Modify an active call''s dialplan in real-time |

        | `calling.end` | Terminate an active call immediately |

        | `calling.transfer` | Transfer a call to a new destination (SIP URI, phone number, or inline SWML) |

        | `calling.disconnect` | Disconnect bridged calls without hanging up either leg |

        | `calling.play` | Play audio, TTS, silence, or ringtone to a call |

        | `calling.play.pause` | Pause active playback |

        | `calling.play.resume` | Resume paused playback |

        | `calling.play.stop` | Stop active playback |

        | `calling.play.volume` | Adjust playback volume |

        | `calling.record` | Start recording a call |

        | `calling.record.pause` | Pause active recording |

        | `calling.record.resume` | Resume paused recording |

        | `calling.record.stop` | Stop active recording |

        | `calling.collect` | Collect DTMF or speech input |

        | `calling.collect.stop` | Stop active collection |

        | `calling.collect.start_input_timers` | Start input timers on active collect |

        | `calling.detect` | Start a detector (answering machine, fax, or digit) |

        | `calling.detect.stop` | Stop active detector |

        | `calling.tap` | Tap call audio to an RTP or WebSocket endpoint |

        | `calling.tap.stop` | Stop active tap |

        | `calling.transcribe` | Start background transcription of a call |

        | `calling.transcribe.stop` | Stop active transcription |

        | `calling.stream` | Stream call audio to a WebSocket endpoint |

        | `calling.stream.stop` | Stop active stream |

        | `calling.denoise` | Start noise reduction on a call |

        | `calling.denoise.stop` | Stop noise reduction |

        | `calling.ai_hold` | Place an AI call on hold |

        | `calling.ai_unhold` | Resume an AI call from hold |

        | `calling.ai_message` | Inject a message into an active AI conversation |

        | `calling.ai.stop` | Stop an active AI session |

        | `calling.ai_sidecar` | Attach a real-time AI observer (sidecar) to a call, or summarize the conversation |

        | `calling.ai_sidecar.poke` | Send a message to the sidecar and prompt an immediate response |

        | `calling.ai_sidecar.ask` | Ask the sidecar a one-off question (answered via an `ask_answer` callback) |

        | `calling.ai_sidecar.stop` | Stop and detach the AI sidecar |

        | `calling.ai_sidecar.status` | Get a snapshot of the sidecar''s activity counters |

        | `calling.live_transcribe` | Start, stop, or summarize real-time transcription |

        | `calling.live_translate` | Start, stop, summarize, or inject real-time translation |

        | `calling.send_fax.stop` | Stop active fax send |

        | `calling.receive_fax.stop` | Stop active fax receive |

        | `calling.refer` | Transfer a SIP call via SIP REFER |

        | `calling.user_event` | Fire a custom user event on the call |


        #### Permissions


        The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Voice_.


        Learn more about API scopes.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calling.CallResponse'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode400'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
        '422':
          description: The request contains invalid parameters. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calling.CallCreate422Error'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Calling.CallRequest'
            examples:
              dial:
                summary: dial
                description: Initiate a new outbound call with the dial command
                value:
                  command: dial
                  params:
                    from: '+15551234567'
                    to: '+15557654321'
                    url: https://example.com/swml
              update:
                summary: update
                description: Modify an existing call's parameters in real-time
                value:
                  command: update
                  params:
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    url: https://example.com/swml
              calling.end:
                summary: calling.end
                description: Terminate an active call immediately
                value:
                  command: calling.end
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    reason: hangup
              calling.ai_hold:
                summary: calling.ai_hold
                description: Put an active AI call on hold, pausing the conversation
                value:
                  command: calling.ai_hold
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    timeout: '300'
              calling.ai_unhold:
                summary: calling.ai_unhold
                description: Resume an AI call that was previously put on hold
                value:
                  command: calling.ai_unhold
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params: {}
              calling.ai_message:
                summary: calling.ai_message
                description: Send a message to the AI conversation to modify behavior or add context
                value:
                  command: calling.ai_message
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    role: system
                    message_text: You are now in expert mode. Provide detailed technical responses and use industry terminology.
              calling.live_transcribe:
                summary: calling.live_transcribe
                description: Start real-time speech-to-text transcription on an active call
                value:
                  command: calling.live_transcribe
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    action:
                      start:
                        lang: en-US
                        direction:
                        - local-caller
                        - remote-caller
                        webhook: https://example.com/transcription-events
                        live_events: true
                        ai_summary: true
                        ai_summary_prompt: Summarize the key points of this conversation.
                        speech_engine: deepgram
              calling.live_translate:
                summary: calling.live_translate
                description: Start real-time language translation between call participants
                value:
                  command: calling.live_translate
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    action:
                      start:
                        from_lang: en-US
                        to_lang: es-ES
                        direction:
                        - local-caller
                        - remote-caller
                        from_voice: elevenlabs.josh
                        to_voice: elevenlabs.josh
                        filter_from: professional
                        webhook: https://example.com/translation-events
                        live_events: true
                        ai_summary: true
                        speech_engine: deepgram
              calling.transfer:
                summary: calling.transfer
                description: Transfer an active call to a new destination
                value:
                  command: calling.transfer
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    dest: https://example.com/swml
              calling.disconnect:
                summary: calling.disconnect
                description: Disconnect a call leg
                value:
                  command: calling.disconnect
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params: {}
              calling.play:
                summary: calling.play
                description: Play media on an active call
                value:
                  command: calling.play
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: play-control-1
                    play:
                    - type: audio
                      params:
                        url: https://example.com/audio.mp3
                    volume: 0
                    direction: listen
                    loop: 1
              calling.play.pause:
                summary: calling.play.pause
                description: Pause an active play operation
                value:
                  command: calling.play.pause
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: play-control-1
              calling.play.resume:
                summary: calling.play.resume
                description: Resume a paused play operation
                value:
                  command: calling.play.resume
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: play-control-1
              calling.play.stop:
                summary: calling.play.stop
                description: Stop an active play operation
                value:
                  command: calling.play.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: play-control-1
              calling.play.volume:
                summary: calling.play.volume
                description: Adjust the volume of an active play operation
                value:
                  command: calling.play.volume
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: play-control-1
                    volume: 5
              calling.record:
                summary: calling.record
                description: Start recording an active call
                value:
                  command: calling.record
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: record-control-1
                    record:
                      audio:
                        format: mp3
                        direction: speak
                        stereo: false
              calling.record.pause:
                summary: calling.record.pause
                description: Pause an active recording
                value:
                  command: calling.record.pause
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: record-control-1
              calling.record.resume:
                summary: calling.record.resume
                description: Resume a paused recording
                value:
                  command: calling.record.resume
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: record-control-1
              calling.record.stop:
                summary: calling.record.stop
                description: Stop an active recording
                value:
                  command: calling.record.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: record-control-1
              calling.collect:
                summary: calling.collect
                description: Collect user input (digits or speech) during a call
                value:
                  command: calling.collect
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: collect-control-1
                    initial_timeout: 5
                    digits:
                      max: 4
                      terminators: '#'
                    continuous: false
                    partial_results: false
                    send_start_of_input: false
                    start_input_timers: false
                    status_url: https://example.com/collect_callback
              calling.collect.stop:
                summary: calling.collect.stop
                description: Stop an active collect operation
                value:
                  command: calling.collect.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: collect-control-1
              calling.collect.start_input_timers:
                summary: calling.collect.start_input_timers
                description: Start input timers for an active collect operation
                value:
                  command: calling.collect.start_input_timers
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: collect-control-1
              calling.detect:
                summary: calling.detect
                description: Start detection (machine, fax, or digit) on an active call
                value:
                  command: calling.detect
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: detect-control-1
                    detect:
                      type: machine
                      params:
                        initial_timeout: 4.5
                        end_silence_timeout: 1
                    timeout: 30
              calling.detect.stop:
                summary: calling.detect.stop
                description: Stop an active detection operation
                value:
                  command: calling.detect.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: detect-control-1
              calling.tap:
                summary: calling.tap
                description: Start tapping (capturing audio) on an active call
                value:
                  command: calling.tap
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: tap-control-1
                    tap:
                      type: audio
                      params:
                        direction: both
                    device:
                      type: rtp
                      params:
                        addr: 198.51.100.42
                        port: 5060
              calling.tap.stop:
                summary: calling.tap.stop
                description: Stop an active tap operation
                value:
                  command: calling.tap.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: tap-control-1
              calling.transcribe:
                summary: calling.transcribe
                description: Start background transcription on an active call
                value:
                  command: calling.transcribe
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: transcribe-control-1
                    status_url: https://example.com/transcribe-status
              calling.transcribe.stop:
                summary: calling.transcribe.stop
                description: Stop an active transcription operation
                value:
                  command: calling.transcribe.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: transcribe-control-1
              calling.stream:
                summary: calling.stream
                description: Start streaming call audio to a WebSocket endpoint
                value:
                  command: calling.stream
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: stream-control-1
                    url: wss://example.com/stream
                    track: inbound_track
              calling.stream.stop:
                summary: calling.stream.stop
                description: Stop an active audio stream
                value:
                  command: calling.stream.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params:
                    control_id: stream-control-1
              calling.denoise:
                summary: calling.denoise
                description: Enable noise reduction on an active call
                value:
                  command: calling.denoise
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params: {}
              calling.denoise.stop:
                summary: calling.denoise.stop
                description: Disable noise reduction on an active call
                value:
                  command: calling.denoise.stop
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params: {}
              calling.ai_sidecar.status:
                summary: calling.ai_sidecar.status
                description: Get a snapshot of the sidecar's activity counters
                value:
                  command: calling.ai_sidecar.status
                  id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  params: {}
              calling.ai_sidecar.stop:
                summary: calling.ai_sidecar.stop
                description: Stop and detach the AI sidec

# --- truncated at 32 KB (232 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/signalwire/refs/heads/main/openapi/signalwire-calls-api-openapi.yml