# Mixpanel

Forward agent events to Mixpanel.

The Foldspace SDK forwards agent lifecycle and interaction events to Mixpanel when the Mixpanel SDK is already loaded on the page. Use it to see agent activity alongside the rest of your product analytics.

Forwarding is opt-in: no events are sent until you call `enableAnalyticsForwarding`. All forwarding is wrapped in try/catch and never blocks or fails the agent.

## Prerequisites

The Mixpanel SDK must be loaded and accessible as `window.mixpanel`. If it is not found, a warning is logged and no error is thrown.

## Enable forwarding

Forward all events to Mixpanel:

```javascript
const agent = foldspace.agent('YOUR-AGENT-KEY');

agent.enableAnalyticsForwarding({
  providers: ["mixpanel"]
});
```

Forward specific events only:

```javascript
agent.enableAnalyticsForwarding({
  providers: ["mixpanel"],
  events: ["agent.ready", "conversation.created", "action.called"]
});
```

## enableAnalyticsForwarding(config?)

Enables forwarding of agent events to analytics providers found on `window`.

**Parameters:**

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| config | `AnalyticsForwardingConfig \| null` | No | Provider and event selection. If omitted, all supported providers and all events are enabled by default. |

**AnalyticsForwardingConfig:**

| Field | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| providers | `("mixpanel" \| "amplitude" \| "segment")[]` | `["mixpanel", "amplitude", "segment"]` | Which analytics providers to forward events to. Set to `["mixpanel"]` to forward to Mixpanel only. The provider must be available on `window`. |
| events | `string[]` | All events | Which events to forward. If omitted, all supported events are forwarded. Invalid event names are silently skipped. |

**Returns:** The agent instance, enabling method chaining.

## Supported events

All forwarded events are prefixed with `foldspace.` (e.g. `foldspace.agent.ready`).

| Event | Description |
| :--- | :--- |
| `agent.ready` | Agent has initialized and is ready |
| `agent.removed` | Agent has been removed from the page |
| `agent.open` | Agent UI was opened |
| `agent.closed` | Agent UI was closed |
| `conversation.created` | A new conversation was started |
| `conversation.history` | An existing conversation was loaded |
| `action.called` | An action was executed |
| `action.response` | An action returned a response |

Every event payload is automatically enriched with `agentName`.

## Notes

- If called before the agent is ready, the call is queued and replayed once the agent initializes.
- Only the payload properties listed above are forwarded per event. No sensitive or unrelated data is sent.
- To forward to Amplitude or Segment as well, add them to the providers array or see [Amplitude](/reference/amplitude/) and [Segment](/reference/segment/).