10.51.10 • Public • Published

    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.




    npm i @botpress/channel-web

    DownloadsWeekly Downloads






    Unpacked Size

    9.02 MB

    Total Files


    Last publish


    • laurentlp
    • samuelmasse
    • slvnperron
    • spgingras
    • franklevasseur