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

GET /

Receive call-state changes

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

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.call.state
  version: subpackage_callingCallState.calling.call.state
  description: Receive call-state changes
channels:
  /:
    description: Receive call-state changes
    publish:
      operationId: subpackage_callingCallState.calling.call.state-publish
      summary: calling.call.state
      message:
        name: onCallingCallStateCallStateEvent
        title: calling.call.state
        payload:
          $ref: '#/components/schemas/calling.call.state_callStateEvent'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  schemas:
    ChannelsCallingCallStateMessagesCallStateEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingCallStateMessagesCallStateEventJsonrpc
    ChannelsCallingCallStateMessagesCallStateEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingCallStateMessagesCallStateEventMethod
    ChannelsCallingCallStateMessagesCallStateEventParamsEventType:
      type: string
      enum:
        - calling.call.state
      description: The event type — identifies which event this is.
      title: ChannelsCallingCallStateMessagesCallStateEventParamsEventType
    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
    CallingCallStateParamsDialWinner:
      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: CallingCallStateParamsDialWinner
    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.CallStateParams:
      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.
        start_time:
          type: integer
          format: int64
          description: >-
            When the call started, in epoch milliseconds. Always emitted; `0`
            until known.
        answer_time:
          type: integer
          format: int64
          description: >-
            When the call was answered, in epoch milliseconds. Always emitted;
            `0` until known.
        end_time:
          type: integer
          format: int64
          description: >-
            When the call ended, in epoch milliseconds. Always emitted; `0`
            until known.
        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/CallingCallStateParamsDialWinner'
          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"`).
        audio_in_mos:
          type: number
          format: double
          description: >-
            Inbound-audio Mean Opinion Score (voice quality, ~1.0-5.0). Present
            when media (RTP) quality stats are available.
        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
        - start_time
        - answer_time
        - end_time
      description: >-
        Payload of the `calling.call.state` event: the call's address, state,
        timing, and leg detail.
      title: Calling.CallStateParams
    ChannelsCallingCallStateMessagesCallStateEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingCallStateMessagesCallStateEventParamsEventType
          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.CallStateParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingCallStateMessagesCallStateEventParams
    calling.call.state_callStateEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingCallStateMessagesCallStateEventJsonrpc
          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/ChannelsCallingCallStateMessagesCallStateEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsCallingCallStateMessagesCallStateEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires every time one of your calls changes state. Use the `call_state`
        field to track the call through its lifecycle, and `tag` to match the
        event back to the call you placed.
      title: calling.call.state_callStateEvent

```