Operations
Operations

Set workflow function

Add or replace one function in the agent's workflow, matched by name within its slot. Functions are self-contained steps that run around the conversation: preCall functions run before the agent's first turn (kinds http, a request to any https endpoint; tool, one of this version's in-call tools; and app, an action of a connected app) and each result reaches the agent in its call context; callEnded (hang-up) functions run the moment the call ends, before analysis, and stop after 10 seconds (kinds http, sms, email and slack; they see {{disconnection_reason}}, {{call_status}} and {{call_duration_seconds}} but no analysis variables, and call_status is ended or error at hang-up; an outbound campaign or lead-callback call that rings out or is busy starts no conversation and runs only its callEnded functions, with disconnection_reason no_answer or busy, call_status not_connected and {{caller.number}} the number dialled); postCall functions run after the call is analysed (kinds http, tool, app, sms, email and slack). Each function sets `after` (names in the same slot it waits on; [] starts at once; a chain holds at most 4), optional `when` (all or any of: a variable rule such as {"kind":"variable","variable":"call_successful","op":"eq","value":"false"}, and on callEnded or postCall a disconnection_reason or call_status rule, or an early_hangup rule such as {"kind":"early_hangup","underSeconds":30}, which matches when the caller hung up within that many seconds, 5 to 600; a variable rule on a value with a fixed set takes eq, neq, exists or not_exists and one of its values: call_successful is true or false; user_sentiment is positive, neutral or negative; urgency is urgent or normal; caller_type is new_lead, existing or spam; call_outcome is handled, abandoned, dropped, transferred or unknown; disconnection_reason is agent_end_call, busy, caller_hangup, connection_lost, emergency, error, idle_timeout, injection_hangup, max_duration, moderation_hangup, no_answer, no_input_hangup, outside_hours, transfer_to_human, voicemail_detected or voicemail_reached; call_status is ended, error or not_connected; caller_is_team is true or false; call_duration_seconds also takes gt, lt, gte and lte with a number), `inputs` ({"param": {"mode":"value","value":"text with {{variable}} placeholders"}}; on postCall an input may instead be {"mode":"ai","prompt":"The caller's preferred callback time"}, which the call analysis fills from the call and leaves empty when the call does not say). On postCall an sms may set `sms.prompt` and an email `email.prompt` (such as "Thank the caller and confirm the job they booked"): the call analysis writes the text or body from it, and the written text or body is not sent. AI-filled inputs and messages count with the post-call fields against one limit of 20 analysis fields, and preCall and callEnded functions take neither. An http POST, PUT or PATCH may set `http.body`, a JSON template sent in place of the inputs; a {{variable}} inside a string is filled JSON-escaped, and one standing alone must hold a number, true, false or null. Without a body the inputs are sent as {name, args, call} unless `http.argsOnly` is true. An app function sets `app` ({"toolkit":"hubspot","action":"HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA"}; list_agent_connections names the toolkits and list_connector_tools the actions) and passes the action's parameters as `inputs`; each value is converted to the type the action declares. Saving an app function needs workspace-admin access and an app the workspace has connected; when the agent has no row for that app yet, it gets one that loads none of the app's tools during the call, so only the workflow runs the action. A function may also set `outputs.variables` (name to a dot path in the response, readable as {{name}} by later functions, the system prompt and post-call functions) and `outputs.types` (the type of an output by name, boolean or number, such as {"vip":"boolean"}; an output left out is text): a condition on a boolean output takes eq, neq, exists or not_exists with true or false, and one on a number output takes a number under gt, lt, gte and lte. Placeholders: agent variables, {{caller.number}} and the other {{caller.*}} fields, {{direction}}, {{channel}}, {{agent_number}}, {{call_id}}, outputs of functions this one waits on, and on postCall {{call_summary}}, {{call_successful}}, {{user_sentiment}}, {{disconnection_reason}}, {{call_status}} and the other call results, and the caller details the analysis extracts: {{customer_name}}, {{account_number}}, {{phone_number}}, {{email}}, {{address}}, {{issue_type}} and {{resolution}}, each post-call field declared with set_post_call_field, by its name, and {{transcript}} (the call as Caller: and Agent: lines, newest kept within 20,000 characters, empty when the agent keeps basic details only); on callEnded and postCall also each output an in-call HTTP tool keeps with set_tool_outputs. Never put a credential in a header, query, body or input: use a {{variable}} and set_secret_variable. A slack function may set `slack.channel` ({id, name} of a channel list_call_alerts returns under slackChannels); without one it posts to the workspace's first channel. Up to 15 functions per slot. Pass `previousName` to rename. Set `enabled` false to turn a function off without deleting it, or use set_workflow_function_enabled. Works on a draft, or on a published latest version when you pass draftFrom.

POST
/operations/set_workflow_function

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_workflow_function" \  -H "Content-Type: application/json" \  -d '{    "slot": "preCall",    "function": {      "name": "string",      "kind": "http"    },    "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
}