VocalDocscontracts 1.65.0

Send a synthetic request to a pre-call hook

POST /v1/pre-call-hooks/{hook_id}/test

PropertyValue
Operationtest_pre_call_hook
GroupPre-call hooks
Scopehooks:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited dispatch.pre_call_hook.test (mutation)
Released in1.52.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Sends one synthetic request through the production path (1.52.0): signed, through the egress guard, with livemode false and a synthetic Call, caller and number, whatever the status of the hook. Answers what it came to, names and codes only; a failure is an outcome, not an error. It writes an Audit event, never the response.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the hooks:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/pre-call-hooks/pch_.../test" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Parameters

NameInTypeRequiredDescription
hook_idpathPreCallHookIdyesThe id of a pre-call hook: pch_ 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: PreCallHookTestRequest.

FieldTypeRequiredDescription
directionone of "inbound", "outbound", "web", "app"noThe kind of Call the synthetic request describes; inbound when omitted.

Responses

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

Fields of the 200 answer

The shape is PreCallHookTestResult.

FieldTypeRequiredDescription
compliance_changesarray of PreCallComplianceFieldnoThe fields of compliance the answer applied (1.54.0), each under /compliance; empty when it tightened nothing. Absent from an api before 1.54.0.
decline_reasonstring or nullyes
failure_codePreCallFailureCode or nullyes
http_statusinteger or nullyes
latency_msintegeryes
object"pre_call_hook_test"yes
outcomePreCallOutcomeyes
overridden_settingsarray of stringyesThe paths of the settings it overrode.
request_idPreCallRequestIdyes
selected_agentPreCallAgentVersion or nullyes
tagsarray of CallTagyes
variables_setarray of stringyesThe names of the variables it supplied.
violationsarray of PreCallViolationyesThe JSON path and code of each value outside the bounds, never the value.