VocalDocscontracts 1.65.0

Label what answered an outbound Call

POST /v1/calls/{call_id}/answering-machine-label

PropertyValue
Operationlabel_answering_machine
GroupCalls
Scopecalls:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited call.answering_machine.label (mutation)
Released in1.50.0
Phase 0 hostServed (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" }'

Parameters

NameInTypeRequiredDescription
call_idpathCallIdyesThe id of a Call: call_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
idempotency-keyheaderstringnoA 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.

FieldTypeRequiredDescription
actualAnsweringMachineLabelValueyes

Responses

StatusContent typeShapeError codes
200application/jsonAnsweringMachineResult
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeanswering_machine_not_detected, idempotency_in_progress, idempotency_key_reused
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is AnsweringMachineResult.

FieldTypeRequiredDescription
actionAnsweringMachineActionyes
classificationAnsweringMachineClassificationyes
confidencenumber or nullyesThe classifier's confidence, 0 to 1; null for a timeout.
contradictedbooleanyesTrue when later evidence disagrees with the decision: a signal during the Call or a label.
contradiction_sourceContradictionSource or nullyesWhat contradicted it first; null when nothing did.
decided_atTimestampyes
decision_msintegeryesFrom the answer to the decision, a measurement; never on the voice path.
labelAnsweringMachineLabel or nullyesThe latest reviewer's label; null until one is given.
sensitivityAnsweringMachineSensitivityyesThe sensitivity in force.
stageAnsweringMachineStageyes