Operations
Operations

Update call handling

Configure call handling, the call-lifecycle detection + limit knobs, on agents.settings.callHandling. All fields optional; send only what changes (each is deep-merged over the stored block). Detection: voicemailDetectionEnabled + voicemailAction ('hang_up' | 'leave_message') + voicemailMessage (spoken on 'leave_message'); callScreenEnabled + callScreenMessage (iOS/Android call screening); ivrHangupEnabled (hang up on an IVR, parked for outbound). Keypad/DTMF: keypadInputEnabled + keypadTimeoutSecs (1-30) + keypadTerminationKey (0-9/#/*) + keypadDigitLimit (1-32). Limits: endOnSilenceEnabled + maxSilenceSecs (10-600, a HARD hangup, distinct from the 'are you still there?' check-in); maxCallDurationSecs (60-14400, null = the 15-minute fleet default; a real inbound call is never uncapped); maxDurationCloseLine (the line spoken when the call hits maxCallDurationSecs; null = the runtime default line); ringTimeoutSecs (5-120, null = default; the outbound/warm-transfer dial ring). Caller access: passphraseGateEnabled (answer in silence until the caller says the passphrase, then greet; the phrase lives in the SECRET variable `access_passphrase`, set it with set_secret_variable, and a caller who never says it is hung up on after 60 seconds; voice only; outbound calls skip it). passphraseGateRelaxed opts this agent into repeated-letter spelling variants, one letter of transcription error on phrases of at least six normalized characters, and joining up to three final transcripts within five seconds; off by default. Difficult callers: hangupOnAbuse (default on, hang up on a persistently abusive/hostile caller after a spoken warning; a frustrated caller is never cut off; turn off for sensitive lines like super, health, government, crisis). Use for 'hang up on voicemail', 'leave a voicemail message', 'answer call screening', 'listen for keypad input', 'end the call after N seconds of silence', 'cap calls at an hour', 'ring for 20 seconds', 'stay silent until I say the passphrase', or 'hang up on abusive callers' / 'stop hanging up on abusive callers'.

POST
/operations/set_call_handling

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Header Parameters

Idempotency-Key?string

A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/operations/set_call_handling" \  -H "Content-Type: application/json" \  -d '{    "agent": "string"  }'
{}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "errors": [
    {
      "path": "string",
      "message": "string"
    }
  ],
  "estimate": {},
  "retryAfterSeconds": 0
}

Set builtin config POST

Set the builtin_config (template-specific settings) on a BUILTIN tool, for example take_a_message's message routing (default_recipient + per-category/person routing rules) or transfer_to_human's destination, announced person and transfer style (`screening`: none, press1 or the consult call), or call_and_connect's `stay_on_the_line` (true: the agent stays on the call with the caller and the person it rang), or end_call's `speak_farewell` (true: the agent's closing line goes in end_call's `farewell` argument and is spoken before the hang-up). Identify the tool by toolName (its snake_case name) or toolId. `config` is the FULL builtin_config as a JSON object string and REPLACES the existing config, so read the current one from get_agent, edit it, and send the whole object back. To change ONE take_a_message setting on a live agent, prefer the ops that merge instead of replace, set_take_message_sms (the text copy) and set_take_message_details (what every message records), so a missed read can't delete the routing table. Only builtin tools have a builtin_config; for HTTP tools use set_tool_endpoint / set_tool_headers / set_tool_params instead. The change lands on the draft version.

Set caller blocking POST

Block or unblock one caller by phone number. A blocked number's inbound calls are refused at ingress: silently declined before the call is answered, or answered with a short spoken line then hung up, the agent's call-handling setting blockedCallerAction (set_call_handling) picks which, defaulting to the silent decline. Creates the caller's profile if none exists yet, and works with caller memory off. Pass scope 'workspace' to block the number for every agent in the workspace rather than just this one. Blocking wins over priority routing on the same profile. Inbound only, outbound campaigns keep their own do-not-call list. Use when the operator says things like 'block this number', 'stop +61400000000 calling us', or 'unblock Jordan'.