Amplitude

The Foldspace SDK forwards agent lifecycle and interaction events to Amplitude when the Amplitude 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 Amplitude SDK must be loaded and accessible as window.amplitude. If it is not found, a warning is logged and no error is thrown.

Enable forwarding

Forward all events to Amplitude:

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

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

Forward specific events only:

agent.enableAnalyticsForwarding({
  providers: ["amplitude"],
  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 ["amplitude"] to forward to Amplitude 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 Mixpanel or Segment as well, add them to the providers array or see Mixpanel and Segment.