The useWebchatClient hook provides access to the Botpress Webchat integration instance and related state. It allows you to:

  • Interact with the bot
  • Listen to real-time events
  • Manage conversation lifecycle, user info, and messages

useWebchatClient is the primary entry point for integrating the Webchat experience into custom UIs or applications.

​
Usage

App.tsx
import { useWebchatClient } from '@botpress/webchat'

function App() {
  const { client, clientState, on, user, conversationId, newConversation, messages, isFetchingMessages, isTyping } =
    useWebchatClient({
      clientId: '$CLIENT_ID$', // Insert your Client ID here
    })
}

​
Parameters

​
clientId
string

Your Botpress project Client ID. Required to initialize the client and establish communication with the backend.

​
Returned Values

​
client
WebchatClient

The underlying client instance. Can be used to manually send events, fetch data, or interact with the backend.

​
clientState
'connecting' | 'connected' | 'error' | 'disconnected'

Represents the current connection state of the client.

​
on
(event: string, callback: Function) => void

Allows you to listen to client events such as incoming messages, typing indicators, or custom events. Here are the native Webchat events that you can listen to:

EventsDescription
conversationTriggered when a new conversation is started.
messageTriggered when a new message is received.
messageSentTriggered when a message is sent.
errorTriggered when an error occurs.
webchatVisibilityTriggered when the webchat visibility changes. (‘show’ or ‘hide’ or ‘toggle’)
webchatConfigTriggered when the webchat configuration changes.
customEventTriggered when a custom event is received.
isTypingTriggered when the bot is typing.
​
user
User

The current user’s profile object:

const user:
  | {
      name?: string
      pictureUrl?: string
      data?: {
        [k: string]: any
      }
      id: string
      createdAt: string
      updatedAt: string
    }
  | undefined
​
conversationId
string

The active conversation’s unique identifier.

​
newConversation
() => void

A function to start a new conversation. Resets the current chat session.

​
messages
WebchatMessage[]

An array of messages for the active conversation. Includes user and bot messages.

​
isFetchingMessages
boolean

Indicates whether messages are currently being fetched from the backend.

​
isTyping
boolean

Reflects whether the bot is currently “typing,” as indicated by typing events from the backend.

Was this page helpful?

Suggest editsRaise issue