Overview

When using Twilio Programmable Voice for critical incident alerting, it is essential to ensure that only a real human answers the call and acknowledges the alert. Many organizations need to trigger escalation or retry logic if a call is answered by voicemail or goes unacknowledged. However, distinguishing between a human and voicemail using Twilio’s Answering Machine Detection (AMD) can present challenges due to ambiguous or misclassified results.

This article provides best practices and architectural recommendations for reliably handling voicemail detection and ensuring robust incident alerting workflows.

• Scenario: Automated system places a high-priority call to an on-call analyst when a major incident occurs.
• Requirement: If the call is answered by voicemail or not acknowledged, the system must retry or escalate.
• Challenge: Twilio’s AMD sometimes returns ambiguous answered_by values (e.g., unknown, machine_end_other), making it difficult to reliably distinguish between human and voicemail answers.

Key Concepts

• AMD (Answering Machine Detection): Twilio’s feature to classify call answers as “human” or “machine.”
• answered_by Parameter: Indicates who answered the call (human, machine, machine_end_beep, machine_end_other, unknown).

Product

Programmable Voice

 

Environment

Twilio Console

What You Need to Know

Best Practices & Recommendations

1. Treat Ambiguous Results as Failures

• Recommended Logic: Treat any call where answered_by is NOT explicitly human as a failure.
  • If answered_by is machine, machine_end_beep, machine_end_other, or unknown, trigger your retry or escalation logic.
• Rationale: This approach ensures that only clear human answers are considered successful, reducing the risk of missed escalations.

2. DTMF (Keypad) Acknowledgment

• Pattern: After AMD detects a human, prompt the callee to press a key (DTMF) to confirm receipt.
• Implementation: Use TwiML <Gather> to collect DTMF input. Only treat the alert as acknowledged if the correct input is received.
• Fallback: If no DTMF is received within a set time, treat the call as unacknowledged and trigger escalation.

3. Configuration Tuning

• AMD Parameters: Experiment with AMD settings such as DetectMachineEnd and timeout to optimize detection for your use case.
• Timeouts: Reducing the initial <Dial> or <Say> timeout may help avoid voicemail, but could increase the risk of missing a human answer.
• Carrier/Voicemail Variability: Be aware that AMD accuracy can vary by carrier and voicemail system.

4. Monitoring & Continuous Improvement

• Voice Insights: Use Twilio Voice Insights and the Annotation API to analyze AMD results and identify patterns (e.g., false positives linked to specific carriers).
• A/B Testing: Test different configurations and review sample call recordings to refine your approach.

Example Implementation

<!-- Example TwiML for DTMF acknowledgment -->
<Response>
  <Say>Please press 1 to acknowledge this alert.</Say>
  <Gather numDigits="1" timeout="5" action="/acknowledge">
    <Say>If you do not press 1, the alert will be escalated.</Say>
  </Gather>
  <Say>No input received. Escalating the alert.</Say>
  <!-- Add logic to trigger escalation here -->
</Response>

Conclusion 

For critical incident alerting, always treat ambiguous or non-human AMD results as failures and implement a DTMF acknowledgment step to guarantee human response. Continuously monitor and tune your configuration for optimal results. This approach ensures reliable escalation and minimizes the risk of missed alerts due to voicemail or misclassification.

If you have further questions or need implementation guidance, please reach out to Twilio Support.

Below you will find references to useful documents:

• Twilio Answering Machine Detection Best Practices
• TwiML Gather Documentation
• Voice Insights