openrpc: 1.3.2
info:
  title: Calling API (JSON-RPC)
  version: 1.0.0
  description: |
    JSON-RPC API to create and manage SignalWire's Calls.
    Each method corresponds to a specific call command for controlling calls programmatically.
  contact:
    name: SignalWire Support
    url: https://signalwire.com
  license:
    name: MIT
    url: https://github.com/signalwire/docs/blob/main/LICENSE
servers:
  - name: production
    url: https://{space_name}.signalwire.com/api/calling/rpc
    description: SignalWire JSON-RPC endpoint

methods:
  - name: calling.dial
    summary: Create a new outbound call
    paramStructure: by-name
    description: |
      Initiates a new outbound call to a destination. Returns immediately with call details
      while the call is being established in the background.

      You must provide either `url` (webhook returning SWML) or inline `swml` instructions.
    params:
      - name: from
        description: The address that initiates the call. E.164 format (+xxxxxxxxxxx) or SIP endpoint.
        required: true
        schema:
          type: string
      - name: to
        description: The address that receives the call. E.164 format (+xxxxxxxxxxx) or SIP endpoint.
        required: true
        schema:
          type: string
      - name: url
        description: The URL to handle the call. Should return SWML instructions. Either `url` or `swml` must be provided.
        required: false
        schema:
          type: string
      - name: swml
        description: Inline SWML passed as a string containing instructions for handling the call. Either `url` or `swml` must be provided.
        required: false
        schema:
          type: string
      - name: caller_id
        description: The number in E.164 format or identifier of the caller.
        required: false
        schema:
          type: string
      - name: fallback_url
        description: The fallback URL to handle the call if the primary URL fails.
        required: false
        schema:
          type: string
      - name: status_url
        description: A URL that will receive status updates of the current call.
        required: false
        schema:
          type: string
      - name: status_events
        description: The call events that will be monitored and sent to the status_url.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
              - answered
              - queued
              - initiated
              - ringing
              - ending
              - ended
    result:
      name: call
      description: The created call object with status and metadata
      schema:
        type: object
        properties:
          id:
            type: string
            description: The unique identifier of the call
          from:
            type: string
            description: The origin number or address
          to:
            type: string
            description: The destination number or address
          direction:
            type: string
            description: The direction of the call
          status:
            type: string
            description: The status of the call
    examples:
      - name: Create call with URL
        description: Create a new outbound call using a webhook URL
        params:
          - name: from
            value: "+15551234567"
          - name: to
            value: "+15559876543"
          - name: url
            value: "https://example.com/swml"
          - name: status_events
            value:
              - answered
              - ended
        result:
          name: call
          value:
            id: "0e9c80d7-a149-4917-892d-420043709f45"
            from: "+15551234567"
            to: "+15559876543"
            direction: "outbound-api"
            status: "queued"
      - name: Create call with inline SWML
        description: Create a new outbound call using inline SWML instructions
        params:
          - name: from
            value: "+15551234567"
          - name: to
            value: "+15559876543"
          - name: swml
            value: "{'version': '1.0.0', 'sections': { 'main': [{ 'answer': {} }, { 'play': { 'urls': ['say:Hello from SignalWire!'] } }] } }"
        result:
          name: call
          value:
            id: "0e9c80d7-a149-4917-892d-420043709f45"
            from: "+15551234567"
            to: "+15559876543"
            direction: "outbound-api"
            status: "queued"

  - name: calling.update
    summary: Update an existing call
    paramStructure: by-name
    description: |
      Modifies an active call's properties in real-time. Update call parameters such as
      routing, recording settings, or other call-specific configurations.

      You must provide either `url` (webhook returning SWML) or inline `swml` instructions.
    params:
      - name: id
        description: The unique identifying ID of the existing call to update.
        required: true
        schema:
          type: string
      - name: url
        description: The URL to handle the call with new SWML instructions. Either `url` or `swml` must be provided.
        required: false
        schema:
          type: string
      - name: swml
        description: Inline SWML with new instructions for handling the call. Either `url` or `swml` must be provided.
        required: false
        schema:
          type: string
      - name: fallback_url
        description: The fallback URL to handle the call if the primary URL fails.
        required: false
        schema:
          type: string
      - name: status
        description: Set to canceled to cancel a call, or completed to end an in-progress call.
        required: false
        schema:
          type: string
          enum:
            - canceled
            - completed
    result:
      name: call
      description: The updated call object
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: Update call with new URL
        description: Update an existing call with a new SWML webhook URL
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: url
            value: "https://example.com/new-swml"
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"

  - name: calling.end
    summary: Terminate an active call
    paramStructure: by-name
    description: |
      Terminates an active call immediately. Disconnects all parties and ends the call session.
    params:
      - name: id
        description: The unique identifying ID of the call to terminate.
        required: true
        schema:
          type: string
      - name: reason
        description: The reason for hanging up the call.
        required: false
        schema:
          type: string
          enum:
            - hangup
            - busy
    result:
      name: call
      description: The terminated call object
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: End call normally
        description: Terminate an active call with normal hangup reason
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: reason
            value: "hangup"
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "ended"

  - name: calling.ai_hold
    summary: Place an AI call on hold
    paramStructure: by-name
    description: |
      Places an AI-powered call on hold. Pauses the AI conversation and plays hold music.
    params:
      - name: id
        description: The unique identifying ID of the call to place on hold.
        required: true
        schema:
          type: string
      - name: timeout
        description: The duration to hold the caller in seconds. Maximum is 300 seconds.
        required: false
        schema:
          type: integer
          maximum: 300
          default: 300
      - name: prompt
        description: A system message the AI will speak before placing the caller on hold.
        required: false
        schema:
          type: string
          default: "Tell the user you are putting them on hold."
    result:
      name: call
      description: The call object now on hold
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: Hold call with custom prompt
        description: Place an AI call on hold with a custom message
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: timeout
            value: 120
          - name: prompt
            value: "Please hold while I transfer you to a specialist."
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"

  - name: calling.ai_unhold
    summary: Resume an AI call from hold
    paramStructure: by-name
    description: |
      Resumes an AI call from hold state. Reactivates the AI agent and continues the conversation.
    params:
      - name: id
        description: The unique identifying ID of the call to take off hold.
        required: true
        schema:
          type: string
      - name: prompt
        description: A system message added to the AI conversation when taking the caller off hold.
        required: false
        schema:
          type: string
          default: "The user has been taken off hold."
    result:
      name: call
      description: The call object now resumed
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: Unhold call with context
        description: Resume an AI call from hold with context
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: prompt
            value: "The user has been connected to a specialist."
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"

  - name: calling.ai_message
    summary: Inject a message into an AI conversation
    paramStructure: by-name
    description: |
      Injects a message into an active AI conversation. Allows you to dynamically add
      context, instructions, or messages to guide the AI agent's behavior during the call.
    params:
      - name: id
        description: The unique identifying ID of the call.
        required: true
        schema:
          type: string
      - name: role
        description: |
          The role of the message:
          - `system`: Inject instructions or context that modify the AI's behavior
          - `user`: Inject a message as if the caller said it
          - `assistant`: Inject a message as if the AI said it
        required: true
        schema:
          type: string
          enum:
            - system
            - user
            - assistant
      - name: message_text
        description: The text content that will be sent to the AI.
        required: true
        schema:
          type: string
    result:
      name: call
      description: The call object after message injection
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: Inject system message
        description: Inject a system message to change AI behavior mid-conversation
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: role
            value: "system"
          - name: message_text
            value: "You are now in expert mode. Provide detailed technical responses."
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"

  - name: calling.live_transcribe
    summary: Control live transcription on a call
    paramStructure: by-name
    description: |
      Controls live transcription on an active call. Start real-time speech-to-text transcription,
      stop transcription, or request an AI summary of the conversation.
    params:
      - name: id
        description: The unique identifying ID of the call.
        required: true
        schema:
          type: string
      - name: action
        description: |
          The transcription action to perform. Can be:
          - An object with `start` key to begin transcription
          - An object with `summarize` key to request an AI summary
          - The string `stop` to end transcription
        required: true
        schema:
          type: object
    result:
      name: call
      description: The call object after transcription action
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: Start transcription
        description: Start live transcription with English language
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: action
            value:
              start:
                lang: "en-US"
                direction:
                  - "local-caller"
                  - "remote-caller"
                webhook: "https://example.com/transcription-webhook"
                live_events: true
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"
      - name: Stop transcription
        description: Stop live transcription on a call
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: action
            value: "stop"
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"

  - name: calling.live_translate
    summary: Control live translation on a call
    paramStructure: by-name
    description: |
      Controls live translation on an active call. Start real-time language translation
      between call participants, stop translation, request summaries, or inject translated messages.
    params:
      - name: id
        description: The unique identifying ID of the call.
        required: true
        schema:
          type: string
      - name: action
        description: |
          The translation action to perform. Can be:
          - An object with `start` key to begin translation
          - An object with `inject` key to inject a translated message
          - An object with `summarize` key to request an AI summary
          - The string `stop` to end translation
        required: true
        schema:
          type: object
    result:
      name: call
      description: The call object after translation action
      schema:
        type: object
        properties:
          id:
            type: string
          status:
            type: string
    examples:
      - name: Start translation
        description: Start live translation between English and Spanish
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: action
            value:
              start:
                from_lang: "en-US"
                to_lang: "es-ES"
                direction:
                  - "local-caller"
                  - "remote-caller"
                webhook: "https://example.com/translation-webhook"
                live_events: true
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"
      - name: Inject translated message
        description: Inject a message to be translated and spoken
        params:
          - name: id
            value: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          - name: action
            value:
              inject:
                message: "Please hold while I transfer you."
                direction: "remote-caller"
        result:
          name: call
          value:
            id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
            status: "active"