# Segment

Forward agent events to Segment.

The Foldspace SDK forwards agent lifecycle and interaction events to [Segment](https://segment.com) when the Segment analytics.js library is already loaded on the page. Segment then fans those events out to every destination you have connected, so agent activity flows into 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 Segment analytics.js library must be loaded and accessible as `window.analytics`. If it is not found, a warning is logged and no error is thrown.

## Enable forwarding

Forward all events to Segment:

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

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

Forward specific events only:

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

Each event is sent with `analytics.track()`, named with the `foldspace.` prefix (e.g. `analytics.track("foldspace.conversation.created", { agentName })`).

## 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 `["segment"]` to forward to Segment 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 other providers as well, add them to the providers array or see [Amplitude](/reference/amplitude/) and [Mixpanel](/reference/mixpanel/).