# Events (for API)
### Overview
\
**Events** enable two-way communication between your embedded 3D project and your website through the Model API.
\
With Events, your website can:
* **Send data to the scene** — trigger interactions, update variables, control behavior
* **Receive data from the scene** — react to user actions, track state changes
Events are configured in Interactions (Interact mode):
* **Event listener** trigger — receives events from your website
* **Send event** action — sends events to your website
```
┌─────────────────────┐ ┌─────────────────────┐
│ │ │ │
│ Your Website │ dispatchEvent("name") │ Vectary Scene │
│ │ ──────────────────────────► │ │
│ │ Trigger: Event listener │ │
│ │ │ │
│ │ addEventListener("name") │ │
│ │ ◄────────────────────────── │ │
│ │ Action: Send event │ │
│ │ │ │
└─────────────────────┘ └─────────────────────┘
```
{% hint style="warning" %}
**Event names must be unique** — duplicate names are not allowed, even across different interaction types.
{% endhint %}
### How Events Carry Values
Events and [**Variables**](https://help.vectary.com/documentation/3d-configurator/variables-and-expressions) are connected by name. Understanding this link is essential:
Direction
How values work
Website → Scene
The value you send with dispatchEvent("name", value) is stored in a Variable called name
Scene → Website
The Send event action transmits the current value of a Variable with the same name
**Example:** If you have an event called `price` and a Variable called `price` with value `99`, when the scene sends this event, your website receives `99`.
If no Variable with a matching name exists, the event sends `undefined`.
### Receiving Events from the Scene
To send data from the scene to your website:
**1. In Studio (Interact mode):**
* Create a Variable (e.g., `selected_color` with value `"red"`)
* Create an Interaction:
* **Trigger:** On click → your object
* **Action:** Send event → `selected_color`\
**2. In your code:**
```javascript
api.addEventListener("selected_color", (value) => {
console.log(value); // "red"
});
```
The event fires when the trigger condition is met (e.g., user clicks the object).
### Sending Events to the Scene
To send data from your website to the scene:
**1. In Studio (Interact mode):**
* Create an Interaction:
* **Trigger:** Event listener → `width`
* **Action:** Whatever should happen (Transform, Set variable, Play animation, etc.)
**2. In your code:**
```javascript
api.dispatchEvent("width", 150);
```
The value `150` is automatically stored in a Variable called `width`, making it available in expressions.
### Debugger
The **Debugger** lets you test events directly in Studio without writing code. It simulates API calls from your website.
\
**To use the Debugger:**
1. Enter Preview mode
2. Open the **Debugger** tab (appears if at least one event exists)
3. Enter a value for any event
4. Click the radio button to dispatch it
\
The Debugger also displays all Variable values and updates in real-time — useful for verifying your Interactions work correctly.
### Embed code
Once you create an event, the **Share** popup automatically generates ready-to-use code.
The generated code includes:
* iframe embed with your project
* API initialization
* `addEventListener()` calls for events used in **Send event** actions
* `dispatchEvent()` calls for events used in **Event listener** triggers
```javascript
```
{% hint style="success" %}
To update the code, synchronize the project in Share popup
{% endhint %}
For further details, refer to the [Model API docs](https://help.vectary.com/api/model-api).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.vectary.com/documentation/3d-configurator/interactions/events-for-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
