Custom Action

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 — The QwryAI custom action editor offers four action types. This saved action runs code on the visitor’s page.

Create a custom action

Open Build → Actions, choose Create action, then Custom actions.
Select the action type and choose Save and continue.
Complete General with the action name and When to use instructions.
Define the data inputs the action needs. For API actions, configure the request; for client actions, register the website function.
Run the API test when applicable, then choose what response data the AI may access.
For a widget action, add or select a widget and connect its inputs.
Select the supported channels, save your configuration, and use Save & enable.
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.

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.

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

Overview

Best for

Action types

Create a custom action

General

Collect inputs

API request

Test response

Data access

Channels