Can Twilio tell whether a call was answered by a human or machine? – Twilio Support

Twilio has an Answering Machine Detection system which can detect if an outbound call made with Twilio's API was picked up by a human, an answering machine, or a fax machine.

How Answering Machine Detection works

Answering Machine Detection (or AMD for short) listens to the answered greeting of a call, and then analyzes the audio received. There is no consistent signaling difference between a call picked up by a human or a machine, so Twilio relies on analyzing the sound patterns of the greeting.

For example, a typical human greeting is much shorter than a voicemail recorded greeting, and so the length of the initial speech is a critical factor in the AMD decision.

How to use AMD

To use AMD, add the MachineDetection parameter to your HTTP POST request for making an outgoing call.

MachineDetection has two possible values:

Enable returns results as soon as the initial recognition of human, machine, or fax is complete.
DetectMessageEnd returns the initial recognition for human or fax. If an answering machine is detected, it will wait to return until the machine greeting is complete. This is useful for call flows where you want to leave a voicemail.

Here is an example of a cURL script for placing a call using the DetectMessageEnd mode for AMD:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls.json \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "MachineDetection=DetectMessageEnd" \
--data-urlencode "Url=https://www.mysite.com/twilio/callscript" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will place an outbound call from the sender (212) 555-1234 (+12125551234) to the phone number (310) 555-5555 (+13105555555), and then analyze the greeting when the call is answered. Once analyzed, Twilio will make an HTTP POST request to the TwiML script at https://www.mysite.com/twilio/callscript, and execute the TwiML response. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with your Account SID
Line 2 update with a valid destination phone number
Line 3 update with a valid caller ID phone number
Line 5 update with a valid TwiML URL or App SID url
Line 6 update with your Account SID and Auth Token

AMD's Response

When an outbound call is made with the MachineDetection parameter as part of the request, Twilio's request to your application to retrieve your TwiML will contain an additional parameter called AnsweredBy.

AnsweredBy has a number of possible values, based on the MachineDetection value used.

AnsweredBy value	MachineDetection value
human	Enable or DetectMessageEnd
fax	Enable or DetectMessageEnd
unknown	Enable or DetectMessageEnd
machine_start	Enable only
machine_end_beep	DetectMessageEnd only
machine_end_silence	DetectMessageEnd only
machine_end_other	DetectMessageEnd only

You can use these values to dictate the behavior of your app, like so:

<?php
header('Content-type: text/xml');
echo '<!--?xml version="1.0" encoding="UTF-8"?-->'; echo '';
switch($_POST['AnsweredBy']){
    case 'human':
        echo "Hello from Dr. Jones. Your appointment is tomorrow at noon.";
        break;
    case 'machine_end_beep':
        echo "This is a message from Dr Jones' office. Your appointment is tomorrow at noon.";
        break;
}
echo '';
?>

Performance of AMD

Since not all humans or voicemail greetings follow similar patterns when answering calls, AMD will not always return the right answer. The AMD engine may, for example, interpret a very short two second voicemail greeting as a human picking up. With this imperfection in mind, we have provided four optional API tuning parameters that allow customers to tune the performance of the AMD engine.

For more details about these API parameters and how to use them, please see AMD Tuning Parameters (Twilio Docs).

Alternatives to AMD

AMD is not suited to all use cases, but there are alternatives which may suit your application even if AMD doesn't.

Human Detection

One alternative to AMD is Call Screening, aka "Human Detection".

This approach works by asking a human to respond by pressing a key, and assumes that a voicemail has been reached if a key isn't pressed. In that case, you can have your app retry the call later to hopefully reach a human on the second try.

To make this work, you'll need to create a TwiML script for your outbound call API request that uses the <Gather> verb to collect keypresses:

<Response>
    <Gather action="message.xml" method="get">
        <Say>Press any key to hear an important message about your appointment.</Say>
    </Gather>
</Response>

The example script above reads the message asking the answering caller to press a key. When a keypress is registered, the <Gather> verb will request the file message.xml, which should respond with commands to read the message you want people to hear.

<Response>
    <Say>This is a message that you only want a person to hear.</Say>
</Response>

"Human Detection" is very reliable if you want to only deliver your message to humans. However, if you want to leave a voicemail, we do not recommend using "Human Detection". This is because voicemail greetings are not a consistent length, so you are more likely to have your call flow begin before the voicemail begins recording. AMD is the recommended solution if you want to leave a voicemail.

Looping the Message

If your message is short, for example "This is a message from Owl Elementary School. School is cancelled on account of snow.", you might just want to loop the message. This ensures that the message gets delivered, regardless of whether the message is answered by a human or a machine. You can do this by adding the "loop" attribute to the verb.