> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Events emitted by the Reactor JavaScript SDK

## Event types

```typescript Definition theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
type ReactorEvent =
  | "statusChanged"
  | "sessionIdChanged"
  | "message"
  | "runtimeMessage"
  | "trackReceived"
  | "error"
  | "sessionExpirationChanged"
  | "capabilitiesReceived"
  | "statsUpdate";
```

Register handlers with `reactor.on(event, handler)` and remove them with `reactor.off(event, handler)`.

***

## `statusChanged`

Fired when the connection status changes.

**Payload:** `ReactorStatus`

```typescript Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("statusChanged", (status: ReactorStatus) => {
  console.log(status); // "connecting" | "waiting" | "ready" | "disconnected"
});
```

***

## `message`

Fired when the model sends an application-level message.

**Payload:** `any`. Shape depends on the model.

```typescript Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("message", (msg) => {
  if (msg.type === "state") {
    console.log(msg.data.current_frame);
  }
});
```

***

## `trackReceived`

Fired when a named media track is received from the model.

**Payload:** `(name: string, track: MediaStreamTrack, stream: MediaStream)`

| Argument | Type               | Description                          |
| -------- | ------------------ | ------------------------------------ |
| `name`   | `string`           | Track name as declared on the model  |
| `track`  | `MediaStreamTrack` | The raw media track                  |
| `stream` | `MediaStream`      | A `MediaStream` containing the track |

```typescript Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("trackReceived", (name, track, stream) => {
  videoElement.srcObject = stream;
});
```

<Note>
  For React apps, use `ReactorView` instead. It handles this event automatically.
</Note>

***

## `error`

Fired when an error occurs.

**Payload:** `ReactorError`

```typescript Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("error", (error: ReactorError) => {
  console.error(`[${error.component}] ${error.code}: ${error.message}`);
  if (error.recoverable) {
    reactor.reconnect();
  }
});
```

See [`ReactorError`](/sdk-reference/types#reactorerror) for all fields and error codes.

***

## `sessionIdChanged`

Fired when the session ID changes, typically on connect or disconnect.

**Payload:** `string | undefined`

***

## `sessionExpirationChanged`

Fired when the session expiration time is updated by the server.

**Payload:** `number | undefined`. Unix timestamp of expiration, or `undefined` if not set.

***

## `statsUpdate`

Fired every 2 seconds with WebRTC connection statistics while connected.

**Payload:** `ConnectionStats`

```typescript Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("statsUpdate", (stats) => {
  console.log(`RTT: ${stats.rtt}ms, FPS: ${stats.framesPerSecond}`);
});
```

See [`ConnectionStats`](/sdk-reference/types#connectionstats) for all fields.

***

## `capabilitiesReceived`

Fired when the model's capabilities are received after session creation. Contains track definitions, available commands, and other model metadata.

**Payload:** `Capabilities`

```typescript Example theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor.on("capabilitiesReceived", (capabilities) => {
  console.log("Tracks:", capabilities.tracks);
  console.log("Commands:", capabilities.commands);
});
```

See [`Capabilities`](/sdk-reference/types#capabilities) for the full type.

***

## `runtimeMessage`

Fired when the platform sends an internal runtime message. Used by `ReactorController` to receive the model's command schema. Not needed for most applications.

**Payload:** `any`