An embeddable web chat for Botpress bots


181110.51.103 years ago4 years agoMinified + gzip package size for @botpress/channel-web in KB


Botpress Webchat

This channel is a customizable web chat that can be:

  • Embedded on any website
  • Used as a Standalone full-screen chat


yarn add @botpress/channel-web

Supported messages (Work in progress)

⭐ See the full list of supported messages



'#text': data => [
      on: 'webchat',
      typing: true,
      text: data.text,
      markdown: true

typing (optional)

Can be true to use natural typing speed (based on characters length) or can also be a natural time string (parsed by ms module).

markdown (optional)

Can be true to render the text as markdown format. This allows you to include links, bold and italic text.

web-style (optional)

web-style (optional) will pass the arguments as DOM style properties. This allows you to customize how specific messages look.

web-style: {
  color: "rgb(24, 1, 187)",
  borderLeft: "2px solid rgb(11, 8, 162)",
  padding: "10px",
  fontWeight: "600",
  fontSize: "20px",
  fontFamily: "'Lato', sans-serif" }

quick_replies (optional)

Array of string, with the <PAYLOAD> Text format.

quick_replies: data.choices.map(choice => `<${choice.payload}> ${choice.text}`)
'#form': data => [
    on: 'webchat',
    typing: true,
    markdown: true,
    text: data.text,
    form: {
      title: 'Survey',
      id: 'survey',
      elements: [
          input: {
            label: 'Email',
            placeholder: 'Your email',
            name: 'email',
            subtype: 'email',
            required: true
          textarea: {
            label: 'Text',
            placeholder: 'Your text',
            name: 'text',
            maxlength: 100,
            minlength: 2

It's look's like a usually web form. After submitted, you can handle this event with botpress.hear method. For example:

bp.hear({ type: 'form', formId: 'survey' }, (event, next) => {
  // Your code

You can always catch formId in the hear function, because Id is not an option in the form element. You choose a value to go with your id keys.

'#welcome': data => [
    on: 'webchat',
    text: 'Welcome',
    typing: '250ms',
    form: {
      title: 'welcome',
      id: 'welcome',
      /* ... */

'#form-email': data => [
    on: 'webchat',
    text: 'Provide me your email',
    form: {
      title: 'Email',
      id: 'email',
      /* ... */

in your bp.hear function

bp.hear({type:'form',formId:'welcome'},(event,next))=> {} // welcome content
bp.hear({type:'form',formId:'email'},(event,next))=> {} // form-email content
Form Elements


Has next attributes: label, name, placeholder, subtype, required, maxlength, minlength, which works like a same attributes in html5 (subtype is a same as type in html5)


Has a same attributes like input, but has no subtype attribute


Has a same attributes like textarea, but has no maxlength and minlength attributes, and has options attribute, which contain an option elements.


  select: {
    label: 'Select one item',
    name: 'select',
    placeholder: 'Select one option',
    options: [
        option: {
          label: 'Hindu (Indian) vegetarian',
          value: 'hindu'
        option: {
          label: 'Strict vegan',
          value: 'vegan'
        option: {
          label: 'Kosher',
          value: 'kosher'
        option: {
          label: 'Just put it in a burrito',
          value: 'burrito'

elements (required)

Array of element objects

element.title (required)


element.picture (optional)

String (URL)

element.subtitle (optional)


element.buttons (optional)

Object | { url: 'string', title: 'string', text: 'string', payload: 'string' } When provided with payload instead of url, acts similarly to quick replies.

settings (optional)

Settings to pass the react-slick component

Using it as Standalone (full-screen)

In your index.js file, add this:

const config = {
  botName: '<<REPLACE>>',
  botAvatarUrl: '<<REPLACE BY URL>>',
  botConvoTitle: '<<REPLACE>>',
  botConvoDescription: '<<REPLACE>>',
  backgroundColor: '#ffffff',
  textColorOnBackground: '#666666',
  foregroundColor: '#000000',
  textColorOnForeground: '#ffffff',
  showUserName: false,
  showUserAvatar: false,
  enableTranscriptDownload: false

bp.createShortlink('chat', '/lite', {
  m: 'channel-web',
  v: 'fullscreen',
  options: JSON.stringify({ config: config })

Now your bot is available at the following url: <BOT_URL>/s/chat, e.g. http://localhost:3000/s/chat.

This URL is public (no authentication required) so you can share it we other people.

Using it as Embedded (on website)

To embedded the web interface to a website, you simply need to add this script at the end of the <body> tag. Don't forget to set the host correctly to match the public hostname of your bot.

<script src="<host>/api/botpress-platform-webchat/inject.js"></script>
<script>window.botpressWebChat.init({ host: '<host>' })</script>

Customize the look and feel

You can customize look and feel of the web chat by passing additional keys to init method like this:

  host: '<host>',
  botName: 'Bot', // Name of your bot
  botAvatarUrl: null, // Default avatar url of the image (e.g. 'https://avatars3.githubusercontent.com/u/1315508?v=4&s=400' )
  botConvoTitle: 'Technical Support', // Title of the first conversation with the bot
  botConvoDescription: '',
  backgroundColor: '#ffffff', // Color of the background
  textColorOnBackground: '#666666', // Color of the text on the background
  foregroundColor: '#0176ff', // Element background color (header, composer, button..)
  textColorOnForeground: '#ffffff', // Element text color (header, composer, button..)
  showUserName: false, // Whether or not to show the user's name
  showUserAvatar: false, // Whether or not to show the user's avatar
  enableTranscriptDownload: false, // Whether or not to show the transcript download button
  customStylesheet: '', // Url to custom .css file
  greetingScreen: {
    type: 'blank_chat', // If you want to see "Get started" button you need to change it to 'get_started'
    options: {
      buttonTitle: 'Get Started',
      message: ''
  filterQuickReplies: false // If you have a lot of quick replies, you can apply a search filter on them

You can also use window.botpressWebChat.configure method to modify web chat options after it's initialized.

Custom stylesheet example

Style for silver background

.botpress__side-internal {
  background-color: rgb(255, 255, 255);
  border: 1px solid rgba(0, 0, 0, .3);

.botpress__side-external .botpress__side-internal .botpress__side-header {
  border-bottom: 2px solid #fff;

.botpress__side-internal .botpress__side-header .botpress__toggle-convos-button i,
.botpress__side-internal .botpress__side-header .botpress__close-button i {
  color: #fff;

.botpress__convos-list {
  background-color: rgba(0, 0, 0, .3);

.botpress__side-external .botpress__side-internal .botpress__side-conversation .botpress__side-conversation-bottom .botpress__side-new-message {
  background-color: transparent;

.botpress__side-external .botpress__side-item-right .botpress__side-item-title .botpress__side-item-date span,
.botpress__side-external .botpress__side-internal .botpress__convos-list .botpress__convo-item .botpress__side-item-right .botpress__side-item-text {
  color: #000;

.botpress__side-external .botpress__side-internal .botpress__convos-list .botpress__convo-item:hover {
  background-color: rgba(0, 0, 0, .35);

Page –> Bot interactions

You can open/close sidebar programmatically by calling window.botpressWebChat.sendEvent with { type: 'show' } or { type: 'hide' }.

Modify url

You can add ref query parameter to url(example bot/s/chat?ref=[content]) and content will be available within events as event.raw.data.webchatUrlQuery.

Configuring file uploads

A configuration file has been created in the config directory of your bot when you installed the module. You can change these values to set up S3 integration.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.