# Custom Action

Call your API, run code on your website, or display a widget during a conversation.

## Overview

A custom action connects your agent to functionality you control. Use it to look up a record, pass a request to your own service, read a customer's cart on your website, or present a structured result in chat.

### Best for

Business-specific workflows that need your own data, website functions, or interactive interface.

## Action types

| Type | Runs where | Result |
| --- | --- | --- |
| Call API | QwryAI server | The agent uses the permitted API response data in its reply. |
| Run client-side code | Your website | A registered JavaScript function returns a result to the conversation. |
| Call API + show widget | Server and chat interface | An API response supplies data for a linked widget. |
| Show widget | Chat interface | A linked widget displays fixed or supplied data; automatic website triggers are available. |

![Choose an action type](/docs/screenshots/original/qwryai-action-types.jpg)

The QwryAI custom action editor offers four action types. This saved action runs code on the visitor’s page.

## Create a custom action

1. Open Build → Actions, choose Create action, then Custom actions.
2. Select the action type and choose Save and continue.
3. Complete General with the action name and When to use instructions.
4. Define the data inputs the action needs. For API actions, configure the request; for client actions, register the website function.
5. Run the API test when applicable, then choose what response data the AI may access.
6. For a widget action, add or select a widget and connect its inputs.
7. Select the supported channels, save your configuration, and use Save & enable.
8. Test a realistic conversation in the channel where customers will use it.

## General

Use an action name that describes one task, such as Look up delivery status. In When to use, describe the customer's request, the inputs needed, and the expected outcome. Avoid instructions that overlap with unrelated actions.

Use When not to use (optional) to describe requests that should be excluded. This helps distinguish the action from other tools that have similar purposes.

> **Automatic activation**: Only Show widget supports Visit, Delay, Scroll, and Chat opened triggers. These run in website chat and require Chat bubble to stay enabled.

- [All trigger and display settings](/docs/user-guides/actions/automatic-triggers)

## Collect inputs

Add one input per value the action needs. Each row has a name, type, description, default, and Required setting. The supported scalar types are text, number, boolean, date, and email; Array collects multiple values. Use descriptive names that match your request variables or website handler.

| Setting | How to use it |
| --- | --- |
| Name | The variable passed to the request, widget, or client handler. Keep it unique. |
| Type and Array | Match the value expected by your destination. Review the default again after changing a type. |
| Description | Explain what to collect and any expected format. Client-side input descriptions are required. |
| Default | Provide a correctly typed fallback only when using it is appropriate for this task. |
| Required | Mark values that must be available for the action to proceed. |

## API request

Enter a public HTTPS endpoint and choose GET, POST, PUT, PATCH, or DELETE. Configure query parameters and headers in their respective rows. The body editor is available for POST, PUT, and PATCH; GET and DELETE do not use a body in this editor.

Use the variable picker to insert collected inputs, static conversation variables, or values from a connected integration. Ensure every input referenced in the request is defined. Put service authentication in the server request configuration, never in a browser registration snippet.

```http
GET https://api.example.com/orders/{{order_id}}
Accept: application/json
```

> **Your own endpoint**: The example domain illustrates the request format. Replace it with your service and its authentication requirements. Localhost and private network endpoints are not supported targets.

## Test response

Provide sample input values and run the API test. Inspect the returned status and response before continuing. Example JSON can help you configure response fields, but it does not replace a successful live API test for the current request.

If you change request-related settings after a passing test, run it again before enabling. Changing channels or response exposure does not itself change the HTTP request.

- [Test and publish an action](/docs/user-guides/actions/testing-and-publishing)

## Data access

Choose Full access to make the available response data accessible to the AI, or Limited access to select the fields it needs. Limited access requires at least one selected field. Prefer a small response that directly answers the user's request.

Review the response tree and output mapping after changing your API response. A widget's bindings and the data the AI can read serve different purposes: check both before launch.

## Channels

Select at least one supported channel. Client-side actions need a browser host and offer Chat bubble and Help page. Automatic widget triggers run only on website Chat bubble. Other action types show their supported channels in the editor.

> **Test the actual destination**: An editor preview does not register a function on your website or confirm a messaging channel's rendering. Finish your test in the customer-facing channel.

## Related guides

- [Client-side actions and a complete HTML example](/docs/user-guides/actions/client-side-actions)
- [Widgets and response mapping](/docs/user-guides/actions/widgets)
- [Automatic triggers](/docs/user-guides/actions/automatic-triggers)