# Custom tool events

With the event emitter you can give your AI agent the tools to interact with the website it's embedded on. Give it the ability to navigate to open popups, navigate to product details or even open your dedicated live chat.

## Create event tool

* In your project's **Tools** section, select **Create Tool**.
* Choose `build your own tool` 

<figure><img src="https://382411756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx5Kure6K0P0mTPmH9FQb%2Fuploads%2Fwmn0Oc3NDXq7oYkz3rNK%2FScreenshot%202025-09-08%20at%2014.21.44.png?alt=media&#x26;token=457bbc8c-45ce-4a36-8cd4-57871948ed3f" alt=""><figcaption></figcaption></figure>

### Tool setup

In this step, you’ll provide the core details of your tool:

* **Name**: A unique name (within the project). This name will also be used when the event is emitted, allowing you to identify which event was triggered.
* **Description**: A short explanation of the tool’s purpose.
* **When to Call Instructions**: Guidance for the agent on when it should call the tool, giving it the context needed to use the tool correctly.

<figure><img src="https://382411756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx5Kure6K0P0mTPmH9FQb%2Fuploads%2Fnn2JNXps24RRNztAy9hJ%2FScreenshot%202025-09-08%20at%2014.25.09.png?alt=media&#x26;token=12a50027-2caf-4d09-a7b2-4dcf3dee5ed5" alt=""><figcaption></figcaption></figure>

### Tool parameters

in the [parameters](https://developers.chathive.app/tools/parameters) section you can use JSON schema to define the data your agent should request from the user before emitting the event.

* If parameters are defined, the agent will prompt the user for that data.
* If left empty, no additional user input will be required.

All defined parameters will be included in the emitted event.

### Configure action

After setting up the tool and its parameters:

1. Select **Emit Event** as the action type.
2. Save your tool.

Your agent can now emit this custom event to your SDK.

<figure><img src="https://382411756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx5Kure6K0P0mTPmH9FQb%2Fuploads%2FzuilWHgrsJf30BW6j3Ob%2FScreenshot%202025-10-04%20at%2016.45.32.png?alt=media&#x26;token=72c36025-20e0-49ca-88d1-d78d14eccd82" alt=""><figcaption></figcaption></figure>

## Receive event

How you listen for events may vary slightly depending on whether you’re using the [chatbot](https://developers.chathive.app/sdk/chatbot/events) or  [AI from](https://developers.chathive.app/sdk/ai-form/events)  SDK, but the process is essentially the same.

Once the SDK is initialized, create a subscription to `tool.custom.event`.\
Each time the event is emitted, your callback function will receive the following data:

* **Name**: The unique tool name you defined.
* **Parameters**: All user-provided parameters plus system parameters.
* **Context**: The current conversation context.
* **Customer**: Customer information related to the conversation.
* **Project**: The associated project name.
* **Organization**: The associated organization name.
* **Conversation**: Conversation details, including messages and transcriptions.

```javascript
Chathive.widget.on("tool.custom.event", ({ name, parameters }) => {
    console.log("Event name:", name);
    console.log("Parameters:", parameters);
});
```