Answering Machine Detection

Answering Machine Detection (AMD) enables you to determine the receiving side of an outgoing call and tailor your call flow accordingly. With AMD you can determine if a human, answering machine or fax machine has picked up an outbound voice API call. Once AMD has executed and made its decision, the caller is connected to the callee.

AMD can also be executed asynchronously: the callee is connected immediately and AMD is executed in the background.

Twilio's AMD operates in two modes, depending on whether you need to leave a voicemail as part of your call flow. The default AMD mode tries to balance recognition speed and accuracy. You may also tune the performance of the engine based on your use case via optional API parameters.

Please see the following API parameters for configuring AMD on your outbound calls.

AMD can be enabled on calls generated via POST to the Calls API, POST to the Participants API, <Dial><Number>, or <Dial><Sip>.

The following AMD parameters as well as Optional tunning parameters can be specified on the requests.

Use Enable if you would like Twilio to return an AnsweredBy value as soon as it identifies the called party. This is useful if you would like to take a specific action — for example, connect to an agent, or leave a message in voicemail with <Say> and Text-To-Speech capabilities — for a human but hang up on a machine.

If you would like to leave a voicemail on an answering machine, specify DetectMessageEnd. In this case, Twilio will return an AnsweredBy immediately when a human is detected but for an answering machine, AnsweredBy is returned only once the end of the greeting is reached, usually indicated by a beep.

Select whether to perform AMD in the background. When this is true, the call is continued while AMD makes its decision in the background. When this is false, which is the default, Twilio blocks the execution of the call until AMD is completed.

The HTTP method that we should use to send the results of the AMD.

The absolute or relative URL that we should call using the AsyncAmdStatusCallbackMethod to notify whether the call was answered by a human, machine, or fax. When AMD makes a decision, Twilio will make a request to this URL with the following parameters:

AMD uses an algorithm that isolates human speech audio and measures periods between speech and silence in the greeting, and then uses this data to determine the answering party. Since not all humans and not all voicemail greetings follow similar patterns in answering calls, it's possible that 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.

There are four optional parameters that allow customers to tune the performance of the AMD engine, the diagram below illustrates how each property relates to media utterances:

Expand image

The number of seconds that Twilio should attempt to perform answering machine detection before timing out. If MachineDetectionTimeout is reached, AnsweredBy will return unknown.

Increasing this value will provide the engine more time to make a determination. For example, you may increase the default value when MachineDetection=DetectMessageEnd and there is an expectation of long answering machine greetings that can exceed 30 seconds.

Decreasing this value will reduce the amount of time the engine has to make a determination. For example, you may decrease the default value when MachineDetection=Enabled if you have time constraints for taking an action based on answering machine detection determination, hence you prioritize a (best effort) quick response of human/machine or Unknown result. However, not giving enough time will result in more unknown results.

Note that when MachineDetection=DetectMessageEnd, setting low values for MachineDetectionTimeout may return unknown result even if a machine answered the call and the engine would be able to determine so, because the timeout was triggered without waiting until the end of machine greeting, which instead would have returned machine_end_beep, machine_end_silence, or machine_end_other.

The number of milliseconds that is used as the measuring stick for the length of the speech activity. Durations lower than this value may be interpreted as a human, longer as a machine.

Increasing this value will reduce the chance of a False Machine (detected machine, actually human) for a long human greeting (e.g., a business greeting) but increase the time it takes to detect a machine.

Decreasing this value may reduce the chances of a False Human (detected human, actually machine) for short voicemail greetings. For example, the value of this parameter may need to be reduced by more than 1000 ms to detect very short voicemail greetings. However, a reduction of that significance can result in increased False Machine detections and adjusting the MachineDetectionSpeechEndThreshold is likely the better approach for short voicemails.

The number of milliseconds of silence after speech activity at which point the speech activity is considered complete.

Increasing this value is typically used to better address the short voicemail greeting scenarios. For short voicemails, there is typically 1000-2000 ms of audio followed by 1200-2400 ms of silence and then additional audio before the beep. Increasing the MachineDetectionSpeechEndThreshold to ~2500 ms will treat the 1200-2400 ms of silence as a gap in the greeting but not the end of the greeting and will result in a machine detection. The downsides of such a change include:

1. Increasing the delay for human detection by the amount you increase this parameter, e.g., a change of 1200 ms to 2500 ms increases human detection delay by 1300ms.
2. Cases where a human has two utterances separated by a period of silence (e.g. a "Hello", then 2000 ms of silence, and another "Hello") may be interpreted as a machine.

Decreasing this value will result in faster human detection. The consequence is that it can lead to increased False Human (detected human, actually machine) detections because a silence gap in a voicemail greeting (not necessarily just in short voicemail scenarios) can be incorrectly interpreted as the end of speech.

The number of milliseconds of initial silence after which an unknown AnsweredBy result will be returned.

Increasing this value will result in waiting for a longer period of initial silence before returning an unknown AMD result.

Decreasing this value will result in waiting for a shorter period of initial silence before returning an unknown AMD result.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createCall() {
11
  const call = await client.calls.create({
12
    from: "+18180000000",
13
    machineDetection: "Enable",
14
    to: "+1562300000",
15
    url: "https://handler.twilio.com/twiml/EH8ccdbd7f0b8fe34357da8ce87ebe5a16",
16
  });
17

18
  console.log(call.sid);
19
}
20

21
createCall();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "annotation": null,
4
  "answered_by": null,
5
  "api_version": "2010-04-01",
6
  "caller_name": null,
7
  "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
8
  "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
9
  "direction": "inbound",
10
  "duration": "15",
11
  "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
12
  "forwarded_from": "+141586753093",
13
  "from": "+18180000000",
14
  "from_formatted": "(415) 867-5308",
15
  "group_sid": null,
16
  "parent_call_sid": null,
17
  "phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "price": "-0.03000",
19
  "price_unit": "USD",
20
  "sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
21
  "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
22
  "status": "completed",
23
  "subresource_uris": {
24
    "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
25
    "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
26
    "payments": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments.json",
27
    "events": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Events.json",
28
    "siprec": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Siprec.json",
29
    "streams": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams.json",
30
    "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
31
    "user_defined_message_subscriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessageSubscriptions.json",
32
    "user_defined_messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/UserDefinedMessages.json"
33
  },
34
  "to": "+1562300000",
35
  "to_formatted": "(415) 867-5309",
36
  "trunk_sid": null,
37
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",
38
  "queue_time": "1000"
39
}

AMD results are returned in the AnsweredBy parameter of the webhook issued to the URL you provide in the outbound call request.

Answering Machine Detection will be charged at $.0075 per call where enabled and the called party picks up. Busy or Failed calls may engage our AMD system but will not be charged.

See also: Answering Machine Detection FAQ and best practices

The life cycle of a call using AMD is shown below. The user experience of a recipient of a call using AMD is impacted if there is a delay from the time they pick up the phone to the first packet of audio they hear. Twilio has optimized our AMD system to quickly classify calls, but it's also important that you optimize your application to respond quickly.

Expand image

To minimize delay, ensure that you benchmark your application to ensure that webhooks from Twilio are processed and responded to in a timely manner. In test applications running in EC2, we can get this time under 150 ms. TwiML served from TwiMLBins typically comes in under 100 ms.

If you are using <Play> verbs, we recommend hosting your media in AWS S3 in us-east-1, eu-west-1, or ap-southeast-2 depending on which Twilio Region you are using. No matter where you host your media files, always ensure that you're setting appropriate Cache Control headers. Twilio uses a caching proxy in its webhook pipeline and will cache media files that have cache headers. Serving media out of Twilio's cache can take 10ms or less. Keep in mind that we run a fleet of caching proxies so it may take multiple requests before all of the proxies have a copy of your file in cache.

Alternatively, you can use <Say> to leave a message with Text-To-Speech capabilities which provides more flexibility with low latency, without the overhead of recording, storing, and maintaining the media files.

To help you benchmark your server's response time to Twilio, we expose the request duration in milliseconds for every request in the Request Inspector. You can view these clicking into the Call Details page in the Console:

Expand image