Custom Actions Reference
Configuration schema and runtime behavior for the call_api and send_notification tools.
Custom actions configuration is stored per agent and edited from Custom Actions. This page documents the underlying schema and defaults for anyone scripting or reasoning about the exact behavior.
Configuration shape
{
"enabled": false,
"apiAction": false,
"sendNotification": false,
"apiActionConfig": { "...": "see below" },
"sendNotificationConfig": { "...": "see below" }
}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, human handoff requests, and feedback capture during a conversation.
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.