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.

Name	Type	Default	Description
`detect_machine`Required	`object`	-	An object that accepts the `detect_machine parameters`.

detect_machine parameters

Name	Type	Default	Description
`detect_message_end`Optional	`boolean`	`false`	If `true`, stops detection on beep / end of voicemail greeting.
`detectors`Optional	`string`	`amd,fax`	Comma-separated string of detectors to enable. Valid Values: `amd`, `fax`
`end_silence_timeout`Optional	`number`	`1.0`	How long to wait for voice activity to finish (in seconds).
`initial_timeout`Optional	`number`	`4.5`	How long to wait for initial voice activity before giving up (in seconds).
`machine_ready_timeout`Optional	`number`	The value of `end_silence_timeout`	How long to wait for voice activity to finish before firing the READY event (in seconds).
`machine_voice_threshold`Optional	`number`	`1.25`	The number of seconds of ongoing voice activity required to classify as MACHINE.
`machine_words_threshold`Optional	`integer`	`6`	The minimum number of words that must be detected in a single utterance before classifying the call as MACHINE.
`status_url`Optional	`string`	-	The HTTP(S) URL to deliver detector events to. Learn more about status callbacks.
`timeout`Optional	`number`	`30.0`	The maximum time to run the detector (in seconds).
`tone`Optional	`string`	`CED`	The tone to detect. Only the remote side tone will be received. (`CED` or `CNG`) Used for fax detection.
`wait`Optional	`boolean`	`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.

Variable	Direction	Type	Description
`detect_result`	out	`human` \| `machine` \| `fax` \| `unknown`	The result of detection.
`detect_machine_beep`	out	`true` \| `false`	Whether a beep was detected. `true` if detected.
`detect_ms`	out	`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:

Field	Type	Description
`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.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

YAML
JSON

version: 1.0.0
sections:
  main:
    - detect_machine:
        status_url: 'https://example.com/detect-events'
        timeout: 20
    - play:
        url: 'say:Detection result: %{detect_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

YAML
JSON

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: {}

{
  "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": {}
              }
            ]
          }
        ]
      }
    ]
  }
}

detect_machine parameters​

Variables​

StatusCallbacks​

Raw JSON example​

Examples​

Play the detection result​

Conditional actions based on the detection result​