# 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**.

![Setting up a Look up order custom action](https://hourzero.dev/marketing/app/action-custom-light.webp "Acme's Look up order action: a name, when to use it, and the web address of Acme's order system.")

## 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.

1. **Customer asks**: "Where's my order 48213?"
2. **Agent calls**: Hourzero sends the order number to your system.
3. **System answers**: Your system replies with the order's status.
4. **Agent replies**: The 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](#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.

1. Open **Build → Actions** and select **Custom action**.
2. In **Action name**, enter `Look up order`.
3. In **When should the agent use it?**, enter:

   ```text
   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.
   ```

4. Leave **Execution** set to **Server API request**.
5. Under **API request**, set **Method** to **GET** and **Endpoint URL** to `https://api.acme.com/orders`.
6. Under **Headers**, select **Add custom header**. Enter `Authorization` as the **Header name** and the key from your developer, such as `Bearer acme-key-123`, as the **Header value**.
7. Under **Request inputs**, in **Query string**, select **Add query parameter**. Its settings open below it.
8. Fill in the parameter:
   - **Label:** `Order number` (the key `order_number` is 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**
9. Select **Add query parameter** again and add `Email` with **Value type** **Email**, the description `The email address the customer used to place the order.`, and **Requirement** **Required**.
10. Under **Response**, in **Response instructions**, enter:

    ```text
    Tell the customer the order status and expected delivery date.
    If no order is found, ask them to check the order number and email.
    ```

11. 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:

```json
{ "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](https://hourzero.dev/docs/ai-agent-management/widgets).

> [!TIP]
> Pair this action with a [Custom button](https://hourzero.dev/docs/ai-agent-management/actions/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](#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](https://hourzero.dev/docs/integrations/identity-verification#send-the-token-to-your-api).

### 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](#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](https://hourzero.dev/docs/integrations/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_number` or `orderNumber`. 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:

```text
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](#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](https://hourzero.dev/docs/ai-agent-management/widgets).

## Test your action

1. 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.
2. In the preview, ask "Where's my order?" without a number. The agent should ask for the order number and email.
3. Give a real test order, such as 48213, and its email. Check that the answer matches your system.
4. Try an order number that doesn't exist. The agent should say it couldn't find it, not make up a status.
5. Ask something unrelated, like "Do you sell gift cards?" The agent should answer without running the action.
6. 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.
7. 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](https://hourzero.dev/docs/integrations/chat-iframe#website-actions-and-website-forms) 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](https://hourzero.dev/docs/integrations/website-widget#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 `{}`. `GET` requests 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-Token` header. 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 `null` value on a **Nullable** input is sent as JSON `null` in a body and left out of a query string. Values such as `0` and `false` are kept.
- Default headers: `Accept: application/json, text/plain;q=0.9`, plus `Content-Type: application/json` for requests with a body. Custom headers can override these. Connection-level headers such as `Host` and `Content-Length` can'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**:

```js
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:

```js
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.
- `args` contains the configured parameters. `user` contains `anon_user_id`, which is not a verified identity. When your website signed the visitor in with [identity verification](https://hourzero.dev/docs/integrations/identity-verification), `user` also has `user_id`, `user_hash`, and `user_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](https://hourzero.dev/docs/ai-agent-management/actions/custom-form).

## Next steps

- [Custom button](https://hourzero.dev/docs/ai-agent-management/actions/custom-button): Send customers to a tracking page or portal after a lookup.
- [Widgets](https://hourzero.dev/docs/ai-agent-management/widgets): Show the result as a card, list, or form in your website chat.
- [Procedures](https://hourzero.dev/docs/ai-agent-management/procedures/overview): Use custom actions inside step-by-step flows.
- [Website widget](https://hourzero.dev/docs/integrations/website-widget): Embed the chat on your site, needed for website actions.
- [Actions overview](https://hourzero.dev/docs/ai-agent-management/actions/overview): Compare all actions and choose where each one runs.
