Custom Actions
Custom actions enable your bot to access external systems - retrieving data or performing operations on behalf of customers. Once added, an action can be invoked from any workflow.
Important
Actions are not active by default. You must explicitly enable them inside workflows.
Action Structure
Each custom action is defined by three core properties:
Name
Unique identifier - used by the bot to reference the action
Description
Short summary describing what the action does
API Details
Configuration for calling the external API
Name
Follow camelCase naming conventions to ensure clarity and consistency.
Examples:
getOrderDetails
refundOrder
cancelSubscription
Description
A one-sentence explanation of the action’s purpose.
This is visible to the AI - write it so the bot understands what to ask it for and when.
Example:
Retrieves the customer’s active subscription and basic billing information.
API Details
Define how the platform connects to your API.
Required fields:
Base URL
https://api.company.com
Path
/products/inventory
Request Timeout
How long to wait before failing the request
Optional fields:
JSON Headers (often for authentication)
Query Parameters (?id=123&lang=en)
Request Body (for POST/PUT requests)
The path, headers, query parameters, and body collectively form the API inputs.
Inputs may be static or dynamically controlled by the bot.
Dynamic API Arguments
In real implementations, the bot often needs to provide parameters - e.g., order ID, product ID, or user ID.
Use $variableName syntax to expose dynamic input fields:
GET /orders/$orderIdEach variable becomes a required argument when the action is used in workflows.
Guidelines
Use camelCase for variable names
Choose intuitive names that convey meaning
Explain variables to the bot in the workflow setup for better reasoning
Security & Privacy
Your API response is visible to the bot and may be surfaced to the customer.
Only return data that is appropriate for the end user to see.
Reducing Sensitive Exposure
If the exact values are confidential, return abstracted indicators instead.
Example:
{ "inStock": true }instead of:
{ "stock": 123 }Customer Authentication
Consider requiring multiple matching identifiers when dealing with protected data.
Example:
Arguments: email + orderId
API filters with both values to verify ownership
Trade-off: Single-factor (e.g., only order ID) improves UX but carries a small theoretical risk if the bot is manipulated. Choose based on your security policy.
Best Practices
Keep action names and descriptions simple and purposeful
Limit the response to only necessary customer-visible data
Use dynamic arguments to allow personalized information retrieval
Introduce double verification for sensitive details
Add clear explanation for every exposed argument in workflows
Last updated