***

id: c6cc83d7-f766-41bc-8ab2-75aed8c59197
title: detect\_machine
slug: /reference/detect-machine
description: >-
Detect whether the other end of the call is a machine (fax, voicemail, etc.)
or a human, using AMD and fax detection.
max-toc-depth: 3
----------------

[variables]: #variables

[statuscallbacks]: #statuscallbacks

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][variables].

## **Properties**

<ParamField path="detect_machine" type="object" required={true} toc={true}>
  An object that accepts the following properties.
</ParamField>

<Indent>
  <ParamField path="detect_machine.detect_message_end" type="boolean" default="false" toc={true}>
    If `true`, stops detection on beep / end of voicemail greeting.
  </ParamField>

  <ParamField path="detect_machine.detectors" type="string" default="amd,fax" toc={true}>
    Comma-separated string of detectors to enable. **Valid Values:** `amd`, `fax`
  </ParamField>

  <ParamField path="detect_machine.end_silence_timeout" type="number" default="1.0" toc={true}>
    How long to wait for voice activity to finish (in seconds).
  </ParamField>

  <ParamField path="detect_machine.initial_timeout" type="number" default="4.5" toc={true}>
    How long to wait for initial voice activity before giving up (in seconds).
  </ParamField>

  <ParamField path="detect_machine.machine_ready_timeout" type="number" default="value of the end_silence_timeout parameter" toc={true}>
    How long to wait for voice activity to finish before firing the READY event (in seconds).
  </ParamField>

  <ParamField path="detect_machine.machine_voice_threshold" type="number" default="1.25" toc={true}>
    The number of seconds of ongoing voice activity required to classify as MACHINE.
  </ParamField>

  <ParamField path="detect_machine.machine_words_threshold" type="integer" default="6" toc={true}>
    The minimum number of words that must be detected in a single utterance before classifying the call as MACHINE.
  </ParamField>

  <ParamField path="detect_machine.status_url" type="string" toc={true}>
    The HTTP(S) URL to deliver detector events to. Learn more about [status callbacks][statuscallbacks].
  </ParamField>

  <ParamField path="detect_machine.timeout" type="number" default="30.0" toc={true}>
    The maximum time to run the detector (in seconds).
  </ParamField>

  <ParamField path="detect_machine.tone" type="string" default="CED" toc={true}>
    The tone to detect. Only the remote side tone will be received. (`CED` or `CNG`) Used for fax detection.
  </ParamField>

  <ParamField path="detect_machine.wait" type="boolean" default="true" toc={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.
  </ParamField>
</Indent>

## **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.

<ParamField path="detect_result" type="human | machine | fax | unknown" toc={true}>
  The result of detection.
</ParamField>

<ParamField path="detect_machine_beep" type="true | false" toc={true}>
  Whether a beep was detected. `true` if detected.
</ParamField>

<ParamField path="detect_ms" type="integer" toc={true}>
  The number of milliseconds the detection took.
</ParamField>

## **StatusCallbacks**

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

<ParamField path="event_type" type="string" toc={true}>
  The type of event, always `calling.call.detect` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing detection-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.control_id" type="string" toc={true}>
    The control ID for this detect operation.
  </ParamField>

  <ParamField path="params.detect" type="object" toc={true}>
    Detection result details (see subfields below).
  </ParamField>

  <Indent>
    <ParamField path="detect.type" type="string" toc={true}>
      The type of detection. **Valid values:** `machine` or `fax`.
    </ParamField>

    <ParamField path="detect.params.event" type="string" toc={true}>
      The detection result. **Valid values:** `HUMAN`, `MACHINE`, `READY`, `NOT_READY`, `UNKNOWN`, `finished`.
    </ParamField>

    <ParamField path="detect.params.beep" type="boolean" toc={true}>
      Present and set to `true` when a beep was detected. Absent when no beep has been detected.
    </ParamField>
  </Indent>

  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.segment_id" type="string" toc={true}>
    The segment ID for this part of the call.
  </ParamField>
</Indent>

### Raw JSON example

```json
{
  "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": "MACHINE",
        "beep": true
      }
    },
    "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

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - detect_machine:
            status_url: 'https://example.com/detect-events'
            timeout: 20
        - play:
            url: 'say:Detection result: ${detect_result}'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```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}"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Conditional actions based on the detection result

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    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: {}
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```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": {}}
                ]
              }
            ]
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>