Machine Detection
Detect answering machines on outbound calls with synchronous or asynchronous detection modes.
Important: Not a Separate Endpoint
Machine detection is NOT a separate API endpoint. It is configured as parameters when making a call usingPOST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/. This page documents the machine detection parameters and callback format.
Machine detection allows you to identify when an answering machine picks up your outbound call instead of a human. You can configure Vobiz to either hang up automatically or continue the call when a machine is detected.
Note: Machine detection is only supported on outbound calls initiated via the Make Call API. Set the machine_detection parameter to enable this feature.
How It Works
Synchronous Machine Detection
When you set machine_detection=true ormachine_detection=hangup when making a call, Vobiz analyzes the audio after the call is answered to determine if a machine answered.
Machine Detection Parameters
| Parameter | Type | Description |
|---|---|---|
machine_detectionoptional | string | Set to "true" to continue the call or "hangup" to automatically hang up when a machine is detected. |
machine_detection_timeoptional | integer | Time in milliseconds to analyze audio. Default: 5000. Range: 2000–10000. |
machine_detection_maximum_speech_lengthoptional | integer | Maximum speech duration in milliseconds. Default: 5000. Range: 1000–6000. |
machine_detection_initial_silenceoptional | integer | Maximum silence after answer in milliseconds. Default: 4500. Range: 2000–10000. |
machine_detection_maximum_wordsoptional | integer | Maximum number of sentences. Default: 3. Range: 2–10. |
machine_detection_initial_greetingoptional | integer | Maximum greeting length in milliseconds. Default: 1500. Range: 1000–5000. |
Asynchronous Machine Detection
You can take action on detecting an answering machine during a call by setting themachine_detection_url parameter when firing an outbound call API. Vobiz will detect an answering machine in the background and invoke the machine_detection_url with detection results.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
machine_detection_urloptional | string | Callback URL invoked when machine detection completes. Vobiz sends detection results to this URL. |
machine_detection_methodoptional | string | HTTP method used to invoke machine_detection_url. Default: POST. |
Benefit: Asynchronous detection allows your application to handle the call immediately while detection happens in the background, providing better user experience.
Parameters Sent to machine_detection_url
When machine detection completes, Vobiz sends these parameters to your machine_detection_url:
| Parameter | Type | Description |
|---|---|---|
Fromoptional | string | The from number used to initiate the call. |
Machineoptional | boolean | Set to true if a machine is detected. |
Tooptional | string | The destination of the call. |
RequestUUIDoptional | string | An identifier that can uniquely identify a call. |
ALegRequestUUIDoptional | string | Identifies the first leg of the call in case there are multiple legs. |
CallUUIDoptional | string | The identifier used to identify the call. |
IfMachineoptional | string | This parameter can be either "continue" or "hangup" depending on the machine_detection parameter set while initiating the call. |
Directionoptional | string | The direction of the call. This will be "outbound" since we support machine detection only on outbound calls. |
ALegUUIDoptional | string | A unique identifier for the A leg of the call. |
Eventoptional | string | The event that triggered this notification. This will have the value "MachineDetection". |
CallStatusoptional | string | The status of the call. This will have the value "in-progress". |
Example Callback Response
{
"From": "+12025550000",
"Machine": true,
"To": "+12025551111",
"RequestUUID": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f",
"ALegRequestUUID": "9834029e-58b6-11e1-b8b7-a5bd0e4e126f",
"CallUUID": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"IfMachine": "continue",
"Direction": "outbound",
"ALegUUID": "97ceeb52-58b6-11e1-86da-77300b68f8bb",
"Event": "MachineDetection",
"CallStatus": "in-progress"
}