Agent Event

Subscribe to agent lifecycle, UI, and conversation events directly from your app.

Subscribe to events

on(event, handler) / off(event, handler)

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

Parameter	Type	Description
event	string	The event name.
handler	function	Callback that receives the event payload.

Both .on() and .off() return the agent instance, so calls can be chained.

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.

Action callback lifecycle

Event	Payload	Description
action.callback	{ actionKey: string; status: "executed" | "rendered" | "failed" | "finished" | "clicked" | "cancelled" | "not_found"; payload?: any; }	Fired when an action callback is triggered or changes status.

Share data lifecycle

Event	Payload	Description
shareData.shareState	{ active: boolean }	Fired when the data sharing state is updated.
shareData.shareScreen	{ active: boolean }	Fired when the screen sharing state is updated.

Match events with wildcards

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)

Listen to a group of events.

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

Use * to listen to all events. The handler also receives the event name as a second argument.

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

Remove listeners

To remove a specific listener, call .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() removes the same handler for all matching events.

Chain listeners

Chain listeners across lifecycle, UI, and conversation events.

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)
  );

Related

• Messaging API: send messages to your agent.
• Conversation API: manage the conversations these events reference.