@botpress/webchat

A fully customizable React library that lets you seamlessly integrate Botpress Webchat into your React applications.

Features

• 🎨 Fully Customizable - Style and configure every aspect of the webchat experience
• 🔌 Easy Integration - Simple installation and setup process
• 🛠️ Flexible Architecture - Use pre-built components or build custom implementations
• 📱 Responsive - Works seamlessly across desktop and mobile devices

Installation

# npm
npm install @botpress/webchat

# yarn
yarn add @botpress/webchat

# pnpm
pnpm install @botpress/webchat

Requirements

• React 18 or higher
• A published Botpress bot
• Your bot's Client ID

Quick Start

Get Your Client ID

1. Open your bot in the Botpress Dashboard
2. Navigate to Webchat in the left sidebar
3. Open the Features sub menu
4. Go to the Advanced Settings tab
5. Copy your Client ID

Basic Implementation

import { Fab, Webchat } from '@botpress/webchat'
import { useState } from 'react'

function App() {
  const [isWebchatOpen, setIsWebchatOpen] = useState(false)

  return (
    <>
      <Webchat
        clientId="YOUR_CLIENT_ID"
        style={{
          width: '400px',
          height: '600px',
          display: isWebchatOpen ? 'flex' : 'none',
          position: 'fixed',
          bottom: '90px',
          right: '20px',
        }}
      />
      <Fab
        onClick={() => setIsWebchatOpen(!isWebchatOpen)}
        style={{
          position: 'fixed',
          bottom: '20px',
          right: '20px',
          width: '64px',
          height: '64px',
        }}
      />
    </>
  )
}

Advanced Usage

Custom Webchat Implementation

For more control over the webchat experience, build it manually using individual components:

import { Container, Header, MessageList, Composer, useWebchat, Fab } from '@botpress/webchat'
import { useState, useMemo } from 'react'

function App() {
  const [isWebchatOpen, setIsWebchatOpen] = useState(false)
  const { client, messages, isTyping, user, clientState, newConversation } = useWebchat({
    clientId: 'YOUR_CLIENT_ID',
  })

  const config = {
    botName: 'SupportBot',
    botAvatar: 'https://example.com/avatar.png',
    botDescription: 'Your virtual assistant',
  }

  const enrichedMessages = useMemo(
    () =>
      messages.map((message) => {
        const direction = message.authorId === user?.userId ? 'outgoing' : 'incoming'
        return {
          ...message,
          direction,
          sender:
            direction === 'outgoing'
              ? { name: user?.name ?? 'You', avatar: user?.pictureUrl }
              : { name: config.botName, avatar: config.botAvatar },
        }
      }),
    [messages, user, config]
  )

  return (
    <>
      <Container
        connected={clientState !== 'disconnected'}
        style={{
          width: '500px',
          height: '800px',
          display: isWebchatOpen ? 'flex' : 'none',
          position: 'fixed',
          bottom: '90px',
          right: '20px',
        }}
      >
        <Header
          closeWindow={() => setIsWebchatOpen(false)}
          restartConversation={newConversation}
          configuration={{
            botName: config.botName,
            botAvatar: config.botAvatar,
            botDescription: config.botDescription,
          }}
        />
        <MessageList
          botName={config.botName}
          botDescription={config.botDescription}
          isTyping={isTyping}
          messages={enrichedMessages}
          sendMessage={client?.sendMessage}
        />
        <Composer
          connected={clientState !== 'disconnected'}
          sendMessage={client?.sendMessage}
          uploadFile={client?.uploadFile}
          composerPlaceholder="Type a message..."
        />
      </Container>
      <Fab
        onClick={() => setIsWebchatOpen(!isWebchatOpen)}
        style={{
          position: 'fixed',
          bottom: '20px',
          right: '20px',
        }}
      />
    </>
  )
}

Configuration

Using the Webchat Component

Pass configuration through the configuration prop:

<Webchat
  clientId="YOUR_CLIENT_ID"
  configuration={{
    botName: 'My Bot',
    botAvatar: 'https://example.com/avatar.png',
    botDescription: 'Here to help!',
  }}
/>

Custom Styling

Use the StylesheetProvider component for custom themes:

import { StylesheetProvider } from '@botpress/webchat'
;<StylesheetProvider />
{
  /* Your webchat components */
}

Components

• Webchat - All-in-one webchat component
• Container - Webchat container wrapper
• Header - Customizable header with bot info
• MessageList - Message display area
• Composer - Message input and file upload
• Fab - Floating action button
• StylesheetProvider - Custom styling provider
• useWebchat - Hook for webchat state and methods

Documentation

For detailed documentation, examples, and API reference, visit:

Botpress Webchat React Library Documentation

Support

• 📖 Documentation
• 💬 Discord Community

License

This library is part of the Botpress ecosystem. See the Botpress repository for license information.