VocalDocscontracts 1.65.0

Create a pre-call hook

POST /v1/pre-call-hooks

PropertyValue
Operationcreate_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.create (mutation)
Released in1.52.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Creates a hook on a Phone number, an Agent or the Organization at revision 1 and answers its secret once (1.52.0). A scope that has a hook is pre_call_hook_scope_taken. In a PHI-mode Organization a hook is created paused unless attested, and status: active is phi_attestation_required. The URL passes the egress guard (egress_denied with its reason), and every issue is a detail of 422 validation_failed (PreCallHookIssueCode). A replay under the same Idempotency-Key creates nothing and answers secret null.

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" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": {
      "type": "phone_number",
      "id": "pn_..."
    },
    "url": "<url>",
    "directions": [
      "inbound"
    ]
  }'

Parameters

NameInTypeRequiredDescription
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: PreCallHookCreateRequest.

FieldTypeRequiredDescription
allowed_agent_idsarray of AgentIdno
defaultPreCallHookAcceptInput or nullno
directionsarray of PreCallHookDirectionyes
on_failurePreCallHookOnFailureno
scopePreCallHookScopeyes
statusone of "active", "paused"nodegraded is set by the platform.
timeout_msinteger or nullno
urlstring (uri)yesThe endpoint: https, a public name, no IP literal and no embedded credentials, checked by the egress guard at save and at every request.

Responses

StatusContent typeShapeError codes
201application/jsonPreCallHookCreated
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
404application/jsonErrorEnvelopenot_found
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is PreCallHookCreated.

FieldTypeRequiredDescription
allowed_agent_idsarray of AgentIdyesAgents besides the routed one whose published versions a response may select; empty allows only versions of the routed Agent.
consecutive_failuresintegeryes
created_atTimestampyes
defaultPreCallHookDefault or nullyes
directionsarray of PreCallHookDirectionyes
idPreCallHookIdyes
object"pre_call_hook"yes
on_failurePreCallHookOnFailureyes
phi_attested_atTimestamp or nullyesWhen an owner attested the endpoint for PHI; null before.
phi_attested_byMemberId or nullyes
previous_secret_expires_atTimestamp or nullyes
previous_secret_hintstring or nullyes
revisionintegeryes
scopePreCallHookScopeyes
secretPreCallHookSecret or nullyesThe secret, shown in this answer only; null on a replay under the same Idempotency-Key, which creates nothing.
secret_hintstringyesThe last four characters of the current secret.
statusPreCallHookStatusyes
timeout_msinteger or nullyesThe deadline of a request; null for the default of each direction.
updated_atTimestampyes
urlstringyesThe endpoint.