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.

Properties

objectRequired

An object that accepts the following properties.

detect_machine.detect_message_end

booleanDefaults to false

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

detect_machine.detectors

stringDefaults to amd,fax

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

detect_machine.end_silence_timeout

numberDefaults to 1.0

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

detect_machine.initial_timeout

numberDefaults to 4.5

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

detect_machine.machine_ready_timeout

numberDefaults to 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

numberDefaults to 1.25

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

detect_machine.machine_words_threshold

integerDefaults to 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

numberDefaults to 30.0

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

detect_machine.tone

stringDefaults to CED

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

detect_machine.wait

booleanDefaults to 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 SWML 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).

detect.type

string

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

detect.params.event

string

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

detect.params.beep

boolean

Present and set to true when a beep was detected. Absent when no beep has been detected.

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

1 {
2   "event_type": "calling.call.detect",
3   "event_channel": "swml:be38xxxx-8xxx-4xxxx-9fxx-bxxxxxxxxx",
4   "timestamp": 1745332535.668522,
5   "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
6   "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
7   "params": {
8     "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
9     "detect": {
10       "type": "machine",
11       "params": {
12         "event": "MACHINE",
13         "beep": true
14       }
15     },
16     "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
17     "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
18     "segment_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
19   }
20 }

Examples

Play the detection result

1 version: 1.0.0
2 sections:
3   main:
4     - detect_machine:
5         status_url: 'https://example.com/detect-events'
6         timeout: 20
7     - play:
8         url: 'say:Detection result: ${detect_result}'

Conditional actions based on the detection result

1 version: 1.0.0
2 sections:
3   main:
4     - play:
5         url: "say: Welcome to the machine detection test."
6     - detect_machine:
7         status_url: "https://webhook.site/5c8abf82-b8c7-41c8-b5d6-b32a40068109"
8         detectors: "amd,fax"
9         wait: true
10     - cond:
11         - when: detect_result == 'machine'
12           then:
13             - play:
14                 url: "say: You are a machine, goodbye."
15             - hangup: {}
16         - when: detect_result == 'human'
17           then:
18             - play:
19                 url: "say: You are a human, hello."
20             - hangup: {}
21         - when: detect_result == 'fax'
22           then:
23             - play:
24                 url: "say: You are a fax, goodbye."
25             - hangup: {}
26         - else:
27             - play:
28                 url: "say: Unable to determine if you are a human, machine, or fax, goodbye. Result was ${detect_result}"
29             - hangup: {}