useWebchat

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:

Events	Description
conversation	Triggered when a new conversation is started.
message	Triggered when a new message is received.
messageSent	Triggered when a message is sent.
error	Triggered when an error occurs.
webchatVisibility	Triggered when the webchat visibility changes. (‘show’ or ‘hide’ or ‘toggle’)
webchatConfig	Triggered when the webchat configuration changes.
customEvent	Triggered when a custom event is received.
isTyping	Triggered 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.