Agent Event API

API

foldspace.agent("AGENT_NAME").on(event, handler);
foldspace.agent("AGENT_NAME").off(event, handler);

event: The event name (string) handler: A callback function that receives the event payload Both .on() and .off() return the agent instance (for chaining)

Available Events

Agent Lifecycle

Event	Payload	Description
`agent.ready`	`{}`	Fired when the agent is fully initialized and ready.
`agent.removed`	`{}`	Fired when the agent is removed from the page.

UI Lifecycle

Event	Payload	Description
`ui.open`	`{ rect: DOMRect }`	Fired when the chat UI is opened.
`ui.close`	`{ rect: DOMRect }`	Fired when the chat UI is closed.
`ui.show`	`{ rect: DOMRect }`	Fired when the agent becomes visible.
`ui.hide`	`{ rect: DOMRect }`	Fired when the agent is hidden.
`ui.move`	`{ rect: DOMRect }`	Fired when the agent is dragged to a new position.
`ui.resize`	`{ rect: DOMRect }`	Fired when the agent is resized.

Conversation Lifecycle

Event	Payload	Description
`conversation.created`	`{ conversationId: string }`	Fired when a new conversation is created.

Wildcards

You can listen to multiple events at once using wildcard patterns:

Pattern	Matches	Example
`*`	All events	`foldspace.agent("demo").on("*", handler)`
`ui.*`	All UI lifecycle events	`foldspace.agent("demo").on("ui.*", handler)`
`conversation.*`	All conversation-related events	`foldspace.agent("demo").on("conversation.*", handler)`

Example:

foldspace.agent("demo").on("ui.*", (payload) => {
  console.log("UI event triggered:", payload);
});

You can also use * to listen to all events:

foldspace.agent("demo").on("*", (payload, eventName) => {
  console.log(`Event "${eventName}" fired with:`, payload);
});

Removing Listeners

To remove a specific listener, use .off() with the same event name and handler:

const handler = (payload) => console.log("UI opened:", payload);

foldspace.agent("demo").on("ui.open", handler);

// Later...
foldspace.agent("demo").off("ui.open", handler);

If you used a wildcard (* or group.*), .off() will remove the same handler for all matching events.

Example

foldspace.agent("support")
  .on("agent.ready", () => console.log("Agent is ready"))
  .on("ui.open", ({ rect }) => console.log("Chat opened at:", rect))
  .on("conversation.created", ({ conversationId }) =>
    console.log("New conversation:", conversationId)
  );