Create a custom action

A custom action is the most flexible tool — it can call your API, show a widget, or do both. Create one from Actions → Create action.

Pick a type

• Call API — fetch data from your endpoint and let the agent use it in its answer.
• API + Widget — call your API, then render the response as a widget in the chat.
• Widget only — show an interactive widget with no API call (the agent fills it from the conversation).
• Run code (Client) — run your JavaScript in the visitor’s browser to do something on your site (see below).
• Send to Help Desk — collect inputs and open a ticket in your Help Desk inbox for your team to handle (see below).

General

• Action name — the function name the agent calls (letters, numbers, underscores), e.g. get_order_status.
• When to use — a clear description of when the agent should use this, with example questions it answers. This is how the agent decides to call it, so be specific.

API request

For Call API and API + Widget actions, set the method and URL, plus optional headers and body (both JSON). Insert collected inputs anywhere with {{input_name}} tokens.

Method: GET
URL:    https://api.example.com/orders/{{order_id}}
Headers: { "Authorization": "Bearer ..." }

Data the agent collects

Declare the inputs the agent should gather from the customer — each has a name, type (string / number / boolean), a description (which helps the agent fill it correctly), and whether it's required. These become the action's parameters.

Run code (Client) actions

A Client action runs your JavaScript in the visitor’s own browser, on your site — so it can do things the page can do: add an item to the cart, redirect to checkout, open a cart drawer, prefill a field, or fire an analytics/pixel event. The agent decides when to trigger it and passes along the inputs you defined.

Your code receives two things: args (the inputs the agent collected) and bookbag (the embed SDK). It runs as a side effect — it does not return a value back to the agent. If you need data back in the agent’s answer, use a Call API action instead.

// Go to checkout
window.location.href = '/checkout';

// Add a variant to the Shopify cart
fetch('/cart/add.js', {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: args.variant_id, quantity: 1 }),
});

// Prefill a field, then fire an analytics event
document.querySelector('#email').value = args.email;
window.dataLayer?.push({ event: 'chat_action', name: args.name });

Send to Help Desk actions

A Send to Help Desk action lets the agent hand a conversation to your team. The agent collects the inputs you define — for example name, email, and message — and opens a ticket in your Help Desk inbox. Your team replies from there, and the reply is emailed back to the visitor.

• Inputs — define the fields the agent gathers (name, email, the question), exactly like any other action.
• Ticket subject (optional) — a subject template using {{input_name}} tokens, e.g. Billing question from {{name}}, so tickets are easy to scan.
• Hand the conversation to a human (toggle) — when on, the AI is paused on that chat so a person takes over. When off, the AI keeps helping while your team follows up async.

Run mode

Choose Run automatically for read-only lookups, or Ask the user to confirm first for anything that changes data.

Test it

Use the Test button on the action to run it with sample inputs and inspect the raw result before you rely on it in live chats. For confirm-mode actions the test approves the run for you so you can see the output.

What's next