Web Widget API
API reference
@nlxai/chat-widget
Interfaces
Type Aliases
StorageType
Ƭ StorageType: "localStorage" | "sessionStorage"
When this option is set to "localStorage" or "sessionStorage",
the state of the chat conversation is persisted in local
or session storage respectively.
This allows the state and history of the conversation to persist between full page refreshes.
> When using the session storage feature, it is your responsibility > to make sure that your website complies with your data protection > and privacy policy requirements.
Defined in
packages/chat-widget/src/props.ts:45
CustomModalityComponent
Ƭ CustomModalityComponent: FC<{ key: string ; data: any }>
Custom Modalities allow rendering of rich components from nodes. See: https://docs.studio.nlx.ai/intentflows/documentation-flows/flows-build-mode/advanced-messaging-+-functionality#modalities
Defined in
packages/chat-widget/src/props.ts:51
Variables
defaultTheme
• Const defaultTheme: Theme
the default theme
Defined in
packages/chat-widget/src/ui/constants.ts:16
Functions
getCurrentExpirationTimestamp
▸ getCurrentExpirationTimestamp(responses): null | number
Get current expiration timestamp from the current list of reponses
Parameters
| Name | Type | Description |
|---|---|---|
responses | Response[] | the current list of user and bot responses (first argument in the subscribe callback) |
Returns
null | number
an expiration timestamp in Unix Epoch (new Date().getTime()), or null if this is not known (typically occurs if the bot has not responded yet)
Defined in
packages/chat-core/lib/index.d.ts:568
create
▸ create(props): WidgetInstance
Create a new chat widget and renders it as the last element in the body.
Parameters
| Name | Type |
|---|---|
props | Props |
Returns
the WidgetInstance to script widget behavior.
Defined in
packages/chat-widget/src/index.tsx:114
clearSession
▸ clearSession(storeIn): void
Clears stored session history.
Parameters
| Name | Type | Description |
|---|---|---|
storeIn | StorageType | where to clear the session. |
Returns
void
Defined in
packages/chat-widget/src/index.tsx:351
useConversationHandler
▸ useConversationHandler(): null | ConversationHandler
Hook to get the ConversationHandler for the widget. This may be called before the Widget has been created. It will return null until the Widget has been created and the conversation has been established.
Returns
null | ConversationHandler
the ConversationHandler if the widget has been created and its conversation has been established, otherwise it returns null.
Defined in
packages/chat-widget/src/index.tsx:474
Widget
▸ Widget(props): ReactNode
Parameters
| Name | Type |
|---|---|
props | Props & RefAttributes<WidgetRef> |
Returns
ReactNode
Defined in
packages/chat-widget/src/index.tsx:478
Interfaces
Interface: Nudge
When set, a dismissable call-to-action will appear above the chat icon with the given text.
By default, the call-to-action will be displayed after 3 seconds, and will automatically dismiss after 20 seconds.
It will be dissapear when the chat is opened, but until dismissed, will reappear whenever the chat is minimized or closed.
Properties
content
• content: string
The text content of the nudge. Markdown is supported.
Defined in
packages/chat-widget/src/props.ts:73
showAfter
• Optional showAfter: number
Show the nudge after a specific time, measured in milliseconds. Defaults to 3000 (3s) if not set.
Defined in
packages/chat-widget/src/props.ts:78
hideAfter
• Optional hideAfter: number
Hide the nudge after a specific time after it appears, measured in milliseconds. Defaults to 20000 (20s) if not set.
Defined in
packages/chat-widget/src/props.ts:83
Interface: Props
The properties for creating the Chat Widget.
Properties
config
• config: Config
The configuration to create a conversation.
Defined in
packages/chat-widget/src/props.ts:93
theme
• Optional theme: Partial<Theme>
The theme to apply to the chat widget.
Defined in
packages/chat-widget/src/props.ts:97
titleBar
• Optional titleBar: TitleBar
How to configure the title bar. When missing, the widget will not have a title bar.
Defined in
packages/chat-widget/src/props.ts:101
chatIcon
• Optional chatIcon: string
If you want a custom chat icon, set this to the URL of an image to use.
Defined in
packages/chat-widget/src/props.ts:105
nudge
• Optional nudge: Nudge
An optional Nudge configuration object.
Defined in
packages/chat-widget/src/props.ts:109
inputPlaceholder
• Optional inputPlaceholder: string
The placeholder in the input field. When not set, the default placeholder is "Type something..."
Defined in
packages/chat-widget/src/props.ts:113
loaderMessage
• Optional loaderMessage: string
A message to display to the user while the bot is still processing the previous message from the user.
Defined in
packages/chat-widget/src/props.ts:117
showLoaderMessageAfter
• Optional showLoaderMessageAfter: number
How long to wait, in milliseconds, before the loader message is displayed. Default is 2,500ms.
Defined in
packages/chat-widget/src/props.ts:121
allowChoiceReselection
• Optional allowChoiceReselection: boolean
If set to true, previously selected choices in the chat can be changed.
Defined in
packages/chat-widget/src/props.ts:125
storeIn
• Optional storeIn: StorageType
When set, chat history & conversation will be stored in the browser.
Defined in
packages/chat-widget/src/props.ts:129
onExpand
• Optional onExpand: (conversationHandler: ConversationHandler) => void
Optional callback to be called when the chat is expanded.
Type declaration
▸ (conversationHandler): void
Parameters
| Name | Type |
|---|---|
conversationHandler | ConversationHandler |
Returns
void
Defined in
packages/chat-widget/src/props.ts:133
onCollapse
• Optional onCollapse: (conversationHandler: ConversationHandler) => void
Optional callback to be called when the chat is collapsed. This is also called when the chat is closed.
Type declaration
▸ (conversationHandler): void
Parameters
| Name | Type |
|---|---|
conversationHandler | ConversationHandler |
Returns
void
Defined in
packages/chat-widget/src/props.ts:137
onClose
• Optional onClose: () => void
Optional callback to be called when the chat is closed via the close button.
Type declaration
▸ (): void
Returns
void
Defined in
packages/chat-widget/src/props.ts:141
onNudgeClose
• Optional onNudgeClose: (conversationHandler: ConversationHandler) => void
Optional callback to be called when the nudge element is closed explicitly by the user. It is not called when the nudge is hidden automatically after the hideAfter interval passes.
Type declaration
▸ (conversationHandler): void
Parameters
| Name | Type |
|---|---|
conversationHandler | ConversationHandler |
Returns
void
Defined in
packages/chat-widget/src/props.ts:145
customModalities
• Optional customModalities: Record<string, CustomModalityComponent>
Set this to render a CustomModalityComponent for a given modality name See: https://docs.studio.nlx.ai/intentflows/documentation-flows/flows-build-mode/advanced-messaging-+-functionality#modalities
Defined in
packages/chat-widget/src/props.ts:151
Interface: Theme
The theme to apply to the chat widget. Colors may be in any CSS-compatible format like rgb(50, 50, 50) or #aaa
Properties
primaryColor
• primaryColor: string
Primary color for interactive UI elements like buttons
Defined in
packages/chat-widget/src/theme.ts:7
darkMessageColor
• darkMessageColor: string
Background color for the dark chat bubbles (sent by the user)
Defined in
packages/chat-widget/src/theme.ts:9
lightMessageColor
• lightMessageColor: string
Background color for the light chat bubbles (sent by the bot)
Defined in
packages/chat-widget/src/theme.ts:11
white
• white: string
Customized shade of white
Defined in
packages/chat-widget/src/theme.ts:13
fontFamily
• fontFamily: string
Widget font family
Defined in
packages/chat-widget/src/theme.ts:15
spacing
• spacing: number
Main spacing unit
Defined in
packages/chat-widget/src/theme.ts:17
borderRadius
• borderRadius: number
Chat border radius
Defined in
packages/chat-widget/src/theme.ts:19
chatWindowMaxHeight
• chatWindowMaxHeight: number
Max height of the chat window
Defined in
packages/chat-widget/src/theme.ts:21
Interface: TitleBar
Configures the Title Bar of the Chat Widget. This is visible at the top of the widget when it is open / expanded.
Properties
logo
• Optional logo: string
Optional URL to a logo image to be displayed on to the left of the title.
Defined in
packages/chat-widget/src/props.ts:13
title
• title: string
The title string.
Defined in
packages/chat-widget/src/props.ts:17
withCollapseButton
• Optional withCollapseButton: boolean
Setting this to true shows the collapse button ("_"). Pressing the collapse button will hide the chat overlay but keep it active.
Defined in
packages/chat-widget/src/props.ts:22
withCloseButton
• Optional withCloseButton: boolean
Setting this to true shows the close button ("X"). Pressing the close button will
- hide the chat overlay
- terminate the ongoing conversation
- call the chat's onClose handler if provided.
Defined in
packages/chat-widget/src/props.ts:30
Interface: WidgetInstance
A handler for a Widget. Created with create
Properties
teardown
• teardown: () => void
End the conversation, clean up all event handlers, and remove the widget from the DOM. If you want to additionally clear a stored session, explicitly call clearSession with your Props.
Type declaration
▸ (): void
Returns
void
Defined in
packages/chat-widget/src/index.tsx:74
expand
• expand: () => void
Expand the widget and call the onExpand callback if present.
Type declaration
▸ (): void
Returns
void
Defined in
packages/chat-widget/src/index.tsx:78
collapse
• collapse: () => void
Collapse the widget and call the onCollapse callback if present.
Type declaration
▸ (): void
Returns
void
Defined in
packages/chat-widget/src/index.tsx:82
getConversationHandler
• getConversationHandler: () => undefined | ConversationHandler
Get the ConversationHandler for widget. Returns undefined if the widget has not yet been established.
Note that this might not be available synchronously after widget initialization, and therefore an undefined check is highly recommended before use.
See: https://developers.nlx.ai/headless-api-reference#interfacesconversationhandlermd
Type declaration
▸ (): undefined | ConversationHandler
Returns
undefined | ConversationHandler
Defined in
packages/chat-widget/src/index.tsx:88
Interface: WidgetRef
Widget Ref, for use when rendering a Widget without using the create helper function.
Properties
expand
• expand: () => void
Expand the widget and call the onExpand callback if present.
Type declaration
▸ (): void
Returns
void
Defined in
packages/chat-widget/src/index.tsx:98
collapse
• collapse: () => void
Collapse the widget and call the onCollapse callback if present.
Type declaration
▸ (): void
Returns
void
Defined in
packages/chat-widget/src/index.tsx:102
conversationHandler
• conversationHandler: ConversationHandler
the ConversationHandler for the widget.
Defined in
- Previous
- Web widget: Try live