> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

# detect

> Start detection (answering machine, fax, DTMF) on a call via REST.

Start a detector on an active call. Detectors can identify answering machines,
fax tones, or DTMF digits. Returns a `control_id` for managing the detector.

## **Request**

### Schema (`calling.detect`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    CallingDetectMachineConfigType:
      type: string
      enum:
        - machine
      title: CallingDetectMachineConfigType
    Calling.DetectMachineParams:
      type: object
      properties:
        initial_timeout:
          type: number
          format: double
          default: 4.5
          description: Maximum time in seconds to wait for initial speech/voice.
        end_silence_timeout:
          type: number
          format: double
          default: 1
          description: Time in seconds of silence after voice ends to finalize the result.
        machine_ready_timeout:
          type: number
          format: double
          description: >-
            Time in seconds to wait for the machine greeting to be ready.
            Defaults to `end_silence_timeout`.
        machine_voice_threshold:
          type: number
          format: double
          default: 1.25
          description: >-
            Voice duration threshold in seconds distinguishing machine from
            human.
        machine_words_threshold:
          type: integer
          default: 6
          description: >-
            Word-count threshold distinguishing machine greetings from human
            speech.
        detect_interruptions:
          type: boolean
          default: false
          description: >-
            If `true`, detect the caller interrupting during the machine
            greeting playback.
        detect_message_end:
          type: boolean
          default: true
          description: If `true`, detect when a machine message has finished.
      description: >-
        Answering-machine detection parameters. Applies only when `detect.type`
        is `machine`.
      title: Calling.DetectMachineParams
    Calling.DetectType:
      type: string
      enum:
        - machine
        - fax
        - digit
      description: The type of detection to perform.
      title: Calling.DetectType
    Calling.DetectMachineConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Calling.DetectType'
          description: The type of detection to perform.
        params:
          $ref: '#/components/schemas/Calling.DetectMachineParams'
          description: Machine-detection parameters.
      required:
        - type
      description: Answering-machine detection configuration.
      title: Calling.DetectMachineConfig
    CallingDetectFaxConfigType:
      type: string
      enum:
        - fax
      title: CallingDetectFaxConfigType
    Calling.DetectFaxTone:
      type: string
      enum:
        - CNG
        - CED
        - cng
        - ced
      description: Fax tone to detect.
      title: Calling.DetectFaxTone
    Calling.DetectFaxParams:
      type: object
      properties:
        tone:
          $ref: '#/components/schemas/Calling.DetectFaxTone'
          description: The fax tone to detect. Omitted means either tone matches.
      description: Fax-tone detection parameters. Applies only when `detect.type` is `fax`.
      title: Calling.DetectFaxParams
    Calling.DetectFaxConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Calling.DetectType'
          description: The type of detection to perform.
        params:
          $ref: '#/components/schemas/Calling.DetectFaxParams'
          description: Fax-detection parameters.
      required:
        - type
      description: Fax-tone detection configuration.
      title: Calling.DetectFaxConfig
    CallingDetectDigitConfigType:
      type: string
      enum:
        - digit
      title: CallingDetectDigitConfigType
    Calling.DetectDigitParams:
      type: object
      properties:
        digits:
          type: string
          description: >-
            Set of DTMF digits to match. Allowed: `0-9`, `A-D` (case
            insensitive), `*`, `#`. Empty string matches any digit.
      description: >-
        DTMF-digit detection parameters. Applies only when `detect.type` is
        `digit`.
      title: Calling.DetectDigitParams
    Calling.DetectDigitConfig:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Calling.DetectType'
          description: The type of detection to perform.
        params:
          $ref: '#/components/schemas/Calling.DetectDigitParams'
          description: Digit-detection parameters.
      required:
        - type
      description: DTMF-digit detection configuration.
      title: Calling.DetectDigitConfig
    CallingCallRequestDiscriminatorMappingCallingDetectParamsDetect:
      oneOf:
        - $ref: '#/components/schemas/Calling.DetectMachineConfig'
        - $ref: '#/components/schemas/Calling.DetectFaxConfig'
        - $ref: '#/components/schemas/Calling.DetectDigitConfig'
      description: Detection configuration specifying what to detect.
      title: CallingCallRequestDiscriminatorMappingCallingDetectParamsDetect
    CallingCallRequestDiscriminatorMappingCallingDetectParams:
      type: object
      properties:
        control_id:
          type: string
          description: >-
            Unique identifier for this detect operation, used to control it
            later. Must be unique per active detect on this call.
        detect:
          $ref: >-
            #/components/schemas/CallingCallRequestDiscriminatorMappingCallingDetectParamsDetect
          description: Detection configuration specifying what to detect.
        timeout:
          type: number
          format: double
          default: 30
          description: Maximum time in seconds the detection may run before timing out.
        status_url:
          type: string
          format: uri
          description: HTTP or HTTPS URL that receives detection result webhooks.
      required:
        - control_id
        - detect
      description: An object of parameters that will be utilized by the active command.
      title: CallingCallRequestDiscriminatorMappingCallingDetectParams
    Calling.CallDetectRequest:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: The unique identifying ID of a existing call.
        params:
          $ref: >-
            #/components/schemas/CallingCallRequestDiscriminatorMappingCallingDetectParams
          description: An object of parameters that will be utilized by the active command.
      required:
        - id
        - params
      title: Calling.CallDetectRequest
```

## **Response**

### Schema (`Calling.CallResponse`)

```yaml
components:
  schemas:
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    Calling.CallDirection:
      type: string
      enum:
        - inbound
        - outbound
        - outbound-api
      description: The direction of the call.
      title: Calling.CallDirection
    CallingCallLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingCallLegSource
    Calling.ChargeDetails:
      type: object
      properties:
        description:
          type: string
          description: Description for this charge.
        charge:
          type: number
          format: double
          description: Charged amount.
      required:
        - description
        - charge
      title: Calling.ChargeDetails
    Calling.CallResponseStatus:
      type: string
      enum:
        - queued
        - initiated
        - created
        - ringing
        - answered
        - ending
        - ended
        - failed
        - canceled
        - completed
      description: The status of the call throughout its lifecycle.
      title: Calling.CallResponseStatus
    CallingCallLegType0:
      type: string
      enum:
        - relay_pstn_call
      title: CallingCallLegType0
    CallingCallLegType1:
      type: string
      enum:
        - relay_sip_call
      title: CallingCallLegType1
    CallingCallLegType2:
      type: string
      enum:
        - relay_webrtc_call
      title: CallingCallLegType2
    CallingCallLegType:
      oneOf:
        - $ref: '#/components/schemas/CallingCallLegType0'
        - $ref: '#/components/schemas/CallingCallLegType1'
        - $ref: '#/components/schemas/CallingCallLegType2'
      description: Type of this call.
      title: CallingCallLegType
    Calling.CallLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingCallLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          oneOf:
            - $ref: '#/components/schemas/Calling.CallResponseStatus'
            - type: 'null'
          description: The status of the call.
        duration:
          type:
            - integer
            - 'null'
          description: The duration of the call in seconds.
        duration_ms:
          type:
            - integer
            - 'null'
          description: The duration of the call in milliseconds.
        billing_ms:
          type:
            - integer
            - 'null'
          description: The billable duration of the call in milliseconds.
        type:
          $ref: '#/components/schemas/CallingCallLegType'
          description: Type of this call.
        parent_id:
          oneOf:
            - $ref: '#/components/schemas/uuid'
            - type: 'null'
          description: The parent call ID if this is a child call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - duration
        - duration_ms
        - billing_ms
        - type
        - parent_id
      description: Returned when the call is a standard PSTN, SIP, or WebRTC call.
      title: Calling.CallLeg
    CallingFabricDeviceLegSource:
      type: string
      enum:
        - realtime_api
      description: Source of this call.
      title: CallingFabricDeviceLegSource
    CallingFabricDeviceLegType:
      type: string
      enum:
        - fabric_subscriber_device_leg
      description: Type of this call.
      title: CallingFabricDeviceLegType
    Calling.FabricDeviceLeg:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the call on SignalWire. This can be used to
            update the call programmatically.
        from:
          type: string
          description: The origin number or address.
        to:
          type: string
          description: The destination number or address.
        direction:
          $ref: '#/components/schemas/Calling.CallDirection'
          description: The direction of the call.
        source:
          $ref: '#/components/schemas/CallingFabricDeviceLegSource'
          description: Source of this call.
        url:
          type:
            - string
            - 'null'
          description: The URL associated with this call.
        charge:
          type: number
          format: double
          description: Total charge for this call.
        created_at:
          type: string
          format: date-time
          description: The date and time when the call was created.
        charge_details:
          type: array
          items:
            $ref: '#/components/schemas/Calling.ChargeDetails'
          description: Details on charges associated with this call.
        status:
          description: >-
            The status of the call. Always null for Fabric subscriber device
            legs.
        type:
          $ref: '#/components/schemas/CallingFabricDeviceLegType'
          description: Type of this call.
      required:
        - id
        - from
        - to
        - direction
        - source
        - url
        - charge
        - created_at
        - charge_details
        - status
        - type
      description: >-
        Returned when the call is a Fabric subscriber device leg. The `status`
        field is always null for this type.
      title: Calling.FabricDeviceLeg
    Calling.CallResponse:
      oneOf:
        - $ref: '#/components/schemas/Calling.CallLeg'
        - $ref: '#/components/schemas/Calling.FabricDeviceLeg'
      title: Calling.CallResponse
```

## **Examples**

### Answering Machine Detection

```python {10}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

# Answering machine detection
result = client.calling.detect(
    call_id="call-id-xxx",
    detect={
        "type": "machine",
        "params": {
            "initial_timeout": 4.5,
            "end_silence_timeout": 1.0,
        }
    },
    timeout=30.0,
)
```

### Fax Detection

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

result = client.calling.detect(
    call_id="call-id-xxx",
    detect={"type": "fax", "params": {"tone": "CED"}}
)
```

### Digit Detection

```python {9}
from signalwire.rest import RestClient

client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)

result = client.calling.detect(
    call_id="call-id-xxx",
    detect={"type": "digit", "params": {"digits": "0123456789#*"}}
)
```