Create a chat session

Overview

Manages authentication and creates chat elements.

Examples

Basic usage

const session = whopElements.createChatSession({
  token: async () => {
    const response = await fetch("/api/token");
    const data = await response.json();
    return data.token;
  },
});

session.on("ready", () => {
  console.log("Session is ready");
});

Creating elements

const chatElement = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
});
chatElement.mount("#chat-container");

Options

Property	Type	Required	Default	Description
`token`	`Token \| GetToken`	Yes	-	The token to use for the session. If a function is provided, it will be called and awaited to get the token. When a function is provided, the token will be refreshed automatically before it expires. if a string is provided, it will be used as the token and not refreshed automatically. However you can update the token at runtime by calling ‘updateOptions’ with a new token.

Events

Events emitted by the ChatSession. Listen to these events using the on() method.

`optionsUpdated`

Emitted when the session options are updated via updateOptions(). Callback signature: (options: ExpandedChatSessionOptions) => void

`tokenRefreshed`

Emitted when the authentication token is refreshed. Callback signature: (token: string) => void

`tokenRefreshError`

Emitted when token refresh fails. Callback signature: (error: unknown) => void

`error`

Emitted when an error occurs during session operation. Callback signature: (error: unknown) => void

`ready`

Emitted when the session is ready and authenticated. Callback signature: (void) => void

Methods

`createElement(type, options)`

Create a new element instance.

Parameter	Type	Description
`type`	T \| { type: T; }	The element type (e.g., “chat-element”)
`options`	ChatSessionElements[T][0]	Element-specific configuration options

Returns: ChatSessionElements[T][1]

const element = session.createElement("chat-element", {
  channelId: "feed_XXXXXXXXXXXXXX",
  onReady: () => console.log("Element ready"),
});
element.mount("#chat-container");

`updateOptions(options)`

Update the session options after initialization. Changes will be propagated to all active elements.

Parameter	Type	Description
`options`	Partial<ChatSessionOptions>	Partial options object with the values to update

`destroy()`

Destroy the session and clean up all mounted elements. Call this when you no longer need the session to free up resources.

`showSearchModal(options, force)`

Show the search element in a modal overlay. By default, the modal auto-closes on completion (onResultClick) or dismiss (onClose). Call ev.preventDefault() in a callback to prevent auto-close.

Parameter	Type	Description
`options`	`SearchElementOptions` \| ((modal: ModalContainer) => `SearchElementOptions`)	Element options or a callback that receives the modal container
`force`	Force \| undefined	-

Returns: Force extends true ? ModalContainer : ModalContainer | undefined

​Overview

​Examples

​Basic usage

​Creating elements

​Options

​Events

​optionsUpdated

​tokenRefreshed

​tokenRefreshError

​error

​ready

​Methods

​createElement(type, options)

​updateOptions(options)

​destroy()

​Modal Methods

​showSearchModal(options, force)