Answering Machine Detection

Outbound calls placed with the Telnyx Voice API can be enabled with Answering Machine Detection (AMD, Voicemail Detection).

When a call is answered, Telnyx runs real-time detection to determine if it was picked up by a human or a machine and sends webhooks with the analysis result.

AMD settings

The answering_machine_detection value when creating an outbound call or transferring an inbound call can be set to one of the following:

Setting	Description	Webhooks Sent
`detect`	Only detect if answering machine or human.	`call.machine.detection.ended`
`detect_beep`	Listens for a final "beep" sound after detecting a `machine`	`call.machine.detection.ended` and `call.machine.greeting.ended` only if a beep is detected
`detect_words`	After a `machine` is detected, a 30 second long beep detection will begin. Note the answering machine may still be playing it's greeting while the 30 seconds is counting down.	`call.machine.detection.ended` and `call.machine.greeting.ended` when the beep is detected or at the end of 30 seconds.
`greeting_end`	Listens for extended periods of silence or a beep in the greeting to determine if a greeting has ended.	`call.machine.detection.ended` and `call.machine.greeting.ended`
`premium`	RECOMMENDED Premium AMD uses advanced speech recognition technology and machine learning to achieve exceptional accuracy in determining whether a call has been connected to a live person or a machine.	`call.machine.premium.detection.ended` with one of `human_residence` or `human_business` or `machine` or `silence` or `fax_detected` or `not_sure`. If a beep is detected a `call.machine.premium.greeting.ended` webhook with `beep_detected` is also sent. If a beep is detected before `call.machine.premium.detection.ended`, `call.machine.premium.greeting.ended` is sent. If a beep is detected after `call.machine.premium.detection.ended`, both webhooks will be sent.

Sample dial request

POST https://api.telnyx.com/v2/calls HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Bearer YOUR_API_KEY

{
  "connection_id" : "1494404757140276705",
  "to"            : "+19198675309",
  "from"          : "+19842550944",
  "webhook_url"   : "https://webhook_url.com/outbound_call_events",
  "answering_machine_detection" : "detect_words"
}

Note
After pasting the above content, Kindly check and remove any new line added

General order of operations

Create outbound call.
Receive call.initiated webhook.
Receive call.answered webhook when the call is answered either by human or machine.
Receive call.machine.detection.ended webhook with human/machine status.
Receive call.machine.greeting.ended webhook when beep detected or 30 second timeout.

x. Important at any point, the callee could hangup generating a call.hangup webhook.

Webhooks

call.machine.detection.ended

The call.machine.detection.ended is sent when Telnyx can make a determination on human or machine.

The data.payload.result will contain the information about the answering machine:

Result	Description
`human`	Human answered call
`machine`	Machine answered call
`not_sure`	Recommended to treat as if human answered.

Sample Webhook

{
  "data": {
    "event_type": "call.machine.detection.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "result": "machine",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Note
After pasting the above content, Kindly check and remove any new line added

call.machine.greeting.ended

If the answering_machine_detection was set to detect_beep, detect_words, greeting_end you could receive a final webhook when the prompt (or beep detection) has finished.

The data.payload.result will contain the information about the answering machine:

Result	Description	AMD Setting
`ended`	Greeting is over.	ONLY sent when setting is `greeting_end`
`beep_detected`	Beep has been detected	`detect_beep` and `detect_words`
`not_sure`	30 second beep detection timeout fired after detecting a `machine`	`detect_beep` and `detect_words`

Sample Webhook

{
  "data": {
    "event_type": "call.machine.greeting.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "result": "ended",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Note
After pasting the above content, Kindly check and remove any new line added

The call.machine.premium.detection.ended webhook is sent when the AMD process can determine whether the call was answered by a human or a machine. It is possible to specify the number of milliseconds that Telnyx should attempt to perform the detection via the total_analysis_time_millis setting. By default, the timeout is set to 30 seconds. If the timeout is reached before the detection is finished, the result in the webhook will be not_sure.

The data.payload.result will contain the information about the answering machine:

Result	Description
`human_residence`	A human answered the call
`human_business`	A human answered call
`machine`	A machine answered the call
`silence`	No sound was detected
`fax_detected`	A Fax machine answered the call
`not_sure`	Not identifiable, or the configured AMD timeout was reached before the result was available.

Sample Webhook

{
  "data": {
    "event_type": "call.machine.premium.detection.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "result": "machine",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Note
After pasting the above content, Kindly check and remove any new line added

call.machine.premium.greeting.ended

If a machine answered the call, you may receive a final webhook when the beep detection has finished. This webhook is optional and will only be sent if one of two happens:

a beep is detected. In this case, the result is beep_detected.
the optional AMD timeout is reached after the call was answered by a machine, but no beep was heard. For this case, the result is no_beep_detected.

The data.payload.result will contain the information about the answering machine:

Result	Description	AMD Setting
`beep_detected`	Greeting is over.	ONLY sent when a `machine` answered the call, and a beep was heard.
`no_beep_detected`	ONLY sent when a `machine` answered the call, and the AMD timeout was reached before a beep was heard.

Sample Webhook

{
  "data": {
    "event_type": "call.machine.premium.greeting.ended",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "occurred_at": "2018-02-02T22:25:27.521992Z",
    "payload": {
      "call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
      "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "from": "+35319605860",
      "result": "beep_detected",
      "to": "+13129457420"
    },
    "record_type": "event"
  }
}

Note
After pasting the above content, Kindly check and remove any new line added