Best for:
Anything Chatbase doesn’t have a built-in Action for: looking up records in your own database, triggering a workflow, or showing a custom UI in the chat.
- “Upgrade my subscription to premium”
- “What’s the weather in London?”
- “Look up my account balance”
Action Types
When creating a Custom Action, you select a type that determines how the Action behaves:Call API + show Widget and Show Widget Actions let you attach a Widget to the Action. You can create and manage Widgets directly from the Action’s configuration page. See the Widgets documentation for details on building Widgets.
How to create the Action
1
Navigate to Actions
Go to your Chatbase dashboard and select your AI agent. Click Build > Actions in the left sidebar.
2
Create the Action
Click Create Action, then select Custom Action and the type you need.
3
Configure General Settings
See General below, then click Continue.
4
Configure the API
Define the data inputs the AI agent collects and the request it sends. See API below, then click Continue.
5
Test the response
Verify the endpoint returns what you expect. See Test Response below, then click Continue.
6
Set data access
Choose how much of the response the AI agent can see. See Data Access below, then click Continue.
7
Choose Channels
Call API Actions are compatible with every channel. The other three types work only on the Chat Bubble, Help Page, Center Stage, and the Android and iOS SDKs. Toggle the Action on or off for each configured channel. See Channels for what configured, unconfigured, and incompatible mean.
8
Enable and Test
Ensure the Action is toggled to Enabled, then test it in the Playground.
General
Action Name: A descriptive name for this Action, such asGet_Order_Status. The AI agent sees this name, so it helps the AI agent know when to use it. Names can contain only letters, numbers, underscores, and hyphens, with no spaces.
When to use: A detailed description explaining when the AI agent should use this Action and API. Include examples of the data this Action provides and the customer queries it helps answer.
To restrict the Action to Procedure steps only, turn on Only use in Procedures. When it’s on, the When to use field is hidden, because the AI agent no longer decides when to call the Action.
A request body, when you add one, must be valid JSON, and your endpoint’s response must be JSON. An empty successful response is treated as
{}.API
Collect data inputs from user
The list of information the AI agent needs from the customer to perform the Action. Each input has:- Name: Name of the data input. Use it in the request as
{{name}}. - Type: Text, Number, Boolean, Date, or Email.
- Array: Check this to accept a list of values instead of one.
- Description: A short sentence describing the data input to the AI agent, so it knows what to ask for.

API request
The endpoint the AI agent calls to retrieve data or send updates. You can include data inputs collected from the customer in the URL or the request body.- Method:
GET(default),POST,PUT,PATCH, orDELETE. The Body tab is disabled forGETandDELETE. - HTTPS URL: The URL of the API the AI agent should call. It must start with
https://. - Add variable: Inserts a variable that depends on the customer’s input. See Variables.

- Parameters: Key-value pairs sent as part of the request URL to provide input data or filter the response.
- Headers: Metadata sent along with the request to describe the request or client.
- Body: The data sent as part of the request. The body must be JSON-formatted. A variable inside quotes, such as
"{{message}}", is escaped automatically when its value would break the JSON, for example a quote or a line break, so you don’t need to instruct the AI agent to escape it.
Chatbase sends only the headers you add. If your endpoint expects JSON, add a
Content-Type: application/json header yourself.Variables
You can use variables in the URL path, Parameters, Headers, and Body:
Values in Parameters are URL-encoded. Values in the Body are inserted as they are, and escaped only inside JSON strings.
For example, a
Get_Order_Status Action could call https://api.example.com/orders/{{orderNumber}}?email={{contact.email}}, where orderNumber is a data input the AI agent asks the customer for.
Authentication
Authenticate with static Headers or Parameters, such asAuthorization: Bearer <your API key> or x-api-key: <your API key>. There’s no built-in Basic auth or OAuth flow, and Chatbase doesn’t fetch or refresh tokens. For Basic auth, type the full Authorization: Basic <encoded credentials> header yourself.
Test Response
- Live response: Test with live data from the API to make sure it’s configured correctly.
- Example response: Use example JSON data if the API isn’t ready yet.
Data Access
- Full data access: The AI agent can access all available information from the API’s response, giving comprehensive replies based on complete data.
- Limited data access: Restricts the information the AI agent can access, giving more controlled and specific replies while protecting sensitive data. A table lists every field in the test response by its path, such as
data.user.email, with its size. Check the fields the AI agent may see. An array counts as one field. At runtime, only the checked fields are passed to the AI agent.
Test the Action in the Playground with a query that should trigger it, and confirm the AI agent calls your endpoint and uses the response in its reply.
Examples
Upgrade subscription
AnUpdate_Subscription Action that lets the customer ask the AI agent to upgrade their subscription to the premium plan.
In the General section, the Action is named Update_Subscription, with a When to use description telling the AI agent to call this API whenever the customer wants to upgrade.


https://demo-rhythmbox.chatbase.fyi/api/update-subscription with the method set to GET.

active and premium as the upgrade example.



Weather API
AGet_Weather Action that provides weather information for any city the customer asks about.
In the General section, the Action is named Get_Weather, with a When to use description telling the AI agent to use this API whenever it’s asked about the weather of any city.

City, with the type Text and the description: The city that you want to know its weather.

https://wttr.in/{{city}}?format=j1 with the method set to GET. The key-value pair in the parameters is added automatically after entering the URL.

London as the city.



How the AI agent handles the response
- Success: the response (filtered by Data Access) goes to the AI agent, which writes its reply from it.
- Error status: if your endpoint returns a non-2xx status, the AI agent sees the status code and the first 1,000 characters of the response body, then writes its own reply. Don’t put anything in error bodies that the customer shouldn’t read.
- Not JSON: a successful response that isn’t JSON is passed to the AI agent as an error.
- Too large: if the response is over 20KB after Data Access filtering, the AI agent gets “Response is too large”.
- Timeout: Chatbase waits up to 60 seconds for your endpoint, then passes a timeout error to the AI agent. Failed requests aren’t retried.
Limitations
- The maximum response size is 20KB. It’s measured after Limited data access filtering, so unchecking fields can bring a response under the limit. The request body has no size limit.
- Requests and responses must be JSON. The request body must be JSON-formatted, and the returned response must be JSON-formatted.
- 60-second timeout, no retries. Slow endpoints fail, and the AI agent lets the customer know.
- Static authentication only. Headers and parameters only, with no OAuth or token refresh.
- Client-side and Widget types work on fewer channels. Run client-side code, Call API + show Widget, and Show Widget run only on the Chat Bubble, Help Page, Center Stage, and the Android and iOS SDKs. They aren’t available on WhatsApp, Messenger, Instagram, Email, Phone, Slack, or API. Run client-side code executes in the customer’s browser through the embed script or in your app through the SDK.
Best Practices
Clear Action Triggers
Write a specific When to use description that names the data this Action provides and the customer queries it answers.
Describe Every Input
The input description is what the AI agent uses to decide what to ask the customer for. Vague descriptions produce wrong values.
Limit Data Access
Use Limited data access when the response contains anything the AI agent shouldn’t repeat back to the customer.
Keep Responses Small
Return only the fields the AI agent needs. Trimming the response keeps you under the 20KB cap and makes replies more accurate.
Frequently asked questions
How do I authenticate a Custom Action with my API?
How do I authenticate a Custom Action with my API?
Add your API key or token as a static header, for example
Authorization: Bearer <your API key>, or as a parameter. Basic auth works if you type the full Authorization: Basic ... header. OAuth flows and token refresh aren’t supported.Can I pass the customer's email or the conversation ID to my API?
Can I pass the customer's email or the conversation ID to my API?
Yes. Use
{{contact.email}}, {{conversationId}}, and the other variables in the URL, parameters, headers, or body.What happens when my API returns an error?
What happens when my API returns an error?
The AI agent sees the status code and the first 1,000 characters of the response body, then writes its own reply to the customer. Requests that take longer than 60 seconds time out, and failed requests aren’t retried.
Can a Custom Action run on WhatsApp, email, or phone calls?
Can a Custom Action run on WhatsApp, email, or phone calls?
Only the Call API type. Run client-side code, Call API + show Widget, and Show Widget need the Chat Bubble, Help Page, Center Stage, or the mobile SDKs.
Does the AI agent ask the customer before calling the API?
Does the AI agent ask the customer before calling the API?
No. It calls the Action as soon as it decides to. To require a confirmation, for example before a refund or cancellation, say so in When to use.
My response is over 20KB. What can I do?
My response is over 20KB. What can I do?
Switch to Limited data access and check only the fields the AI agent needs. The limit is measured after this filtering. You can also return fewer fields from your endpoint.