The useWebchat 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
useWebchat is the primary entry point for integrating the Webchat experience into custom UIs or applications.

​
Usage

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

function App() {
  const { client, clientState, on, user, conversationId, newConversation, messages, isFetchingMessages, isTyping } =
    useWebchat({
      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
BlockMessage[]
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.