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

GET /

Connect a device to an active call

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

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.connect
  version: subpackage_callingConnect.calling.connect
  description: Connect a device to an active call
channels:
  /:
    description: Connect a device to an active call
    publish:
      operationId: subpackage_callingConnect.calling.connect-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_callingConnect.calling.connect-server-0-onCallingConnectCallConnectEvent
          - $ref: >-
              #/components/messages/subpackage_callingConnect.calling.connect-server-1-onCallingConnectResponse
    subscribe:
      operationId: subpackage_callingConnect.calling.connect-subscribe
      summary: calling.connect
      message:
        name: callingConnect
        title: calling.connect
        payload:
          $ref: '#/components/schemas/calling.connect_callingConnectRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_callingConnect.calling.connect-server-0-onCallingConnectCallConnectEvent:
      name: onCallingConnectCallConnectEvent
      title: calling.call.connect
      payload:
        $ref: '#/components/schemas/calling.connect_callConnectEvent'
    subpackage_callingConnect.calling.connect-server-1-onCallingConnectResponse:
      name: onCallingConnectResponse
      title: calling.connect response
      payload:
        $ref: '#/components/schemas/calling.connect_callingConnectResponse'
  schemas:
    ChannelsCallingConnectMessagesCallConnectEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingConnectMessagesCallConnectEventJsonrpc
    ChannelsCallingConnectMessagesCallConnectEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingConnectMessagesCallConnectEventMethod
    ChannelsCallingConnectMessagesCallConnectEventParamsEventType:
      type: string
      enum:
        - calling.call.connect
      description: The event type — identifies which event this is.
      title: ChannelsCallingConnectMessagesCallConnectEventParamsEventType
    CallingCallDeviceType:
      type: string
      enum:
        - phone
        - sip
        - webrtc
      title: CallingCallDeviceType
    Calling.CallDevice:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingCallDeviceType'
      required:
        - type
      description: >-
        The negotiated call leg reported in call events. Discriminated on
        `type`.
      title: Calling.CallDevice
    Calling.ConnectPeer:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, scopes the peer call.
            Echo it back on follow-up commands that target it; treat it as
            opaque.
        call_id:
          type: string
          description: The peer call's `call_id`.
        tag:
          type: string
          description: The `tag` set on the peer call.
        queue_id:
          type: string
          description: When the peer was reached through a queue, the queue's id.
        queue_name:
          type: string
          description: Human-readable name of the queue the peer was reached through.
        device:
          $ref: '#/components/schemas/Calling.CallDevice'
          description: The device handling the peer call.
      description: The other call being connected to yours.
      title: Calling.ConnectPeer
    CallingCallConnectParamsConnectState:
      type: string
      enum:
        - disconnected
        - connecting
        - connected
        - failed
      description: >-
        Where the connection stands: `connecting`, `connected`, `disconnected`,
        or `failed`.
      title: CallingCallConnectParamsConnectState
    Calling.CallConnectParams:
      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.
        peer:
          $ref: '#/components/schemas/Calling.ConnectPeer'
          description: The other call yours is being connected to.
        connect_state:
          $ref: '#/components/schemas/CallingCallConnectParamsConnectState'
          description: >-
            Where the connection stands: `connecting`, `connected`,
            `disconnected`, or `failed`.
        failed_reason:
          type: string
          description: Why the connect failed. Present when `connect_state` is `failed`.
      required:
        - node_id
        - call_id
        - connect_state
      title: Calling.CallConnectParams
    ChannelsCallingConnectMessagesCallConnectEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingConnectMessagesCallConnectEventParamsEventType
          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.CallConnectParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingConnectMessagesCallConnectEventParams
    calling.connect_callConnectEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingConnectMessagesCallConnectEventJsonrpc
          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/ChannelsCallingConnectMessagesCallConnectEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsCallingConnectMessagesCallConnectEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires as a connect request progresses, telling you whether your call has
        been bridged to the peer. Watch `connect_state` to know when the two
        calls are joined, torn down, or have failed to connect.
      title: calling.connect_callConnectEvent
    ChannelsCallingConnectMessagesCallingConnectResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingConnectMessagesCallingConnectResponseJsonrpc
    CallingConnectResultMessageDataItemsErrors:
      oneOf:
        - type: string
        - type: object
          additionalProperties:
            description: Any type
      description: >-
        Why this destination failed. Either a string (for example `"Too many
        devices"`)

        or an object describing the errors, typically mapping a field name to a
        list of

        messages, for example

        `{"to": ["The configured SIP Endpoint is not registered."]}`.
      title: CallingConnectResultMessageDataItemsErrors
    CallingConnectResultMessageDataItems:
      type: object
      properties:
        from:
          type: string
          description: The origin used for this destination.
        to:
          type: string
          description: The destination attempted.
        errors:
          $ref: '#/components/schemas/CallingConnectResultMessageDataItemsErrors'
          description: >-
            Why this destination failed. Either a string (for example `"Too many
            devices"`)

            or an object describing the errors, typically mapping a field name
            to a list of

            messages, for example

            `{"to": ["The configured SIP Endpoint is not registered."]}`.
      title: CallingConnectResultMessageDataItems
    Calling.ConnectResult:
      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.
        message_data:
          type: array
          items:
            $ref: '#/components/schemas/CallingConnectResultMessageDataItems'
          description: >-
            Per-destination failures, one entry per destination that could not
            be connected.

            Present when some destinations failed even though the request
            succeeded (`code`

            `"200"`), and on failures such as `"400"` "No valid devices" (the
            array may be

            empty when the request failed before any destination was tried).
      required:
        - code
      title: Calling.ConnectResult
    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.connect_callingConnectResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingConnectMessagesCallingConnectResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Calling.ConnectResult'
          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.connect_callingConnectResponse
    ChannelsCallingConnectMessagesCallingConnectRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingConnectMessagesCallingConnectRequestJsonrpc
    ChannelsCallingConnectMessagesCallingConnectRequestMethod:
      type: string
      enum:
        - calling.connect
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsCallingConnectMessagesCallingConnectRequestMethod
    CallingRingbackType:
      type: string
      enum:
        - audio
        - tts
        - silence
        - ringtone
      title: CallingRingbackType
    Calling.Ringback:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingRingbackType'
      required:
        - type
      description: >-
        Audio played to the caller while a connect is in progress. Discriminated
        on `type`.
      title: Calling.Ringback
    CallingConnectDeviceType:
      type: string
      enum:
        - phone
        - sip
        - fabric
        - call
        - queue
        - stream
      title: CallingConnectDeviceType
    Calling.ConnectDevice:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingConnectDeviceType'
      required:
        - type
      description: >-
        A device to connect to an active call (`calling.connect`). Discriminated
        on `type`.
      title: Calling.ConnectDevice
    Calling.ConnectParams:
      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.
        ringback:
          type: array
          items:
            $ref: '#/components/schemas/Calling.Ringback'
          description: >-
            Audio to play to the existing caller while the new device rings.
            Plays in order until the device answers.
        tag:
          type: string
          description: >-
            Your label for the new call leg. Its `calling.call.*` events carry
            this `tag`.
        devices:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/Calling.ConnectDevice'
          description: >-
            Devices to call and connect. Uses the same layout as `calling.dial`:
            the outer

            array rings groups in sequence, the inner array rings devices in a
            group at

            once, and the first device to answer is the one that gets connected.
            When

            connecting to a `call` or `queue` device, pass exactly one device;
            only the

            first `stream` device is used.
        max_duration:
          type: integer
          minimum: 15
          maximum: 14400
          description: >-
            Maximum length of the connected call, in seconds, from 15 to 14400
            (4 hours). The call ends automatically once this is reached.
            Defaults to 14400; values outside the range are rejected with
            `"400"`.
        timeout:
          type: number
          format: double
          minimum: 1
          description: >-
            Default ring timeout, in seconds, used when a device doesn't set its
            own. Fractions are truncated. Defaults to 60.
        send_digits:
          type: string
          minLength: 1
          maxLength: 98
          description: >-
            DTMF (touch-tone) digits to send once the call is answered: `0`-`9`,
            `*`, `#`,

            and `A`-`D`. Use `w` or `W` to wait and `,` to pause. At most 98
            characters.
        max_price_per_minute:
          type: number
          format: double
          minimum: 0
          description: >-
            Highest price per minute you're willing to pay. Devices that would
            exceed this rate aren't called.
        status_url:
          type: string
          format: uri
          description: >-
            URL to receive `calling.call.connect` events via POST as the
            connection

            progresses through the `connecting`, `connected`, `disconnected`,
            and `failed`

            statuses.
        park_after_bridge:
          type: boolean
          default: true
          description: >-
            What happens to your call when the connected leg hangs up. `true`
            (default) keeps

            your call up and under your control so you can continue with it, for
            example to

            play a message or connect it elsewhere. `false` hangs up your call
            too.
      required:
        - node_id
        - call_id
        - devices
      title: Calling.ConnectParams
    calling.connect_callingConnectRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingConnectMessagesCallingConnectRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingConnectMessagesCallingConnectRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Calling.ConnectParams'
          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.connect_callingConnectRequest

```