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

Twilio has an experimental feature called Answering Machine Detection which can roughly determine if an outbound call made with Twilio’s API has reached a human or if it has reached an answering machine.

How AMD works

Answering Machine Detection (called AMD for short) listens to the first few seconds of a call and analyzes the audio. There is no consistant signalling difference between a call picked up by a human or a machine, so Twilio relies on analyzing the sound patterns of the first few seconds of a call.

When a human answers a call, the typical pattern is to say “Hello” and then wait for the other party to respond “Hello”. Basically, you can think of it as sound, followed by silence.

However, the typical pattern for voicemail is to continue speaking and say something like “Hi, you’ve reached so-and-so…”. This is constant sound with no silences. It is this pattern that AMD is listening for. Sound followed by silence means human, constant sound means voicemail.

AMD relies on measuring a greeting against typical speech patterns. Because of this, it will not work 100% of the time.

How to use AMD

To use AMD, add the IfMachine parameter to the POST request when you make an outgoing call.

IfMachine has two possible values:

  • “Continue”. If Twilio detects an answering machine, it will wait until it hears a beep before continuing with the call flow.
  • “Hangup”. If Twilio detects an answering machine, it will hangup immediately. You won’t be charged for calls terminated in this manner.

Here is a sample POST request that places a call, and will wait until it hears a “beep” before continuing with it’s call flow.

POST /2010-04-01/Accounts/AC30947.../Calls
From=+14158675309&To=+14155551212&Url=http://example.com/twiml.php&IfMachine=Continue

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

AnsweredBy can have two values:

  • “machine”. This means Twilio thinks a machine answered.
  • “human”. This means that Twilio thinks a human answered the call.

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 'machine':
        echo "We're sorry you're not there. We will leave a message.";
    break;
    case 'human':
        echo "So nice to talk to a real human!";
    break;
}
echo '';
?>

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 an 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.

“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 consistant length, so you are more likely to have your call flow begin before the voicemail begins recording than you are with AMD.

Here is a quick example of call screening:

index.xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Gather action="message.xml" method="get">
    <Say>Press any key to hear an important message about your appointment.</Say>
  </Gather>
</Response>

message.xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>This is a message that you only want a person to hear.</Say>
</Response>

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.