Detect an answering machine

Voiceanswering machine detection (AMD)

Use answering machine detection to classify a pickup as human or voicemail before playing the main message.

Also called voicemail detection, human or machine detection, voice broadcast detection step

amd

The claim

An outbound call that classifies whoever answered before it speaks. A person and a voicemail both hear the repair message, voicemail playback waits until after the beep, and a fax tone gets hung up on.

Why it holds

The classification happens in the document, so no code of yours is in the loop while the call is deciding.

How it works

detect_machine runs first and blocks until it has an answer. The outcome lands in the detect_result variable, and is also POSTed to status_url if you want it for reporting.

- detect_machine:
    detectors: "amd,fax"
    detect_message_end: true
    initial_timeout: 4.5
    end_silence_timeout: 1.0
- switch:
    variable: detect_result
    case:
      human:   [...]
      machine: [...]
      fax:     [{ hangup: {} }]

detect_message_end is the field that makes voicemail work. With it on, detection holds until the greeting finishes, so the message is played after the beep. With it off, the call talks over the outgoing greeting and the recording catches half a sentence.

The documented values are lowercase: machine, human, fax, unknown, detecting and error. The last three go to default, which plays the message and nothing else. That is the safe thing to say when the classifier could not decide, because it works read to a person or recorded by a machine.

The document travels with the origination on dial, so the classification runs on the leg being answered. There is no separate call to bridge first.

Limitations

Detection costs time. initial_timeout is how long the call waits for a voice before giving up, so a human hears a pause before you speak. Shortening it trades accuracy for that pause.

AMD is a guess. A slow talker is classified as a machine, and a short voicemail greeting as a human. That happens often enough that the message has to make sense either way.

What to change first

Set detect_message_end to false and call your own voicemail. The message starts during the greeting, and the recording gets the tail of it.

Swap the play in the machine branch for a send_sms verb carrying a link, and the same document is missed call text-back. On this outbound call the customer is the to of the dial, so to_number is that number, not call.from, which is your own line here. from_number is a messaging-enabled number you own. text-the-caller-during-the-call shows the verb on an inbound call.

python/app.py

"""Detect an answering machine before your logic runs.

`detect_machine` classifies who picked up. The outcome lands in the
`detect_result` variable and is also POSTed to `status_url`, so the document
can branch on it without your code being involved.

`detect_message_end: true` is what makes a voicemail usable: detection holds
until the greeting finishes, so the message is left after the beep rather than
over the top of "please leave a message".

The document is placed with the call, so classification happens on the leg
being answered rather than on a call you have to bridge first.

Written against signalwire-sdk 3.0.1 (RestClient.calling).
"""
import os

from dotenv import load_dotenv
from signalwire.rest import RestClient

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

client = RestClient()

FROM = os.getenv("SIGNALWIRE_PHONE_NUMBER", "+15550001111")
PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")

# Documented detect_result values, lowercase.
HUMAN, MACHINE, FAX = "human", "machine", "fax"
UNKNOWN = ("unknown", "detecting", "error")

MESSAGE = "This is Ridgeline Cycles. Your repair is ready for collection."


def reminder_document():
    """Classify first, then say the right thing to whoever answered."""
    return {
        "version": "1.0.0",
        "sections": {
            "main": [
                {"answer": {}},
                {"detect_machine": {
                    "detectors": "amd,fax",
                    # hold until the greeting ends, so the message lands
                    # after the beep instead of over it
                    "detect_message_end": True,
                    "initial_timeout": 4.5,
                    "end_silence_timeout": 1.0,
                    "status_url": f"{PUBLIC_URL}/amd-status",
                }},
                {"switch": {
                    "variable": "detect_result",
                    "case": {
                        HUMAN: [
                            # A person can be told something a machine
                            # cannot act on. Nothing here collects a digit,
                            # so nothing here offers one.
                            {"play": {"url": f"say:{MESSAGE} The workshop is "
                                             "open until six today."}},
                        ],
                        MACHINE: [
                            # detect_message_end held us until the beep
                            {"play": {"url": f"say:{MESSAGE}"}},
                        ],
                        FAX: [
                            # nothing to say to a fax tone
                            {"hangup": {}},
                        ],
                    },
                    # unknown, detecting and error land here. The message
                    # alone is the safe thing to play when the classifier
                    # could not decide: it works read to either.
                    "default": [
                        {"play": {"url": f"say:{MESSAGE}"}},
                    ],
                }},
                {"hangup": {}},
            ]
        },
    }


def call(to):
    return client.calling.dial(**{
        "from": FROM,
        "to": to,
        "swml": reminder_document(),
        "status_url": f"{PUBLIC_URL}/call-status",
        "status_events": ["answered", "ended"],
    })


if __name__ == "__main__":
    import sys

    print(call(sys.argv[1] if len(sys.argv) > 1 else "+15552223333"))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # add your credentials and From number
python app.py +15552223333

Verify it

No network, no account:

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

With the HTTP layer replaced by a recorder, the verifier asserts:

one documented dial, carrying the document inline
detect_machine precedes the switch, and nothing plays before it
detect_message_end is on, with both timeouts set
the switch reads detect_result
every case is one of the six documented values, and human, machine and fax are all handled
a fax hangs up, a human and a machine both hear the message
no branch offers a keypress, because the document collects no digits
the three unclassified outcomes fall to the default rather than being cased

Report an issue