Operations
Operations

Update behaviour

Update conversation + turn-detection + context-memory + transfer-detection knobs, maxResponseTokens (50-2000 spoken-reply brevity in TOKENS, spoken as roughly tokens × 0.75 words, cut at a sentence boundary once a turn runs well past that, NOT a token cap), llmTemperature (0-1), llmThinking (the model reasons before each reply; only on the models that offer thinking), llmEffort (the thinking level while llmThinking is true: low, medium or high), backgroundNoise (ambience bed under the call), backgroundNoiseVolume (0-1 loudness of that bed), backgroundNoiseProfile (which bed plays; default office), typingSpinner (a sound during a tool lookup), typingSpinnerSound (which clip plays; default keyboard), pauses (the named pauses the prompt writes as [pause:NAME]; replaces the whole list), shortTurnTimeout (0.5-5 seconds), longTurnTimeout (15-30 seconds; floored at 15), eotThreshold (0-1 end-of-turn confidence), eagerEotThreshold (0-0.9 quick-response eagerness; higher = replies sooner), autoSummarization, maxContextTokens (1000-16000), maxUnsummarizedMessages (5-100), summaryTargetTokens (500-8000), amdEnabled, amdTier2Enabled. shortTurnTimeout and longTurnTimeout are in SECONDS; eotThreshold/eagerEotThreshold are 0-1 confidences; AMD stands for answering-machine detection. Send only what changes. Use this for 'shorter answers' (maxResponseTokens down), 'less likely to interrupt' (eotThreshold up), 'more creative' (llmTemperature up), 'think before answering' (llmThinking true), 'think harder' (llmThinking true with llmEffort high), 'answer faster' on a model that offers thinking (llmThinking false), 'wait longer before responding' (longTurnTimeout up), 'add background noise' (backgroundNoise true), 'quieter background' (backgroundNoiseVolume down), 'make it sound like a cafe' (backgroundNoiseProfile cafe), 'play a typing sound during lookups' (typingSpinner true), 'use the typewriter sound' (typingSpinnerSound typewriter), 'add a 1.5 second typing pause called lookup' (pauses with { name: lookup, seconds: 1.5, sound: keyboard } added to the existing list), 'summarise long calls' (autoSummarization true), 'detect voicemail before transferring' (amdEnabled). Pass null for a field to unset it, back to the default.

POST
/operations/set_behaviour_settings

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_behaviour_settings" \  -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
}

Update answering hours POST

Configure answering hours, the schedule that decides whether the agent takes a call live or does something else outside it, on agents.settings.answeringHours. Agent-level, NOT versioned. All fields optional; send only what changes. everyDay sets all seven days in one call ({open:"HH:MM", close:"HH:MM"} or null to close every day); mon/tue/wed/thu/fri/sat/sun each override an individual day (applied AFTER everyDay in the same call, so a day-specific value wins). Times are 24h HH:MM in the agent's effective timezone (agent timezone from General, else the workspace timezone); close may be "24:00"; a close earlier than open wraps past midnight. enabled turns the schedule on/off, off (default) means the agent answers around the clock. Turning enabled on is REFUSED while the closed message is empty (unless outsideHoursAction is 'agent'): call set_closed_message FIRST to write and render the message, then set_answering_hours enabled: true. To pause live calls indefinitely, call set_closed_message first, then send enabled: true, everyDay: null, outsideHoursAction: 'message'. Calls play that message and hang up until you disable answering hours or reopen a day; unlike set_manual_close, this pause does not expire at the next opening. outsideHoursAction picks what happens outside the window: 'message' (default) plays the pre-rendered closed message and ends the call; 'forward' rings forwardNumber instead, e.g. the bar's phone after the restaurant closes, and an unanswered forward still falls back to the closed message; 'agent' lets the agent answer every call and tells it, on each call, whether the business is open now and when it closes or next opens, for a business that takes orders or bookings for later while it's shut (no closed message needed). forwardNumber is required (and normalised to E.164) when outsideHoursAction is 'forward'. Use for 'only answer 9 to 5', 'close on weekends', 'we're open till 10pm on Fridays', 'stop taking calls after hours', 'forward calls to the bar after 11pm', or 'the agent keeps answering, but should know when we're open'.

Edit branding POST

Set the agent's caller-facing branding on `agents.settings.branding`: `displayName` (the business name shown on the request_details_form detail-capture page the caller fills in, as the website chat widget's header name, in the header of the agent's public share page, and on the staff transcript link of a website chat handoff) and `formMessage` (a short line under it on that form, used nowhere else). In the app both live under Business details on the agent's Channels tab. Pass only the field you want to change; an empty string or null clears it (the display name then falls back to the agent's name). Set this to the customer's trading name, a leftover onboarding placeholder is caller-visible whenever the agent texts a details form. The logo is uploaded separately and is not settable here.