Operations
Operations

Set builtin config

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.

POST
/operations/set_builtin_config

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_builtin_config" \  -H "Content-Type: application/json" \  -d '{    "config": "string",    "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
}

Save brief POST

Store the agent's brief, the two interview answers that can be checked rather than just written down. `callReasons` is what people ring about. `nevers` is what the agent must never do, and each never must name the tool it forbids, because storing it also COMPILES it: the platform creates a scenario where a caller pushes three times for the forbidden thing, asserts `tool_not_called` against that tool, and links the scenario to the rule. A never that names no tool, or names a tool this version does not have, is REFUSED and nothing is stored, so ask the operator which action they mean instead of guessing, and read the tool list off get_agent rather than from memory. Removing a never from the list deletes its scenario too. Call this during the interview, before writing config: the answers persist on the draft version, so they survive into the next build and a later reader can see what the operator actually asked for. This records intent, it does not change how the agent behaves. Wire the behaviour itself with update_system_prompt and the matching set_* ops.

Update call handling POST

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'.