Segment

The Foldspace SDK forwards agent lifecycle and interaction events to Segment 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:

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

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

Forward specific events only:

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 and Mixpanel.