> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Actions: connect your AI agent to any API

> Call your own API, run code in the browser, or show an interactive Widget, all from inside the conversation

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.

> [card] 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:

| Type | What it does | Channels |
| - | - | - |
| **Call API** | Calls an external API and returns the response to the AI agent. The AI agent uses the response data in its reply. | Every channel, including WhatsApp, Messenger, Instagram, Email, Slack, API, and Phone |
| **Call API + show Widget** | Calls an external API, then displays a [Widget](https://chatbase.co/docs/developer-guides/widgets/overview.md) inline in the chat with the response data. Use this to show rich, interactive UI after fetching data. | Chat Bubble, Help Page, Center Stage, Android SDK, iOS SDK |
| **Run client-side code** | Executes code in the customer's browser via the [JavaScript embed script](https://chatbase.co/docs/developer-guides/website-integration/client-side-custom-actions.md), or in your app through the mobile SDKs. Useful for accessing browser APIs and frontend context. | Chat Bubble, Help Page, Center Stage, Android SDK, iOS SDK |
| **Show Widget** | Displays a [Widget](https://chatbase.co/docs/developer-guides/widgets/overview.md) inline in the chat without calling an API. The AI agent populates the Widget from the conversation context. Use this for forms, info cards, and interactive menus. | Chat Bubble, Help Page, Center Stage, Android SDK, iOS SDK |

> [!NOTE]
>
> **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](https://chatbase.co/docs/developer-guides/widgets/overview.md) for details on building Widgets.

## How to create the Action

**1. Navigate to Actions**

Go to your [Chatbase dashboard](https://www.chatbase.co/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](#action-types) you need.

**3. Configure General Settings**

See [General](#general) below, then click **Continue**.

**4. Configure the API**

Define the data inputs the AI agent collects and the request it sends. See [API](#api) below, then click **Continue**.

**5. Test the response**

Verify the endpoint returns what you expect. See [Test Response](#test-response) below, then click **Continue**.

**6. Set data access**

Choose how much of the response the AI agent can see. See [Data Access](#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](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#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.

> [!TIP]
>
> You can also ask [Backstage](https://chatbase.co/docs/user-guides/chatbot/backstage.md#building-custom-actions) 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](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) steps only, turn on [**Only use in Procedures**](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#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.

> [!NOTE]
>
> 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](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-13.png?fit=max\&auto=format\&n=DIWSTyTSabxfVW3B\&q=85\&s=9a3ed68a5d01a32c06059648dbc1a7fc)

### 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](#variables).

![Configuring the API request for a Custom Action](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-14.png?fit=max\&auto=format\&n=DIWSTyTSabxfVW3B\&q=85\&s=26b96a050e4b3a977ae42e3d68c32186)

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.

> [!NOTE]
>
> 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**:

| Variable | Value |
| - | - |
| `{{inputName}}` | A data input the AI agent collected, by its **Name** |
| `{{conversationId}}` | The ID of the current conversation |
| `{{userId}}` | The user's ID, for [identified users](https://chatbase.co/docs/developer-guides/website-integration/identity-verification.md) only |
| `{{callerPhone}}` | The caller's phone number, on Phone only |
| `{{contact.id}}`, `{{contact.external_id}}`, `{{contact.email}}`, `{{contact.name}}`, `{{contact.phonenumber}}`, `{{contact.stripe_accounts}}`, `{{contact.created_at}}`, `{{contact.updated_at}}` | Fields of the [Contact](https://chatbase.co/docs/user-guides/chatbot/contacts/contacts-overview.md) linked to the conversation |
| `{{contact.custom_attributes.<name>}}` | A custom attribute of the Contact |

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.

> [!WARNING]
>
> 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.

> [!TIP]
>
> 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](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/general-upgrade.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=3325a85b7da278f4793823fd6945731e)

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](https://mintcdn.com/chatbase/fuaTVXjARv0sH-Me/user-guides/chatbot/images/actions/api-upgrade.png?fit=max\&auto=format\&n=fuaTVXjARv0sH-Me\&q=85\&s=880a1551ca3ea7d7a9fcff72c2946d23)

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](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/request-upgrade.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=fd0b8f9766246af77d039df40b86a7a9)

In **Test Response**, the endpoint is tested with `active` and `premium` as the upgrade example.

![Testing the Update\_Subscription response](https://mintcdn.com/chatbase/fuaTVXjARv0sH-Me/user-guides/chatbot/images/actions/test-upgrade.png?fit=max\&auto=format\&n=fuaTVXjARv0sH-Me\&q=85\&s=26615f535b77e96a7f974cd6bd399a80)

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](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/access-upgrade.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=547e94410e170c85e5cb116792243c4f)

The AI agent can now upgrade or downgrade the subscription when the customer asks.

![The AI agent upgrading a subscription in chat](https://mintcdn.com/chatbase/fuaTVXjARv0sH-Me/user-guides/chatbot/images/actions/upgrade-example.gif?s=7efb8fa8187a75e5c1561e23646fb88a)

### 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](https://mintcdn.com/chatbase/EhvCUQ4ZmSlhciUK/user-guides/chatbot/images/actions/actions-15.png?fit=max\&auto=format\&n=EhvCUQ4ZmSlhciUK\&q=85\&s=e810408db085edbbbd96c76329b99a07)

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](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-16.png?fit=max\&auto=format\&n=DIWSTyTSabxfVW3B\&q=85\&s=710a09ede97b9ba13d80a9c1c8672682)

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](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-17.gif?s=0e33d9664181294a2a2f54f5ae912018)

In **Test Response**, the endpoint is tested with `London` as the city.

![Testing the Get\_Weather response](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-18.gif?s=2fbd85f1eae6984cb7d892737bb6ac65)

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](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-19.png?fit=max\&auto=format\&n=DIWSTyTSabxfVW3B\&q=85\&s=58d2e212b4e4b1809c25ea00bcc3e0ef)

The AI agent can now answer the weather for any city the customer asks about.

![The AI agent returning weather information in chat](https://mintcdn.com/chatbase/DIWSTyTSabxfVW3B/user-guides/chatbot/images/actions/actions-20.gif?s=914e089812fc8122e77d813d77a4cf40)

## How the AI agent handles the response

* **Success:** the response (filtered by [Data Access](#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](https://chatbase.co/docs/developer-guides/website-integration/client-side-custom-actions.md) or in your app through the SDK.

## Best Practices

> [card] Clear Action Triggers
>
> Write a specific **When to use** description that names the data this Action provides and the customer queries it answers.

> [card] 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.

> [card] Limit Data Access
>
> Use **Limited data access** when the response contains anything the AI agent shouldn't repeat back to the customer.

> [card] 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

> [accordion] 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.

> [accordion] Can I pass the customer's email or the conversation ID to my API?
>
> Yes. Use `{{contact.email}}`, `{{conversationId}}`, and the other [variables](#variables) in the URL, parameters, headers, or body.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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**.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.