# JavaScript SDK (/docs/sdk/methods) ## Command Function [#command-function] ```ts CustomerAgent(command, ...args) ``` The command function also exposes method properties such as `CustomerAgent.boot(...)` and named ESM exports such as `boot(...)`. ## Methods [#methods] | Method | Signature | Returns | Effect | | ---------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------- | | `boot` | `(options: CustomerAgentOptions)` | `CustomerAgentWidget` | Initializes the Messenger singleton. | | `update` | `(options: Partial)` | `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. | | `startInterview` | `()` | `Promise<{ entryId: string; sessionId: string } \| null>` | Opens and starts an eligible interview. | | `startInvitation` | `(invitationId: string)` | `Promise<{ entryId: string; sessionId: string } \| null>` | Starts an interview session. | | `chooseInvitation` | `(invitationId: string, choice: CustomerAgentInterviewInvitationChoice)` | `Promise` | Records an invitation choice. | | `sendInterviewMessage` | `(content: string)` | `Promise` | Sends an active interview message. | | `loadInterviewReward` | `(sessionId?: string)` | `Promise` | Loads interview reward data. | | `shutdown` | `()` | `void` | Removes the Messenger singleton. | ## Method Details [#method-details] ### boot [#boot] Initializes the Messenger singleton from `CustomerAgentOptions` and returns a `CustomerAgentWidget` controller for that instance. Calling `boot` again replaces the previous singleton. ### update [#update] Applies public option changes to the current singleton. The argument is `Partial`. `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 [#identify] Updates visitor identity from a `WidgetUser`. Identity fields are also included in conversation context. ### setContext [#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-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](/docs/sdk/sessions#customeragenttarget) for target shapes. ### on [#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 [#getstate] Returns the current `CustomerAgentState`, or `null` when no singleton exists. ### getSession and getSupportState [#getsession-and-getsupportstate] `getSession()` ensures the support conversation session and resolves `{ conversationId }`. `getSupportState()` reads the support state without starting a session. See [Support state](/docs/sdk/sessions#support-state). ### Interview methods [#interview-methods] `getInterviewState()` reads interview availability/session state. `getInterviewSession()` returns the active interview session snapshot or `null`. `ensureInvitation()`, `startInterview()`, `startInvitation(...)`, `chooseInvitation(...)`, `sendInterviewMessage(...)`, and `loadInterviewReward(...)` control the interview session surface. See [Interview methods](/docs/sdk/sessions#interview-methods). ### shutdown [#shutdown] Removes the current Messenger singleton. ## Commands [#commands] | Command | Arguments | Return | | ------------------------ | -------------------------------------------------- | --------------------------------------------------------- | | `"boot"` | `CustomerAgentOptions` | `CustomerAgentWidget` | | `"update"` | `Partial` | `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>` | | `"startInterview"` | None | `Promise<{ entryId: string; sessionId: string } \| null>` | | `"startInvitation"` | `string` | `Promise<{ entryId: string; sessionId: string } \| null>` | | `"chooseInvitation"` | `string`, `CustomerAgentInterviewInvitationChoice` | `Promise` | | `"sendInterviewMessage"` | `string` | `Promise` | | `"loadInterviewReward"` | Optional `string` | `Promise` | | `"shutdown"` | None | `void` | ## CustomerAgentWidget [#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: CustomerAgentInterviewInvitationChoice) => Promise` | 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` | Loads interview reward data. | | `sendInterviewMessage` | `(content: string) => Promise` | 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. | | `startInterview` | `() => Promise<{ entryId: string; sessionId: string }>` | Opens and starts an eligible interview. | | `startInvitation` | `(invitationId: string) => Promise<{ entryId: string; sessionId: string }>` | Starts an interview session. | | `toggle` | `(target?: CustomerAgentTarget) => void` | Toggles Messenger visibility. | | `update` | `(options: Partial) => void` | Applies public option updates. | ## CustomerAgentState [#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. |