Skip to main content
Get startedGuidesTechnical Reference

detect_machine

A detection method that combines AMD (Answering Machine Detection) and fax detection. Detect whether the user on the other end of the call is a machine (fax, voicemail, etc.) or a human. The detection result(s) will be sent to the specified status_url as a POST request and will also be saved in the detect_result variable.

detect_machine
objectrequired

An object that accepts the detect_machine parameters.

detect_machine parameters​

detect_machine.detect_message_end
boolean
Default: false

If true, stops detection on beep / end of voicemail greeting.

detect_machine.detectors
string
Default: amd,fax

Comma-separated string of detectors to enable. Valid Values: amd, fax

detect_machine.end_silence_timeout
number
Default: 1.0

How long to wait for voice activity to finish (in seconds).

detect_machine.initial_timeout
number
Default: 4.5

How long to wait for initial voice activity before giving up (in seconds).

detect_machine.machine_ready_timeout
number
Default: value of the end_silence_timeout parameter

How long to wait for voice activity to finish before firing the READY event (in seconds).

detect_machine.machine_voice_threshold
number
Default: 1.25

The number of seconds of ongoing voice activity required to classify as MACHINE.

detect_machine.machine_words_threshold
integer
Default: 6

The minimum number of words that must be detected in a single utterance before classifying the call as MACHINE.

detect_machine.status_url
string

The HTTP(S) URL to deliver detector events to. Learn more about status callbacks.

detect_machine.timeout
number
Default: 30.0

The maximum time to run the detector (in seconds).

detect_machine.tone
string
Default: CED

The tone to detect. Only the remote side tone will be received. (CED or CNG) Used for fax detection.

detect_machine.wait
boolean
Default: true

If false, the detector will run asynchronously and status_url must be set. If true, the detector will wait for detection to complete before moving to the next SMWL instruction.

Variables​

The following variables are available after the detect_machine method is executed and detection is complete. You can reference these variables in your SMWL script utilizing the ${variable} syntax.

detect_result
human | machine | fax | unknown

The result of detection.

detect_machine_beep
true | false

Whether a beep was detected. true if detected.

detect_ms
integer

The number of milliseconds the detection took.

StatusCallbacks​

A POST request will be sent to status_url with a JSON payload like the following:

event_type
string

The type of event, always calling.call.detect for this method.

event_channel
string

The channel for the event, includes the SWML session ID.

timestamp
number

Unix timestamp (float) when the event was generated.

project_id
string

The project ID associated with the call.

space_id
string

The space ID associated with the call.

params
object

An object containing detection-specific parameters.

params.control_id
string

The control ID for this detect operation.

params.detect
object

Detection result details (see subfields below).

params.detect.type
string

The type of detection. Valid values: machine or fax.

params.detect.params.event
string

The detection result. Valid values: HUMAN, MACHINE, FAX, UNKNOWN, finished.

params.call_id
string

The call ID.

params.node_id
string

The node handling the call.

params.segment_id
string

The segment ID for this part of the call.

Raw JSON example​

{
  "event_type": "calling.call.detect",
  "event_channel": "swml:be38xxxx-8xxx-4xxxx-9fxx-bxxxxxxxxx",
  "timestamp": 1745332535.668522,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "detect": {
      "type": "machine",
      "params": {
        "event": "HUMAN"
      }
    },
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "segment_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Examples​

Play the detection result​

version: 1.0.0
sections:
  main:
    - detect_machine:
        status_url: 'https://example.com/detect-events'
        timeout: 20
    - play:
        url: 'say:Detection result: ${detect_result}'

Conditional actions based on the detection result​

version: 1.0.0
sections:
  main:
    - play:
        url: "say: Welcome to the machine detection test."
    - detect_machine:
        status_url: "https://webhook.site/5c8abf82-b8c7-41c8-b5d6-b32a40068109"
        detectors: "amd,fax"
        wait: true
    - cond:
        - when: detect_result == 'machine'
          then:
            - play:
                url: "say: You are a machine, goodbye."
            - hangup: {}
        - when: detect_result == 'human'
          then:
            - play:
                url: "say: You are a human, hello."
            - hangup: {}
        - when: detect_result == 'fax'
          then:
            - play:
                url: "say: You are a fax, goodbye."
            - hangup: {}
        - else:
            - play:
                url: "say: Unable to determine if you are a human, machine, or fax, goodbye. Result was ${detect_result}"
            - hangup: {}