Detect a machine, fax tone or digits on a call in progress

Voiceanswering machine detection (AMD) over REST

Start answering machine, fax tone or keypad detection on a call that is already up, and read the result at your webhook.

restamd

The claim

Answering machine detection usually runs inside the document, before the call says anything. This is the other case: the call is already up, and something outside it wants to know who is there. Any process holding the call id can ask.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority for the shape.

calling.detect requires control_id and detect. The detect object is one of three configs, each requiring a type from the enum machine, fax or digit, and each with its own params.
The spec’s description says detection “runs asynchronously up to timeout seconds” and that results are “delivered via the status_url webhook”, so the recipe refuses a detect with no status URL before it is sent.
calling.detect.stop requires control_id and gives up early.

The machine params are where the classification lives: machine_voice_threshold (1.25 seconds by default) and machine_words_threshold (6 words) are what separate a greeting from a hello. Fax detection takes a tone of CED or CNG, and digit detection takes the digits you care about.

How it works

def machine(call_id, status_url, timeout=30, control_id=CONTROL_ID):
    _needs_status_url(status_url)
    params = {"machine_voice_threshold": 1.25, "machine_words_threshold": 6,
              "detect_message_end": True}
    detect = {"type": "machine", "params": params}
    return client.calling.detect(call_id, control_id=control_id, detect=detect,
                                 timeout=timeout, status_url=status_url)

What the platform receives:

{"command": "calling.detect",
 "id": "6d3f4a0e-2b1c-4e7a-9f0d-1c2b3a4d5e6f",
 "params": {"control_id": "screening",
            "timeout": 30,
            "status_url": "https://your-host/detect-events",
            "detect": {"type": "machine",
                       "params": {"machine_voice_threshold": 1.25,
                                  "machine_words_threshold": 6,
                                  "detect_message_end": true}}}}

The SDK’s calling namespace sends every call command to that one path and puts the call id in id. The TypeScript SDK, @signalwire/sdk, does the same: client.calling.detect(callId, {...}) produces the body above.

The document-side version of this is [Detect an answering machine](../detect-an-answering-machine/), which blocks the call flow until it has an answer. The REST command does not block anything: it listens while your code gets on with something else.

Limitations

The verifier proves the requests, not the classification. Whether a given voicemail greeting reads as a machine is the platform’s judgement, tuned by those thresholds.

One control id runs one detection. The spec says it must be unique per active detect on the call, so two detections at once need two ids.

What to change first

Change "machine" to "voicemail" in the machine helper and run the verifier. The type is outside the enum every config shares, and the exact body comparison fails, which is the point: three types are the whole vocabulary.

Where this sits

Before this

Place an outbound call

Detect an answering machine End or transfer a live call over REST Handle call status callbacks

python/app.py

"""Detect a machine, fax tone or digits on a call in progress.

`calling.detect` starts detection on a call that is already up, from outside
the call's document. The `detect` object picks what to listen for: `machine`,
`fax` or `digit`. The result arrives at your `status_url`, so a detect without
one is refused here before it is sent. `calling.detect.stop` gives up early.

Written against signalwire-sdk 3.0.1 (RestClient.calling).

    python app.py machine <call_id> <status_url>
    python app.py fax <call_id> <status_url>
    python app.py digits <call_id> <status_url>
    python app.py stop <call_id>
"""
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

# one id names this detection, and stop names it again
CONTROL_ID = "screening"

# the spec's three detection types
TYPES = ("machine", "fax", "digit")


def _needs_status_url(status_url):
    # the result arrives only by webhook; without one the detect is unobservable
    if not status_url:
        raise ValueError("a detect needs a status_url to deliver its result")


def machine(call_id, status_url, timeout=30, control_id=CONTROL_ID):
    """Answering machine detection, with the thresholds spelled out."""
    _needs_status_url(status_url)
    params = {"machine_voice_threshold": 1.25, "machine_words_threshold": 6,
              "detect_message_end": True}
    detect = {"type": "machine", "params": params}
    return client.calling.detect(call_id, control_id=control_id, detect=detect,
                                 timeout=timeout, status_url=status_url)


def fax(call_id, status_url, tone="CED", timeout=30, control_id=CONTROL_ID):
    """Fax tone detection. CED is the answering tone, CNG the calling tone."""
    _needs_status_url(status_url)
    detect = {"type": "fax", "params": {"tone": tone}}
    return client.calling.detect(call_id, control_id=control_id, detect=detect,
                                 timeout=timeout, status_url=status_url)


def digits(call_id, status_url, wanted="0123456789", timeout=30, control_id=CONTROL_ID):
    """DTMF detection: report when any of these digits is pressed."""
    _needs_status_url(status_url)
    detect = {"type": "digit", "params": {"digits": wanted}}
    return client.calling.detect(call_id, control_id=control_id, detect=detect,
                                 timeout=timeout, status_url=status_url)


def stop(call_id, control_id=CONTROL_ID):
    """Give up on the detection before its timeout."""
    return client.calling.detect_stop(call_id, control_id=control_id)


if __name__ == "__main__":
    args = sys.argv[1:]
    cmd = args[0] if args else "help"
    call_id = args[1] if len(args) > 1 else ""
    rest = args[2:]
    actions = {"machine": machine, "fax": fax, "digits": digits, "stop": stop}
    if not call_id or cmd not in actions:
        print(__doc__)
    else:
        print(actions[cmd](call_id, *rest))

/**
 * Detect a machine, fax tone or digits on a call in progress.
 *
 * `calling.detect` starts detection on a call that is already up, from outside
 * the call's document. The `detect` object picks what to listen for: `machine`,
 * `fax` or `digit`. The result arrives at your `status_url`, so a detect
 * without one is refused here before it is sent. `calling.detect.stop` gives up
 * early.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient.calling).
 *
 *     npm start machine <call_id> <status_url>
 *     npm start stop <call_id>
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

// one id names this detection, and stop names it again
export const CONTROL_ID = "screening";

// the spec's three detection types
export const TYPES = ["machine", "fax", "digit"] as const;

function needsStatusUrl(statusUrl: string | undefined): asserts statusUrl is string {
  // the result arrives only by webhook; without one the detect is unobservable
  if (!statusUrl) {
    throw new Error("a detect needs a status_url to deliver its result");
  }
}

/** Answering machine detection, with the thresholds spelled out. */
export function machine(callId: string, statusUrl?: string, timeout = 30,
                        controlId = CONTROL_ID) {
  needsStatusUrl(statusUrl);
  const params = {
    machine_voice_threshold: 1.25, machine_words_threshold: 6,
    detect_message_end: true,
  };
  return client.calling.detect(callId, {
    control_id: controlId, detect: { type: "machine", params },
    timeout, status_url: statusUrl,
  });
}

/** Fax tone detection. CED is the answering tone, CNG the calling tone. */
export function fax(callId: string, statusUrl?: string, tone = "CED", timeout = 30,
                    controlId = CONTROL_ID) {
  needsStatusUrl(statusUrl);
  return client.calling.detect(callId, {
    control_id: controlId, detect: { type: "fax", params: { tone } },
    timeout, status_url: statusUrl,
  });
}

/** DTMF detection: report when any of these digits is pressed. */
export function digits(callId: string, statusUrl?: string, wanted = "0123456789",
                       timeout = 30, controlId = CONTROL_ID) {
  needsStatusUrl(statusUrl);
  return client.calling.detect(callId, {
    control_id: controlId, detect: { type: "digit", params: { digits: wanted } },
    timeout, status_url: statusUrl,
  });
}

/** Give up on the detection before its timeout. */
export function stop(callId: string, controlId = CONTROL_ID) {
  return client.calling.detectStop(callId, { control_id: controlId });
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, callId, statusUrl] = process.argv.slice(2);
  if (!callId) {
    console.log("usage: npm start <machine|fax|digits|stop> <call_id> [status_url]");
  } else if (cmd === "machine") {
    console.log(await machine(callId, statusUrl));
  } else if (cmd === "fax") {
    console.log(await fax(callId, statusUrl));
  } else if (cmd === "digits") {
    console.log(await digits(callId, statusUrl));
  } else if (cmd === "stop") {
    console.log(await stop(callId));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py machine <call_id> https://your-host/detect-events
python app.py fax <call_id> https://your-host/detect-events
python app.py stop <call_id>

The TypeScript surface is the same commands on @signalwire/sdk, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start machine <call_id> https://your-host/detect-events

Take the call id from a tool webhook, a status callback, or the dial response. The status_url needs a public route of yours, because that is where the result lands.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier swaps the SDK’s HTTP layer for a recorder, calls the four helpers, and asserts the following.

a detect with a missing or empty status URL raises before any request is made
calling.detect requires control_id and detect, and its description names both the timeout behaviour and the status_url delivery
the detect object is a oneOf of exactly the three documented configs, each requiring type, each carrying the same three-value enum
the machine defaults in the spec are 4.5, 1, 1.25, 6, false and true, and the params this recipe sends are documented properties
the fax tone enum is exactly CNG, CED and their lower-case forms
calling.detect.stop requires only control_id
each body equals the expected {"command", "id", "params"} shape
the TypeScript surface sends those same four bodies and refuses the same detect

Report an issue