Label what answered an outbound Call
POST /v1/calls/{call_id}/answering-machine-label
| Property | Value |
|---|---|
| Operation | label_answering_machine |
| Group | Calls |
| Scope | calls:write |
| Route class | control |
| Idempotency | Idempotency-Key accepted: a retry with the same key replays the first answer |
| Audit | Audited call.answering_machine.label (mutation) |
| Released in | 1.50.0 |
| Phase 0 host | Served (the hosted api pins 1.65.0) |
Records a reviewer's label, human or machine, of what answered a finalized outbound phone Call whose answering-machine detection ran (1.50.0, FR-calls-12), and answers the Call's detection result with the label. A label that disagrees with the decision (machine against human or unknown, human against machine) marks the decision contradicted with the source review and records the Call event amd.contradicted the first time. A later label replaces an earlier one; each writes an Audit event. A Call with no detection result answers 409 answering_machine_not_detected.
Request
Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the calls:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.
curl -X POST "$VOCAL_API/v1/calls/call_.../answering-machine-label" \
-H "Authorization: Bearer $VOCAL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "actual": "human" }'const response = await fetch(`${process.env.VOCAL_API}/v1/calls/call_.../answering-machine-label`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
"actual": "human"
}),
});
console.log(response.status, await response.text());import os
import uuid
import requests
response = requests.post(
f"{os.environ['VOCAL_API']}/v1/calls/call_.../answering-machine-label",
headers={
"Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"actual": "human",
},
)
print(response.status_code, response.text)Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
call_id | path | CallId | yes | The id of a Call: call_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log. |
idempotency-key | header | string | no | A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response. |
Request body
Content type application/json, required: AnsweringMachineLabelInput.
| Field | Type | Required | Description |
|---|---|---|---|
actual | AnsweringMachineLabelValue | yes |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
200 | application/json | AnsweringMachineResult | |
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden, org_suspended |
404 | application/json | ErrorEnvelope | not_found |
409 | application/json | ErrorEnvelope | answering_machine_not_detected, idempotency_in_progress, idempotency_key_reused |
429 | application/json | ErrorEnvelope | rate_limited |
500 | application/json | ErrorEnvelope | internal_error |
Fields of the 200 answer
The shape is AnsweringMachineResult.
| Field | Type | Required | Description |
|---|---|---|---|
action | AnsweringMachineAction | yes | |
classification | AnsweringMachineClassification | yes | |
confidence | number or null | yes | The classifier's confidence, 0 to 1; null for a timeout. |
contradicted | boolean | yes | True when later evidence disagrees with the decision: a signal during the Call or a label. |
contradiction_source | ContradictionSource or null | yes | What contradicted it first; null when nothing did. |
decided_at | Timestamp | yes | |
decision_ms | integer | yes | From the answer to the decision, a measurement; never on the voice path. |
label | AnsweringMachineLabel or null | yes | The latest reviewer's label; null until one is given. |
sensitivity | AnsweringMachineSensitivity | yes | The sensitivity in force. |
stage | AnsweringMachineStage | yes |