Custom Actions Reference
Configuration schema and runtime behavior for custom actions and human handover.
Custom actions configuration is stored per agent and edited from
Custom Actions. This page documents the underlying schema
and defaults. Human Handover uses the same actions_config JSONB but is documented in
Human Handover.
Configuration shape
{
"enabled": false,
"apiAction": false,
"sendNotification": false,
"apiActionConfig": { "...": "see below" },
"sendNotificationConfig": { "...": "see below" },
"handoverConfig": { "...": "see Human Handover doc" }
}apiActionConfig (the call_api tool)
{
"whenToUse": "",
"apiUrl": "",
"requireConfirmation": false,
"apiKeyHeader": "",
"apiKeyEnvVar": "ACTIONS_API_KEY",
"httpMethod": "GET",
"intentParamName": "intent",
"identifierParamName": "id",
"contextParamName": "context",
"timeoutMs": 15000,
"maxRetries": 2
}| Field | Type | Constraints |
|---|---|---|
whenToUse | string | Max 2,000 characters |
apiUrl | string | Must be a valid URL |
requireConfirmation | boolean | Ask the visitor to confirm before executing |
apiKeyHeader | string | HTTP header name to send the key in |
apiKeyEnvVar | string | Must be exactly ACTIONS_API_KEY or start with ACTIONS_API_KEY_ |
httpMethod | GET | POST | PUT | PATCH | DELETE | GET sends query params; others send a JSON body |
intentParamName / identifierParamName / contextParamName | string | Must start with a letter, then letters/digits/_/- |
timeoutMs | number | 1,000–60,000 |
maxRetries | number | 0–5 |
API key isolation
apiKeyEnvVar is validated against an allowlist prefix (ACTIONS_API_KEY /
ACTIONS_API_KEY_*) on the server. This is intentional: it stops an agent configuration from
pointing at platform secrets (LLM provider keys, database service role keys, billing
credentials, widget session secrets) and exfiltrating them to an attacker-controlled
apiUrl. Only env vars your operator has explicitly provisioned under this prefix can be
used.
sendNotificationConfig (the send_notification tool)
{
"whenToUse": "",
"slackWebhookUrl": "",
"emailWebhookUrl": "",
"defaultChannel": "email"
}| Field | Type | Notes |
|---|---|---|
whenToUse | string | Overrides the tool's default description for the model |
slackWebhookUrl | string | A Slack incoming webhook URL |
emailWebhookUrl | string | A webhook URL for your email-sending integration |
defaultChannel | "email" | "slack" | Used when the model doesn't pick one explicitly |
At runtime, this tool is used for escalation requests and feedback capture during a conversation. For live operator handover, use Human Handover instead (independent of the Custom Actions master switch).
handoverConfig (Human Handover)
Stored in the same actions_config object; configured from the Human Handover card on
the Actions page (not gated by enabled above).
{
"enabled": false,
"offlineMessage": ""
}| Field | Type | Notes |
|---|---|---|
enabled | boolean | Default false. When true, registers request_human_handover and pauses AI during operator handling |
offlineMessage | string | Optional visitor acknowledgement; max 500 characters |
Runtime behavior
When enabled is true, the configured tools are added to the model's available tools for
that agent (up to 5 tool calls per response). The model chooses when to call them based on
the conversation and your whenToUse instructions. Use the Test API button in the
dashboard to validate apiActionConfig.apiUrl responds as expected before enabling it for
live traffic.