# Answering Machine Detection - AMD v2

## How does it work

The Answering Machine Detection feature is used to detect if a call was answered by a machine/voicemail or by a human.

The AMD SETUP must happen before the call is answered by the CALLEE, allowing Sinch's AMD Algorithm to analyze the call initial interaction. This configuration is performed in the Initial Call Event - ICE, and in order to work, customer's must use Sinch [CustomCallout](/docs/voice/api-reference/voice/callouts) method.

We offer 2 different methods of interactions between customers and our AMD engine:

### Synchronous

This is the simplest method and it will only inform the user if the call was answered by a machine or a human, this information is relayed to customers as part of our standard Answered Call Event - ACE request. Customers can than decide how to react (hangup, connectConf... ) in a synchronous way.


```mermaid
sequenceDiagram
    participant dev as Developer Backend
    participant sinch as Sinch Platform
    participant b as Callee
    dev-->>sinch: CustomCallout Request (ICE Response ["amd": {"enabled": true, "async": false}] )
    sinch->>b: PSTN Call
    activate b
    b->>b: Voicemail
    b->>sinch: Call Answered
    sinch->>sinch: AMD Processing
    sinch->>dev: ACE Request (amd: { status: 'machine', reason: 'n/a', duration: 4 })
    dev->>sinch: SVAML response (hangup)
    sinch->>b: Hangup call
    deactivate b
    sinch->>dev: Disconnected Call Event (DICE)
```

### Asynchronous

This is a more complete method, and it can not only identify if the call was answered by a machine or a human, but it can also NOTIFY the customer when the beep is detected, so customers can know the right time to leave a message if the call was answered by a machine.

This method is considered asynchronous, due to the fact that an ACE request will be sent to Sinch customer's backend immediately after the call is answered, allowing the standard call flow to continue, while Sinch will send a different notification event if or when the machine beep signal is detected.


```mermaid
sequenceDiagram
    participant dev as Developer Backend
    participant sinch as Sinch Platform
    participant b as Callee
    dev--)sinch: CustomCallout Request (ICE Response ["amd": {"enabled": true, "async": true}] )
    activate sinch
    sinch-->>sinch: AMD Processing
    sinch->>b: PSTN Call
    activate b
    b->>b: Voicemail
    b->>sinch: Call Answered
    sinch->>dev: ACE Request
    dev->>sinch: SVAML response (ConnectConf) ... [wait for AMD response]
    sinch-)dev: Notification (type: 'amd', amd: { status: 'machine', reason: 'n/a', duration: 4 })
    sinch-)dev: Notification (type: 'amd_beep', amd: { status: 'machine', reason: 'beep', duration: 8 })
    deactivate sinch
    dev-->>sinch: SVAML Request PATCH(Instruction: say, Action: hangup)
    sinch->>b: Say [text] - Message to be recorded
    sinch->>b: Hangup call
    deactivate b
    sinch->>dev: Disconnected Call Event (DICE)
```

Note:
See Manage Call API [PATCH](/docs/voice/api-reference/voice/calls/calling_updatecall) - How to update a call in progress.

### Examples:

To enable the AMD feature, customers just need to setup their SVAML ICE Response with one of the following parameters:

**Synchronous - No beep detection:**


```json JSON
  "amd": {"enabled": true},
```

or


```json JSON
  "amd": {"enabled": true, "async": false},
```

**Asynchronous - With beep detection:**


```json JSON
  "amd": {"enabled": true, "async": true},
```

#### Synchronous:


```shell Synchronous cURL
curl --location --request POST 'https://calling.api.sinch.com/calling/v1/callouts' \

--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "method": "customCallout",
    "customCallout": {
      "ice": "{\\"action\\": {\\"name\\": \\"connectPstn\\",\\"number\\": \\"+XXXXXXXXXXX\\",\\"cli\\": \\"+YYYYYYYYYY\\",\\"maxDuration\\": 14400, \\"amd\\": {\\"enabled\\": true, \\"async\\": false},  \\"locale\\": \\"en-US\\" }}",
      "enableAce": true,
      "enableDice": true
    }
}
'
```

#### Asynchronous:


```shell Asynchronous cURL
curl --location --request POST 'https://calling.api.sinch.com/calling/v1/callouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXX' \
--data '{
    "method": "customCallout",
    "customCallout": {
      "ice": "{\\"action\\": {\\"name\\": \\"connectPstn\\",\\"number\\": \\"+XXXXXXXXXXX\\",\\"cli\\": \\"+YYYYYYYYYY\\",\\"maxDuration\\": 14400, \\"amd\\": {\\"enabled\\": true, \\"async\\": true},  \\"locale\\": \\"en-US\\" }}",
      "enableAce": true,
      "enableDice": true
    }
}
'
```

## Notification Events

**Machine/Human:**


```js Human/Machine notification event payload
Body:
 {
  event: 'notify',
  callid: 'edbc97b3-5aaf-4622-8291-b7f9c9792cc9',
  version: 1,
  type: 'amd',
  amd: { status: 'machine', reason: 'n/a', duration: 3 }
}
```

**Beep:**


```js Beep notification event payload
Body:
 {
  event: 'notify',
  callid: 'edbc97b3-5aaf-4622-8291-b7f9c9792cc9',
  version: 1,
  type: 'amd_beep',
  amd: { status: 'machine', reason: 'beep', duration: 8 }
}
```

Note:
The accuracy of the Answering Machine Detection feature may vary due to the variety of voicemail messages lengths, audio quality and beep types.