Custom action
Let your agent look up or send information to your own systems, like checking the status of an order.
A custom action connects your agent to a system your business already uses, such as your online store, booking tool, or order database. With it, the agent can answer "Where's my order 48213?" with the real status instead of a general reply.
Where to find it: open your agent, go to Build → Actions, and select Custom action.


How it works
Your systems talk to other software through an API: a way for one program to ask another for information, using a web address. Most online stores, booking tools, and CRMs have one.
Think of a custom action as a phone call to your back office with a fixed script. The agent always calls the same number (the web address you set), asks one specific question (like "what's the status of order 48213?"), and reads back the answer in plain words. It can only ask the questions you set up.
- 01Customer asks"Where's my order 48213?"
- 02Agent callsHourzero sends the order number to your system.
- 03System answersYour system replies with the order's status.
- 04Agent repliesThe agent explains the result to the customer.
What you can do yourself, and what needs a developer
You can set up most of a custom action on your own. A few parts depend on how your system works, and someone who knows that system should help.
You can set up:
- The name and When should the agent use it?
- The details the agent collects from the customer, like an order number, and how to describe them
- The Response instructions that tell the agent how to explain the result
- A Widget that shows the result as a card in your website chat
- Which channels can use the action, and testing it in the Playground
Ask a developer for:
- The Endpoint URL and Method: which address to call and what kind of request your system expects
- Any API key, which goes in Headers
- Making sure your system checks the details it receives, for example that the order number and email belong together
- The website options (Website API request and Website JavaScript handler) and the Client event
Tip
Send this page to your developer. The For developers section at the end has the technical details they need.
Example: look up an Acme order
This example builds the Look up order action for Acme Support. Your developer has told you that Acme's order system answers at https://api.acme.com/orders, expects an order number and the customer's email, and needs an API key.
-
Open Build → Actions and select Custom action.
-
In Action name, enter
Look up order. -
In When should the agent use it?, enter:
Use when a customer asks where their order is, when it will arrive, or what was in it. Ask for the order number and the email used for the order if you don't have them. Only share details the lookup returns. -
Leave Execution set to Server API request.
-
Under API request, set Method to GET and Endpoint URL to
https://api.acme.com/orders. -
Under Headers, select Add custom header. Enter
Authorizationas the Header name and the key from your developer, such asBearer acme-key-123, as the Header value. -
Under Request inputs, in Query string, select Add query parameter. Its settings open below it.
-
Fill in the parameter:
- Label:
Order number(the keyorder_numberis created for you) - Value type: Short text
- Description for the model:
The 5-digit order number from the confirmation email, for example 48213. - Requirement: Required
- Label:
-
Select Add query parameter again and add
Emailwith Value type Email, the descriptionThe email address the customer used to place the order., and Requirement Required. -
Under Response, in Response instructions, enter:
Tell the customer the order status and expected delivery date. If no order is found, ask them to check the order number and email. -
Select Create action.
Now, when a customer writes "Where's my order 48213?", the agent asks for their email, then calls Acme's system. Acme's system might reply with something like this:
{ "status": "shipped", "carrier": "UPS", "estimated_delivery": "2026-10-06" }
The agent turns that into a friendly answer: "Order 48213 has shipped with UPS and should arrive on October 6."
In your website chat, you can also show the result as an order card with the delivery date, the items, and a Track package button. See Widgets.
Tip
Pair this action with a Custom button that opens your tracking page, so the customer can follow the parcel themselves.
The settings, explained
Execution
This decides where the request runs.
- Server API request (the default): Hourzero calls your system directly. Use this unless your developer tells you otherwise. It works on every channel.
- Website API request and Website JavaScript handler: the request runs inside your own website, using the customer's existing login there. These need a developer and only work in the chat on your website. See Run actions on your website.
API request
- Method is the kind of request. GET usually means "look something up". POST, PUT, PATCH, and DELETE usually create, change, or remove something. Your developer will tell you which one your system expects.
- Endpoint URL is the web address of your system. It must start with
https://.
Headers
Headers are extra information sent with every request, most often an API key that proves the request comes from you. The standard headers Hourzero adds for you are listed with a Default label. Select Add custom header to add your own; you can add up to 20. Header values are fixed: the agent never sees or changes them.
Turn on Send the signed-in user's token to add the identity token your website signed for the visitor, in a Hourzero-User-Token header, so your system can confirm who they are. See Identity verification.
Request inputs
These are the details the agent fills in each time, like the order number. At the top, a preview shows the request as it will be sent, with each input colored by where it goes, for example GET https://api.acme.com/orders/{order_number}?status={status}. For methods other than GET, the line below it shows the JSON body.
The inputs are grouped by where they go:
- URL path: values inside the address itself, such as
https://api.acme.com/orders/48213. You don't add these here: they come from the Endpoint URL. See Put a value in the address. - Query string: values added after the
?, such as?status=shipped. Select Add query parameter. - JSON body: properties of the request body, such as
{ "note": "Gift wrap" }. Select Add body field. GET requests have no body, so this group is hidden for them, and switching to GET moves body fields to the query string.
Select an input to open its settings:
- Value comes from: for server API requests, The conversation (the agent fills it in) or the Signed-in user's ID, email, name, phone, or a custom attribute. A value from the signed-in user is filled in by Hourzero from identity verification, and the agent never sees or changes it. When a required one isn't known, such as for an anonymous visitor, the agent can't use the action.
- Label: a readable name. For query and body inputs, the key is created from it.
- Query key, JSON key, or Path placeholder: the exact name your system expects, such as
order_numberororderNumber. A path placeholder's name comes from the URL; rename it there. - Description for the model: tells the agent which value to use and where to find it. Be specific. Inputs without one are marked Add a description.
- Value type: Short text, Long text, Email, Phone, Number, Yes / no, Select, or Text list. A Text list sends one or more values as a list, such as
["Branding", "Web design"]. In the query string, each value is added as its own parameter. - Requirement: Required means the agent must have this value before it runs the action, so it asks the customer. Optional means it can leave it out.
- Null value: leave this on Non-nullable unless your developer asks for Nullable.
- Allowed values: for Select, a comma-separated list of the only values the agent may use, such as
standard, express. For Text list it's optional: fill it in to make the parameter a multi-select of those choices, or leave it empty to accept any text. - Send in the JSON body instead / Send in the query string instead: moves a query or body input to the other group (not for GET).
You can add up to 20 inputs. If you add none, the request is sent without any customer details.
Put a value in the address
Some systems expect the value inside the address rather than after a ?, for example https://api.acme.com/orders/48213. In Endpoint URL, type a name in curly brackets where the value belongs:
https://api.acme.com/orders/{order_number}
An order_number input appears under URL path right away. Open it to add a description. Editing the name inside the brackets renames the input and keeps its settings, and deleting {order_number} from the address removes it.
A URL path value is always required and can't be empty. Characters such as / or spaces are encoded, so the value never changes the rest of the address. Placeholders only work in the path, not in the domain or after the ?.
Response
- Response instructions (optional): how the agent should explain the result. For example, which details matter and what to say if nothing is found.
- Client event: for developers. See For developers.
Widget
A widget shows the result as a card, list, or form in your website chat, like an order card with a Track package button. Choose one of your saved widgets from the menu, or select Design a new widget in Backstage to make one from a sample of your system's reply. The preview shows the widget with the sample it was designed for.
Widgets show in Chat Bubble, Center Stage, and Chat Iframe. On other channels, the action still runs and the agent answers in text. See Widgets.
Test your action
- Open Playground, pick a channel such as Chat Bubble, and check that Look up order is switched on in the Capabilities tab. Select Save draft if you changed anything.
- In the preview, ask "Where's my order?" without a number. The agent should ask for the order number and email.
- Give a real test order, such as 48213, and its email. Check that the answer matches your system.
- Try an order number that doesn't exist. The agent should say it couldn't find it, not make up a status.
- Ask something unrelated, like "Do you sell gift cards?" The agent should answer without running the action.
- Open the chat in Activity → Conversations. Each action run appears as a box such as "Action · Look up order". Expand it to see exactly what was sent and what came back.
- When everything works, publish the channel.
Warning
Test actions that change things, like cancelling an order, with test data only. Every call in the Playground is a real request to your system.
Limits
- Only
https://addresses on the public internet. Addresses inside a private company network can't be reached. - Your system has 10 seconds to answer. After that, the request is cancelled.
- The reply can be up to 64 KB, which is plenty for a short summary but not for a whole catalog.
- Up to 20 headers and 20 parameters per action.
Troubleshooting
The agent says it couldn't complete the lookup
Your system answered with an error, took longer than 10 seconds, or sent back too much data. Open the chat in Activity → Conversations and expand the action to see the error, then share it with your developer.
The agent never runs the action
Make sure the action is switched on for the channel and that you saved the draft. Then make When should the agent use it? more specific, using the words your customers actually use.
I see "Enter a valid HTTPS URL."
The Endpoint URL must be a full web address that starts with https://.
An input under URL path says "Not in the URL"
The input is meant for the address, but the Endpoint URL has no matching {order_number}. This can happen when an action was set up outside the editor, for example by Backstage. Type the placeholder into the URL where the value belongs, or remove the input. Saving shows "Add {order_number} to the endpoint URL path." until you do.
Run actions on your website
Some actions should run as the customer who is logged in to your website, for example "show my recent orders". For these, a developer can pick a website option under Execution:
- Website API request calls an address on your own website, such as
/api/orders, from the customer's browser. The customer's existing website login is used. - Website JavaScript handler runs a small piece of code that your developer adds to your website. Enter its name in Handler name.
Important
Website actions only run in the chat embedded on your own website with the Hourzero script: Chat Bubble, Center Stage, or Chat Iframe installed with Script. They don't run in a Chat Iframe installed as Iframe only, the Playground preview, or messaging apps, so test them on your live site. If you limited the widget to certain pages, they only run on those pages. See Show the widget on certain pages.
For developers
This section has the technical details for the person connecting your system.
Server API requests
- Each input goes to its group: URL path, Query string, or JSON body. Inputs saved before these groups existed use the method's default: query parameters for
GET, the JSON body otherwise. With no body inputs, the body is{}.GETrequests never have a body. - A URL path input replaces its
{key}placeholder in the URL path (never the host or query). The value is percent-encoded as a single path segment, and empty,., and..values are rejected. - Query string inputs are added to any query already in the URL; a Text list repeats its key once per item, for example
?tag=a&tag=b. - Inputs that come from the signed-in user are filled in by Hourzero from the verified identity token, never from the model, and converted to the input's value type. A custom attribute that's an object or list is sent as JSON text unless the input is a Text list.
- With Send the signed-in user's token on, requests from signed-in visitors carry the token in a
Hourzero-User-Tokenheader. Verify it with the agent's identity secret (HS256) before trusting it. Like custom headers, it's dropped if a redirect goes to a different origin. - Omitted optional inputs are left out. A
nullvalue on a Nullable input is sent as JSONnullin a body and left out of a query string. Values such as0andfalseare kept. - Default headers:
Accept: application/json, text/plain;q=0.9, plusContent-Type: application/jsonfor requests with a body. Custom headers can override these. Connection-level headers such asHostandContent-Lengthcan't be set. Header names must be unique, ignoring case. - The URL must be HTTPS, must not contain credentials, and must resolve to a public address. Localhost and private ranges are blocked.
- Up to three redirects are followed and each destination is checked. Custom headers are dropped if a redirect goes to a different origin.
- Responses can be JSON or text, up to 64 KB, within 10 seconds. Any non-2xx status is treated as a failure.
Design your endpoint defensively:
- Treat every input as untrusted and validate it on your server.
- Check ownership before returning private data, for example that the order number matches the email.
- Return only the fields the agent needs.
- Return a non-2xx status for failures rather than an error message inside a success response.
- Make write operations safe to repeat where you can, because a timed-out request may still have completed.
Client event
When Client event is on, a successful server request dispatches a browser CustomEvent with the name you enter in Event name (letters, numbers, periods, colons, underscores, and hyphens; for example acme:order-found). Its detail contains actionKey, input, response, and status.
The event is dispatched on the chat widget's own window. The standard website embed loads the chat in a separate frame, and the loader doesn't currently pass this event on to your page, so confirm your setup receives it before you rely on it.
Website API request
Enter a same-origin path such as /api/orders or /api/orders/{order_id}. Hourzero builds the full path and query string from the inputs, using the same groups as server requests, and the embed loader sends the request from your page with credentials: "same-origin", so the browser includes the visitor's cookies, including HttpOnly cookies. Non-GET requests send the JSON body inputs as a JSON body, with Text list parameters as string arrays. Cookies are never sent to Hourzero. Redirects are rejected, custom headers aren't supported, requests time out after 15 seconds, and responses must stay under 60 KB. If your endpoint needs a CSRF token or custom headers, use a JavaScript handler instead.
Website JavaScript handler
Register a handler on your page whose name matches Handler name:
window.hourzero("registerTools", {
get_order: async (args, user) => {
const response = await fetch(
`/api/orders/${encodeURIComponent(args.order_number)}`,
);
if (!response.ok)
return { status: "error", error: "Unable to retrieve your order." };
return { status: "success", data: await response.json() };
},
});
Register after the embed script loads, or queue calls before it loads:
window.hourzero =
window.hourzero ||
function () {
(window.hourzero.q = window.hourzero.q || []).push(Array.from(arguments));
};
- Handlers must return
{ status: "success", data }or{ status: "error", error }, as JSON-compatible values under 60 KB. argscontains the configured parameters.usercontainsanon_user_id, which is not a verified identity. When your website signed the visitor in with identity verification,useralso hasuser_id,user_hash, anduser_metadata, as in Chatbase. Use your own session to authorize requests.- Results must arrive within about 18 seconds. A timed-out handler may still have completed, and Hourzero doesn't retry it.
- Results are stored in the conversation history, so return only what the conversation needs.
For website-defined forms, see Custom form.