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

GET /

Start a detector (machine/fax/digit)

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

## AsyncAPI Specification

```yaml
asyncapi: 2.6.0
info:
  title: calling.detect
  version: subpackage_callingDetect.calling.detect
  description: Start a detector (machine/fax/digit)
channels:
  /:
    description: Start a detector (machine/fax/digit)
    publish:
      operationId: subpackage_callingDetect.calling.detect-publish
      summary: Server messages
      message:
        oneOf:
          - $ref: >-
              #/components/messages/subpackage_callingDetect.calling.detect-server-0-onCallingDetectCallDetectEvent
          - $ref: >-
              #/components/messages/subpackage_callingDetect.calling.detect-server-1-onCallingDetectResponse
    subscribe:
      operationId: subpackage_callingDetect.calling.detect-subscribe
      summary: calling.detect
      message:
        name: callingDetect
        title: calling.detect
        payload:
          $ref: '#/components/schemas/calling.detect_callingDetectRequest'
servers:
  production:
    url: wss://relay.signalwire.com/
    protocol: wss
    x-default: true
components:
  messages:
    subpackage_callingDetect.calling.detect-server-0-onCallingDetectCallDetectEvent:
      name: onCallingDetectCallDetectEvent
      title: calling.call.detect
      payload:
        $ref: '#/components/schemas/calling.detect_callDetectEvent'
    subpackage_callingDetect.calling.detect-server-1-onCallingDetectResponse:
      name: onCallingDetectResponse
      title: calling.detect response
      payload:
        $ref: '#/components/schemas/calling.detect_callingDetectResponse'
  schemas:
    ChannelsCallingDetectMessagesCallDetectEventJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingDetectMessagesCallDetectEventJsonrpc
    ChannelsCallingDetectMessagesCallDetectEventMethod:
      type: string
      enum:
        - signalwire.event
      description: Always `signalwire.event`.
      title: ChannelsCallingDetectMessagesCallDetectEventMethod
    ChannelsCallingDetectMessagesCallDetectEventParamsEventType:
      type: string
      enum:
        - calling.call.detect
      description: The event type — identifies which event this is.
      title: ChannelsCallingDetectMessagesCallDetectEventParamsEventType
    CallingCallDetectResultType:
      type: string
      enum:
        - digit
        - fax
        - machine
      title: CallingCallDetectResultType
    Calling.CallDetectResult:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingCallDetectResultType'
      required:
        - type
      description: >-
        What the detector found. Read `type` to know which detector reported it:
        `fax`,

        `machine`, or `digit`. Whatever the type, the `event` field also carries
        the

        generic `finished` value when the detector completes.
      title: Calling.CallDetectResult
    Calling.CallDetectParams:
      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.
        control_id:
          type: string
          description: >-
            The `control_id` of the detector this event refers to, returned when
            you started it with `calling.detect`.
        detect:
          $ref: '#/components/schemas/Calling.CallDetectResult'
          description: >-
            What the detector found, including which kind of detector reported
            it.
      required:
        - node_id
        - call_id
        - control_id
        - detect
      title: Calling.CallDetectParams
    ChannelsCallingDetectMessagesCallDetectEventParams:
      type: object
      properties:
        event_type:
          $ref: >-
            #/components/schemas/ChannelsCallingDetectMessagesCallDetectEventParamsEventType
          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.CallDetectParams'
          description: The event-specific payload.
      required:
        - event_type
        - event_channel
        - timestamp
        - params
      description: The event envelope.
      title: ChannelsCallingDetectMessagesCallDetectEventParams
    calling.detect_callDetectEvent:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingDetectMessagesCallDetectEventJsonrpc
          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/ChannelsCallingDetectMessagesCallDetectEventMethod
          description: Always `signalwire.event`.
        params:
          $ref: >-
            #/components/schemas/ChannelsCallingDetectMessagesCallDetectEventParams
          description: The event envelope.
      required:
        - jsonrpc
        - id
        - method
        - params
      description: >-
        Fires when a detector reports a result — a fax tone, an answering
        machine versus a human, or a DTMF digit.
      title: calling.detect_callDetectEvent
    ChannelsCallingDetectMessagesCallingDetectResponseJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingDetectMessagesCallingDetectResponseJsonrpc
    Calling.DetectResult:
      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.
        call_id:
          type: string
          description: The call this result is for, echoed from your request.
        control_id:
          type: string
          description: >-
            Your control identifier for the started action, echoed from your
            request.
      required:
        - code
      title: Calling.DetectResult
    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.detect_callingDetectResponse:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingDetectMessagesCallingDetectResponseJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: The id of the request this responds to.
        result:
          $ref: '#/components/schemas/Calling.DetectResult'
          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.detect_callingDetectResponse
    ChannelsCallingDetectMessagesCallingDetectRequestJsonrpc:
      type: string
      enum:
        - '2.0'
      description: JSON-RPC version. Always `2.0`.
      title: ChannelsCallingDetectMessagesCallingDetectRequestJsonrpc
    ChannelsCallingDetectMessagesCallingDetectRequestMethod:
      type: string
      enum:
        - calling.detect
      description: The name of the JSON-RPC method being invoked.
      title: ChannelsCallingDetectMessagesCallingDetectRequestMethod
    CallingDetectConfigMachineType:
      type: string
      enum:
        - machine
      description: '`machine` (answering machine / voicemail).'
      title: CallingDetectConfigMachineType
    Calling.DetectMachineParams:
      type: object
      properties:
        initial_timeout:
          type: number
          format: double
          minimum: 1
          description: >-
            How many seconds to wait for initial voice before giving up. Must be
            at least `1`. Default `4.5`.
        end_silence_timeout:
          type: number
          format: double
          minimum: 1
          description: >-
            How many seconds to wait for voice to finish. Must be at least `1`.
            Default `1.0`.
        machine_ready_timeout:
          type: number
          format: double
          minimum: 1
          description: |-
            How many seconds to wait for voice to finish before firing the READY
            event. Must be at least `1`. Defaults to `end_silence_timeout`.
        machine_voice_threshold:
          type: number
          format: double
          minimum: 1
          description: >-
            How many seconds of continuous voice are required before the result
            is reported as MACHINE. Must be at least `1`. Default `1.25`.
        machine_words_threshold:
          type: integer
          minimum: 1
          description: >-
            How many words must be counted before the result is reported as
            MACHINE. Must be at least `1`. Default `6`.
        detect_interruptions:
          type: boolean
          default: false
          description: >-
            If `true`, a NOT_READY event fires if voice activity is detected
            after READY.

            This lets your application restart message delivery to the answering
            machine.

            Default `false`.
        detect_message_end:
          type: boolean
          default: true
          description: >-
            If `false`, stop detection at the MACHINE event instead of waiting
            for the

            beep / end of the voicemail greeting. Default `true`.
      description: Configuration for the answering-machine (voicemail) detector.
      title: Calling.DetectMachineParams
    Calling.DetectConfigMachine:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingDetectConfigMachineType'
          description: '`machine` (answering machine / voicemail).'
        params:
          $ref: '#/components/schemas/Calling.DetectMachineParams'
          description: >-
            Tuning for the machine detector. Required, but every field inside is
            optional: send `{}` to use the defaults.
      required:
        - type
        - params
      description: Run the answering-machine (voicemail) detector.
      title: Calling.DetectConfigMachine
    CallingDetectConfigFaxType:
      type: string
      enum:
        - fax
      description: '`fax` (fax tone).'
      title: CallingDetectConfigFaxType
    Calling.DetectFaxTone:
      type: string
      enum:
        - CED
        - CNG
        - ced
        - cng
      title: Calling.DetectFaxTone
    Calling.DetectFaxParams:
      type: object
      properties:
        tone:
          $ref: '#/components/schemas/Calling.DetectFaxTone'
          description: Which fax tone to listen for on the far end. Default `CED`.
      description: Configuration for the fax-tone detector.
      title: Calling.DetectFaxParams
    Calling.DetectConfigFax:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingDetectConfigFaxType'
          description: '`fax` (fax tone).'
        params:
          $ref: '#/components/schemas/Calling.DetectFaxParams'
          description: >-
            Tuning for the fax detector. Required, but `tone` is optional: send
            `{}` to use the default. Only `tone` is accepted.
      required:
        - type
        - params
      description: Run the fax-tone detector.
      title: Calling.DetectConfigFax
    CallingDetectConfigDigitType:
      type: string
      enum:
        - digit
      description: '`digit` (DTMF).'
      title: CallingDetectConfigDigitType
    Calling.DetectDigitParams:
      type: object
      properties:
        digits:
          type: string
          description: Digits to detect. Default `0123456789#*`.
      description: Configuration for the digit detector.
      title: Calling.DetectDigitParams
    Calling.DetectConfigDigit:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/CallingDetectConfigDigitType'
          description: '`digit` (DTMF).'
        params:
          $ref: '#/components/schemas/Calling.DetectDigitParams'
          description: >-
            Tuning for the digit detector. Required, but `digits` is optional:
            send `{}` to use the default. Only `digits` is accepted.
      required:
        - type
        - params
      description: Run the DTMF digit detector.
      title: Calling.DetectConfigDigit
    Calling.DetectConfig:
      oneOf:
        - $ref: '#/components/schemas/Calling.DetectConfigMachine'
        - $ref: '#/components/schemas/Calling.DetectConfigFax'
        - $ref: '#/components/schemas/Calling.DetectConfigDigit'
      title: Calling.DetectConfig
    Calling.DetectParams:
      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.
        control_id:
          type: string
          description: >-
            Your own identifier for this detector. It's attached to the
            `calling.call.detect` events so you can correlate them, and you pass
            it to `calling.detect.stop` to stop the detector.
        detect:
          $ref: '#/components/schemas/Calling.DetectConfig'
          description: >-
            The detector to run. Set `type` to `machine`, `fax`, or `digit`, and
            supply that detector's `params` (send `{}` for the defaults).
        timeout:
          type: number
          format: double
          minimum: 0
          description: >-
            Maximum time, in seconds, to run the detector before it stops on its
            own. Default `30.0`.
      required:
        - node_id
        - call_id
        - control_id
        - detect
      title: Calling.DetectParams
    calling.detect_callingDetectRequest:
      type: object
      properties:
        jsonrpc:
          $ref: >-
            #/components/schemas/ChannelsCallingDetectMessagesCallingDetectRequestJsonrpc
          description: JSON-RPC version. Always `2.0`.
        id:
          type: string
          description: Request id, echoed on the correlated response.
        method:
          $ref: >-
            #/components/schemas/ChannelsCallingDetectMessagesCallingDetectRequestMethod
          description: The name of the JSON-RPC method being invoked.
        params:
          $ref: '#/components/schemas/Calling.DetectParams'
          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.detect_callingDetectRequest

```