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

GET /

Dial outbound call(s); first to answer wins

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

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.dial
  version: subpackage_callingDial.calling.dial
  description: Dial outbound call(s); first to answer wins
channels:
  /:
    description: Dial outbound call(s); first to answer wins
    publish:
      operationId: subpackage_callingDial.calling.dial-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_callingDial.calling.dial-server-0-onCallingDialCallDialEvent
          - $ref: >-
              #/components/messages/subpackage_callingDial.calling.dial-server-1-onCallingDialResponse
    subscribe:
      operationId: subpackage_callingDial.calling.dial-subscribe
      summary: calling.dial
      message:
        name: callingDial
        title: calling.dial
        payload:
          $ref: '#/components/schemas/calling.dial_callingDialRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_callingDial.calling.dial-server-0-onCallingDialCallDialEvent:
      name: onCallingDialCallDialEvent
      title: calling.call.dial
      payload:
        $ref: '#/components/schemas/calling.dial_callDialEvent'
    subpackage_callingDial.calling.dial-server-1-onCallingDialResponse:
      name: onCallingDialResponse
      title: calling.dial response
      payload:
        $ref: '#/components/schemas/calling.dial_callingDialResponse'
  schemas:
    ChannelsCallingDialMessagesCallDialEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingDialMessagesCallDialEventJsonrpc
    ChannelsCallingDialMessagesCallDialEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingDialMessagesCallDialEventMethod
    ChannelsCallingDialMessagesCallDialEventParamsEventType:
      type: string
      enum:
        - calling.call.dial
      description: The event type — identifies which event this is.
      title: ChannelsCallingDialMessagesCallDialEventParamsEventType
    CallingCallDialParamsDialState:
      type: string
      enum:
        - dialing
        - answered
        - failed
      description: 'Where the dial stands: `dialing`, `answered`, or `failed`.'
      title: CallingCallDialParamsDialState
    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.CallParentRef:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses the parent
            call. Echo back the value you received; treat it as opaque.
        call_id:
          type: string
          description: The parent call's `call_id`.
        device_type:
          type: string
          description: The parent's device type, such as `sip`.
      description: The call that created this one, when it was spawned by another call.
      title: Calling.CallParentRef
    Calling.CallPeerRef:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, addresses the peer
            call. Echo back the value you received; treat it as opaque.
        call_id:
          type: string
          description: The peer call's `call_id`.
      description: The other call this one is bridged to.
      title: Calling.CallPeerRef
    Calling.CallState:
      type: string
      enum:
        - created
        - ringing
        - answered
        - ending
        - ended
      title: Calling.CallState
    Calling.CallDirection:
      type: string
      enum:
        - inbound
        - outbound
      title: Calling.CallDirection
    Calling.CallStateEndReason:
      type: string
      enum:
        - hangup
        - cancel
        - busy
        - noAnswer
        - decline
        - error
        - abandoned
        - maxDuration
        - notFound
      title: Calling.CallStateEndReason
    Calling.CallStateEndSource:
      type: string
      enum:
        - inbound
        - outbound
        - none
      title: Calling.CallStateEndSource
    CallingCallDialCallDialWinner:
      type: string
      enum:
        - 'true'
      description: >-
        Set to the string `"true"` on the call that won a `calling.dial` race.
        Absent otherwise. Note the value is the string `"true"`, not a JSON
        boolean.
      title: CallingCallDialCallDialWinner
    Calling.CallSipData:
      type: object
      properties:
        sip_req_user:
          type: string
          description: Request-URI user part.
        sip_req_uri:
          type: string
          description: Request-URI user@host.
        sip_req_host:
          type: string
          description: Request-URI host.
        sip_from_user:
          type: string
          description: From-header user part.
        sip_from_uri:
          type: string
          description: From-header user@host.
        sip_from_host:
          type: string
          description: From-header host.
        sip_to_user:
          type: string
          description: To-header user part.
        sip_to_uri:
          type: string
          description: To-header user@host.
        sip_to_host:
          type: string
          description: To-header host.
        sip_contact_user:
          type: string
          description: Contact-header user part.
        sip_contact_port:
          type: string
          description: Contact-header port.
        sip_contact_uri:
          type: string
          description: Contact-header user@host[:port].
        sip_contact_host:
          type: string
          description: Contact-header host.
        sip_from_params:
          type: object
          additionalProperties:
            type: string
          description: Parsed From-URI parameters (`key=value` pairs).
        sip_to_params:
          type: object
          additionalProperties:
            type: string
          description: Parsed To-URI parameters (`key=value` pairs).
        sip_contact_params:
          type: object
          additionalProperties:
            type: string
          description: Parsed Contact-URI parameters (`key=value` pairs).
        sip_req_params:
          type: object
          additionalProperties:
            type: string
          description: Parsed Request-URI parameters (`key=value` pairs).
        sip_p_asserted_identity:
          type: string
          description: The `P-Asserted-Identity` header value, when present.
      description: >-
        Present only for SIP calls (`device.type == "sip"`). SIP
        addressing/header detail extracted from the inbound INVITE. Every
        sub-field is optional and appears only when the corresponding SIP header
        was present.
      title: Calling.CallSipData
    Calling.CallDialCall:
      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.
        device:
          $ref: '#/components/schemas/Calling.CallDevice'
          description: >-
            The device handling this call. Always present, but may be an empty
            object until the device type is determined.
        parent:
          $ref: '#/components/schemas/Calling.CallParentRef'
          description: >-
            Present when this call was created by another call, describing that
            originating call.
        peer:
          $ref: '#/components/schemas/Calling.CallPeerRef'
          description: >-
            Present when this call is bridged to another, describing the other
            call.
        call_state:
          $ref: '#/components/schemas/Calling.CallState'
          description: The state the call has just moved into.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: Whether the call is inbound or outbound.
        end_reason:
          $ref: '#/components/schemas/Calling.CallStateEndReason'
          description: Why the call ended. Present once the call has ended.
        end_source:
          $ref: '#/components/schemas/Calling.CallStateEndSource'
          description: >-
            Which side ended the call — `inbound` or `outbound` — or `none` when
            not applicable. Present once the call has ended.
        dial_winner:
          $ref: '#/components/schemas/CallingCallDialCallDialWinner'
          description: >-
            Set to the string `"true"` on the call that won a `calling.dial`
            race. Absent otherwise. Note the value is the string `"true"`, not a
            JSON boolean.
        sip_data:
          $ref: '#/components/schemas/Calling.CallSipData'
          description: >-
            SIP addressing/header detail. Present only for SIP calls
            (`device.type == "sip"`).
        address_id:
          type: string
          description: >-
            For calls placed by or to a Call Fabric subscriber, the Fabric
            address ID involved. Absent otherwise.
        subscriber_id:
          type: string
          description: >-
            For calls placed by or to a Call Fabric subscriber, the subscriber's
            ID. Absent otherwise.
        subscriber_name:
          type: string
          description: >-
            For calls placed by or to a Call Fabric subscriber, the subscriber's
            display name. Absent otherwise.
      required:
        - node_id
        - call_id
        - call_state
        - direction
      description: >-
        The call that answered a `calling.dial`. Same fields as a
        `calling.call.state` payload, except that it carries no `start_time`,
        `answer_time`, `end_time`, or `audio_in_mos`.
      title: Calling.CallDialCall
    Calling.CallDialParams:
      type: object
      properties:
        node_id:
          type: string
          description: >-
            Opaque identifier that, paired with `call_id`, scopes this dial and
            its resulting call. Echo it back on follow-up commands; treat it as
            opaque.
        tag:
          type: string
          description: >-
            The `tag` you set on the `calling.dial` request, so you can match
            this event to it.
        dial_state:
          $ref: '#/components/schemas/CallingCallDialParamsDialState'
          description: 'Where the dial stands: `dialing`, `answered`, or `failed`.'
        call:
          $ref: '#/components/schemas/Calling.CallDialCall'
          description: >-
            The call that answered. Present only when `dial_state` is
            `answered`; the winning leg is marked by `dial_winner`.
        reason:
          type: string
          description: Why the dial failed. Present when `dial_state` is `failed`.
        source:
          type: string
          description: >-
            Which side ended the dial: `outbound` if your side hung up,
            `inbound` if the far end did, `none` if unknown. Pairs with `reason`
            (why it failed) and mirrors `end_source`/`end_reason` on call-ended
            events. Present when `dial_state` is `failed`.
      required:
        - node_id
        - tag
        - dial_state
      title: Calling.CallDialParams
    ChannelsCallingDialMessagesCallDialEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingDialMessagesCallDialEventParamsEventType
          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.CallDialParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingDialMessagesCallDialEventParams
    calling.dial_callDialEvent:
      type: object
      properties:
        jsonrpc:
          $ref: '#/components/schemas/ChannelsCallingDialMessagesCallDialEventJsonrpc'
          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/ChannelsCallingDialMessagesCallDialEventMethod'
          description: Always `signalwire.event`.
        params:
          $ref: '#/components/schemas/ChannelsCallingDialMessagesCallDialEventParams'
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires as a `calling.dial` request progresses. Watch `dial_state` to know
        when your call is ringing, has been answered, or failed; when it is
        answered the `call` field gives you the call that picked up.
      title: calling.dial_callDialEvent
    ChannelsCallingDialMessagesCallingDialResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingDialMessagesCallingDialResponseJsonrpc
    CallingDialResultMessageDataItemsErrors:
      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: CallingDialResultMessageDataItemsErrors
    CallingDialResultMessageDataItems:
      type: object
      properties:
        from:
          type: string
          description: The origin used for this destination.
        to:
          type: string
          description: The destination attempted.
        errors:
          $ref: '#/components/schemas/CallingDialResultMessageDataItemsErrors'
          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: CallingDialResultMessageDataItems
    Calling.DialResult:
      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/CallingDialResultMessageDataItems'
          description: >-
            Per-destination failures, one entry per destination that could not
            be dialed.

            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.DialResult
    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.dial_callingDialResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingDialMessagesCallingDialResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Calling.DialResult'
          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.dial_callingDialResponse
    ChannelsCallingDialMessagesCallingDialRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingDialMessagesCallingDialRequestJsonrpc
    ChannelsCallingDialMessagesCallingDialRequestMethod:
      type: string
      enum:
        - calling.dial
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsCallingDialMessagesCallingDialRequestMethod
    CallingDialDeviceType:
      type: string
      enum:
        - phone
        - sip
      title: CallingDialDeviceType
    Calling.DialDevice:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingDialDeviceType'
      required:
        - type
      description: A device to dial (`calling.dial`). Discriminated on `type`.
      title: Calling.DialDevice
    Calling.DialParams:
      type: object
      properties:
        tag:
          type: string
          description: >-
            Your label for this dial. Every resulting `calling.call.*` and
            `calling.call.dial` event carries this `tag`, so use it to match
            events back to this request. Optional, but set it: the dial result
            returns no `call_id`, so this tag is your only handle for
            correlating the resulting call and its events.
        devices:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/Calling.DialDevice'
          description: >-
            Devices to dial. The outer array is sequential ringing groups; the
            inner

            array is simultaneous (parallel) dials within a group. The first
            device to

            answer wins. Up to 20 devices in total; devices beyond the limit are
            skipped

            and reported in the result's `message_data`.
        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 dialed.
      required:
        - devices
      title: Calling.DialParams
    calling.dial_callingDialRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingDialMessagesCallingDialRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingDialMessagesCallingDialRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Calling.DialParams'
          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.dial_callingDialRequest

```