Custom Actions
Give your agent superpowers. Custom Actions let your AI call external APIs, collect structured data, and trigger real workflows — all from within a conversation, without any code on your end.
What are Custom Actions?
Custom Actions allow your agent to do more than answer questions. When a customer asks to check their order status, book an appointment, or submit a refund request, the agent can call your API directly — and show the real result in the conversation.
HTTP Request
Call any REST API with GET, POST, PUT, PATCH, or DELETE. Pass conversation variables in the URL, headers, or request body.
Use case: Look up a customer record, submit a form, trigger a Zapier webhook, or update a CRM.
Form Collection
Show a structured form to the customer inside the chat. Collect structured data like contact info, order details, or feedback.
Use case: Collect a return request, gather shipping details, or take a support ticket form.
Button Trigger
Show a clickable button in the chat. When the customer clicks, trigger an HTTP request or navigate to a URL.
Use case: Show a 'Book a Demo' button, a 'Download Invoice' link, or a 'Start Refund' action.
Creating a Custom Action
Go to Custom Actions
In the dashboard sidebar, click Custom Actions. Then click Create Action.
Choose an action type
Select HTTP Request, Form Collection, or Button Trigger from the wizard.
Configure the request
For HTTP actions: enter the endpoint URL, method, headers, and request body. Use template variables to inject conversation data.
Set the "When not to use" field
Define conditions where the agent should skip this action even if it seems relevant. Example: "Do not use this action if the customer has not provided their email address."
Test the action
Use the built-in test panel to trigger the action with sample values and verify the response. Check execution logs for request and response details.
Enable the action on your agent
Go to your agent's settings → Actions, and toggle the custom action on. The agent will now use it when appropriate.
Template variables
Use template variables in your request URL, headers, and body to inject real conversation context into your API calls.
{{conversation.id}}Unique conversation ID{{conversation.user_id}}Customer user identifier{{conversation.channel}}Channel (widget, whatsapp, slack, etc.){{message.content}}The customer's most recent message{{message.sentiment}}Sentiment of the last message{{lead.email}}Captured lead email (if lead form is enabled){{lead.name}}Captured lead name{{agent.id}}The agent's unique identifierExample: look up a customer account
This action calls your internal API to fetch a customer's account details using their email address captured from the lead form.
Action definition (JSON)
{
"name": "Get Customer Account",
"type": "http",
"method": "GET",
"url": "https://api.yourcompany.com/customers?email={{lead.email}}",
"headers": {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
"when_not_to_use": "Do not use this action if the customer has not provided their email address or if they are asking a general question."
}Example API response shown to agent
{
"id": "cust_abc123",
"name": "Jane Smith",
"plan": "Pro",
"conversations_used": 3250,
"conversations_limit": 5000,
"account_status": "active"
}The agent receives the response and can reference it naturally: "Your account (Jane Smith) is on the Pro plan with 3,250 of your 5,000 monthly conversations used."
Authentication options
The "When not to use" field
Every custom action has a "When not to use" field where you tell the agent when to skip the action. This prevents false triggers and keeps interactions natural.
Why this matters
Without guardrails, the agent might trigger an API call every time a customer mentions a keyword — even when it doesn't make sense. The "When not to use" instruction prevents unnecessary calls and reduces API costs.
Order lookup
Do not use if the customer hasn't provided an order number or email. Do not use for general questions about shipping policies.
Refund submission
Do not use unless the customer explicitly requests a refund. Do not use if the order is less than 24 hours old.
Appointment booking
Do not use if the customer is just asking about availability in general. Only use when they confirm they want to book.
Execution logs
Every time a custom action is triggered, the execution is logged with the full request and response details. Access logs from Custom Actions → select an action → Logs.
Each log entry includes
- Timestamp and conversation ID
- Full request: URL, method, headers (credentials redacted), and body
- HTTP response code and response body
- Execution time in milliseconds
- Whether the response was successfully injected into the conversation