Customer Agent Docs

Command Function

CustomerAgent(command, ...args)

The command function also exposes method properties such as CustomerAgent.boot(...) and named ESM exports such as boot(...).

Methods

Method	Signature	Returns	Effect
`boot`	`(options: CustomerAgentOptions)`	`CustomerAgentWidget`	Initializes the Messenger singleton.
`update`	`(options: Partial<CustomerAgentOptions>)`	`void`	Applies public option updates.
`identify`	`(user: WidgetUser)`	`void`	Updates visitor identity.
`setContext`	`(context: WidgetContextJson, options?: SetContextOptions)`	`void`	Merges or replaces user context.
`show`	`(target?: CustomerAgentTarget)`	`void`	Opens the Messenger target.
`hide`	`()`	`void`	Closes the Messenger.
`toggle`	`(target?: CustomerAgentTarget)`	`void`	Toggles Messenger visibility.
`openEntry`	`(entryId: string)`	`void`	Opens a conversation entry id.
`on`	`(eventName: CustomerAgentEventName, handler)`	`() => void`	Subscribes to an SDK event.
`getState`	`()`	`CustomerAgentState \| null`	Reads current singleton state.
`getSession`	`()`	`Promise<{ conversationId: string } \| null>`	Ensures the support session.
`getSupportState`	`()`	`CustomerAgentSupportState \| null`	Reads support session state.
`getInterviewState`	`()`	`CustomerAgentInterviewState \| null`	Reads interview state.
`getInterviewSession`	`()`	`CustomerAgentInterviewSession \| null`	Reads the active interview session.
`ensureInvitation`	`()`	`Promise<{ invitationId: string } \| null>`	Creates or returns an invitation id.
`startInvitation`	`(invitationId: string)`	`Promise<{ entryId: string; sessionId: string } \| null>`	Starts an interview session.
`chooseInvitation`	`(invitationId: string, choice: "close" \| "later")`	`Promise<void>`	Records an invitation choice.
`sendInterviewMessage`	`(content: string)`	`Promise<void>`	Sends an active interview message.
`loadInterviewReward`	`(sessionId?: string)`	`Promise<unknown>`	Loads interview reward data.
`shutdown`	`()`	`void`	Removes the Messenger singleton.

Method Details

boot

Initializes the Messenger singleton from CustomerAgentOptions and returns a CustomerAgentWidget controller for that instance. Calling boot again replaces the previous singleton.

Applies public option changes to the current singleton. The argument is Partial<CustomerAgentOptions>. context is accepted as an option field, but setContext is the dedicated context method. Updating mobile.mode recalculates the Messenger presentation; when an open non-mounted Messenger leaves fullscreen presentation, host page scrolling is restored.

identify

Updates visitor identity from a WidgetUser. Identity fields are also included in conversation context.

setContext

Updates WidgetContextJson. By default, plain object fields merge with existing context. Passing { merge: false } replaces the existing context object. Passing { ready } updates the context readiness flag.

show, hide, toggle, openEntry

show(target) opens the Messenger. hide() closes it. toggle(target) switches visibility and updates the target when one is provided. openEntry(entryId) opens a specific conversation entry. See Support and interview sessions for target shapes.

on

Subscribes a handler to a CustomerAgentEventName. The return value removes that handler. A widget.ready handler subscribed after readiness is emitted receives a replayed ready event.

getState

Returns the current CustomerAgentState, or null when no singleton exists.

getSession and getSupportState

getSession() ensures the support conversation session and resolves { conversationId }. getSupportState() reads the support state without starting a session. See Support state.

Interview methods

getInterviewState() reads interview availability/session state. getInterviewSession() returns the active interview session snapshot or null. ensureInvitation(), startInvitation(...), chooseInvitation(...), sendInterviewMessage(...), and loadInterviewReward(...) control the interview session surface. See Interview methods.

shutdown

Removes the current Messenger singleton.

Commands

Command	Arguments	Return
`"boot"`	`CustomerAgentOptions`	`CustomerAgentWidget`
`"update"`	`Partial<CustomerAgentOptions>`	`void`
`"identify"`	`WidgetUser`	`void`
`"setContext"`	`WidgetContextJson`, optional `SetContextOptions`	`void`
`"show"`	Optional `CustomerAgentTarget`	`void`
`"hide"`	None	`void`
`"toggle"`	Optional `CustomerAgentTarget`	`void`
`"openEntry"`	`string`	`void`
`"on"`	`CustomerAgentEventName`, handler	`() => void`
`"getState"`	None	`CustomerAgentState \| null`
`"getSession"`	None	`Promise<{ conversationId: string } \| null>`
`"getSupportState"`	None	`CustomerAgentSupportState \| null`
`"getInterviewState"`	None	`CustomerAgentInterviewState \| null`
`"getInterviewSession"`	None	`CustomerAgentInterviewSession \| null`
`"ensureInvitation"`	None	`Promise<{ invitationId: string } \| null>`
`"startInvitation"`	`string`	`Promise<{ entryId: string; sessionId: string } \| null>`
`"chooseInvitation"`	`string`, `"close" \| "later"`	`Promise<void>`
`"sendInterviewMessage"`	`string`	`Promise<void>`
`"loadInterviewReward"`	Optional `string`	`Promise<unknown>`
`"shutdown"`	None	`void`

CustomerAgentWidget

boot returns a controller for the current Messenger instance.

Top-level state reads return null when no singleton exists. Widget controller methods are typed as instance methods; reads that require an initialized singleton throw CustomerAgent widget is not initialized. if the controller cannot resolve one. getInterviewSession() can return null when the widget is initialized and no interview session is active.

Method	Signature	Effect
`chooseInvitation`	`(invitationId: string, choice: "close" \| "later") => Promise<void>`	Records an invitation choice.
`ensureInvitation`	`() => Promise<{ invitationId: string }>`	Creates or returns an invitation id.
`getInterviewState`	`() => CustomerAgentInterviewState`	Reads interview state.
`getInterviewSession`	`() => CustomerAgentInterviewSession \| null`	Reads active interview session.
`getSession`	`() => Promise<{ conversationId: string }>`	Resolves the support session.
`getState`	`() => CustomerAgentState`	Reads instance state.
`getSupportState`	`() => CustomerAgentSupportState`	Reads support state.
`hide`	`() => void`	Closes the Messenger.
`identify`	`(user: WidgetUser) => void`	Updates visitor identity.
`on`	`(eventName: CustomerAgentEventName, handler) => () => void`	Subscribes to an event.
`openEntry`	`(entryId: string) => void`	Opens a conversation entry id.
`loadInterviewReward`	`(sessionId?: string) => Promise<unknown>`	Loads interview reward data.
`sendInterviewMessage`	`(content: string) => Promise<void>`	Sends an active interview message.
`setContext`	`(context: WidgetContextJson, options?: SetContextOptions) => void`	Updates user context.
`show`	`(target?: CustomerAgentTarget) => void`	Opens the Messenger target.
`shutdown`	`() => void`	Removes the Messenger instance.
`startInvitation`	`(invitationId: string) => Promise<{ entryId: string; sessionId: string }>`	Starts an interview session.
`toggle`	`(target?: CustomerAgentTarget) => void`	Toggles Messenger visibility.
`update`	`(options: Partial<CustomerAgentOptions>) => void`	Applies public option updates.

CustomerAgentState

Field	Type	Meaning
`activeEntryId`	`string \| undefined`	Active conversation entry id.
`activeTarget`	`CustomerAgentTarget \| undefined`	Active Messenger target.
`appId`	`string`	Customer Agent app id.
`isOpen`	`boolean`	Messenger visibility.
`isReady`	`boolean`	Whether the Messenger can be opened.
`interview`	`CustomerAgentInterviewState`	Current interview state.
`launcher.targetConfigured`	`boolean`	Whether a launcher target was configured.
`launcher.targetConnected`	`boolean`	Whether the configured target is connected.
`support`	`CustomerAgentSupportState`	Current support state.
`widgetId`	`string`	Runtime instance id.

JavaScript SDK