Skip to main content
Custom Actions connect your AI agent to anything you can reach over an HTTPS API. The AI agent calls your endpoint, gets the JSON response back, and uses that data in its reply, so it can answer questions and perform tasks that live in your own systems. A Custom Action can also run code in the customer’s browser or show an interactive Widget in the chat, on the Chat Bubble, Help Page, Center Stage, and the mobile SDKs.

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.
Common Use Cases:
  • “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.
You can also ask Backstage to build the Action for you. Describe what your AI agent should do and share your API docs, and Backstage configures, tests, and enables the Action in conversation.

General

Action Name: A descriptive name for this Action, such as Get_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.
There’s no Required setting. If the AI agent doesn’t have a value, it can leave the input empty, and an empty string is sent in its place. Use the description and When to use to tell the AI agent which inputs it must ask for. Show Widget inputs also have a Default column.
Configuring data inputs for a Custom Action

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, or DELETE. The Body tab is disabled for GET and DELETE.
  • 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.
Configuring the API request for a Custom Action
When the URL is added, the parameters, headers, and body are populated automatically:
  • 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 as Authorization: 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.
Header and parameter values are saved as you type them and shown in plain text in the Action editor, so anyone who can edit the Action can see them. Use an API key scoped to only what the Action needs.

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

An Update_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.
General settings for the Update_Subscription Action
In the API section, the data inputs are the status of the plan and the new plan requested, described as: Active or canceled. If they want to upgrade to premium, send ‘active’.
Data inputs for the Update_Subscription Action
In the API request section, the URL is https://demo-rhythmbox.chatbase.fyi/api/update-subscription with the method set to GET.
The API request for the Update_Subscription Action
In Test Response, the endpoint is tested with active and premium as the upgrade example.
Testing the Update_Subscription response
In Data Access, Full data access is selected so the AI agent can use all the information from the response.
Data access settings for the Update_Subscription Action
The AI agent can now upgrade or downgrade the subscription when the customer asks.
The AI agent upgrading a subscription in chat

Weather API

A Get_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.
General settings for the Get_Weather Action
In the API section, the input is named City, with the type Text and the description: The city that you want to know its weather.
Data inputs for the Get_Weather Action
In the API request section, the URL is 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.
The API request for the Get_Weather Action
In Test Response, the endpoint is tested with London as the city.
Testing the Get_Weather response
In Data Access, Full data access is selected so the AI agent can use all the information from the response.
Data access settings for the Get_Weather Action
The AI agent can now answer the weather for any city the customer asks about.
The AI agent returning weather information in chat

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.
The AI agent doesn’t ask the customer to confirm before calling the Action. For Actions that change data, such as cancelling an order, tell it in When to use to confirm the details with the customer first.

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

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.
Yes. Use {{contact.email}}, {{conversationId}}, and the other variables in the URL, parameters, headers, or body.
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.
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.
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.
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.