hbf-webchat

v3.35.4

Published

4 months ago

This is the JS library for the webchat that Helvia uses on the Bots

Downloads

0High
0Medium
0Low

helvia

chatbot

HBF Webchat Library

About the Project

The HBF Webchat Library is the library that gets shared between all the Webchat Widgets that are used on Helvia's bots. Bellow we will describe the general Architecture of the project, the requirements and how to run it locally so that you can develop on it.

HBF Webchat Library enhances the OpenSource library of Microsoft's Bot Framework Webchat as CDN.

Branch v0 uses v3.0 of Microsoft's Webchat. Master and Develop branches use v4.0 of Microsoft's Webchat.

Built With

Installation

Guide

Assuming that you have already created your Tenant and the corresponding Deployment for the Webchat, in order to create your Webchat Widget you should add the following lines in the <Body> of your HTML page.

<script src="https://cdn.helvia.io/hbf-webchat/lib/latest/webchat.min.js"></script>
<script>
  window.HBFWebchat.init({
    deploymentId: "<GENERATED_UUID>", // It is the tenant's id
    apiUrl: "<HBF-CORE-URL_TO_REQUEST_FOR_TOKEN>", // Based on the Environment
    // ...MORE OPTIONS
  }, () => {
    // Here you can add your code to run after the webchat gets initialized properly
  });
</script>

Note

Keep in mind that in the above example we used the latest version of the library. We recommend using a specific version of the HBF Webchat Library that you want, e.g. https://cdn.helvia.io/hbf-webchat/lib/1.0.0/webchat.min.js

Available Options

If you have used a version:

'< 1.11.0' please check out the available options in the link: https://github.com/Helvia/hbf-webchat/blob/v<VERSION>/src/default-properties.js, after you replace the <VERSION> with the version of the Library you used. E.g. https://github.com/Helvia/hbf-webchat/blob/v1.0.0/src/default-properties.js
'>= 1.11.0' please check out the available options in the link: https://github.com/Helvia/hbf-webchat/blob/v<VERSION>/src/interfaces/botProperties.ts, after you replace the <VERSION> with the version of the Library you used. E.g. https://github.com/Helvia/hbf-webchat/blob/v1.11.0/src/interfaces/botProperties.ts
'latest' as the version on CDN link, then you check here the options.

Greeting Messages

Webchat is able to send different greeting messages based on the time that has passed from the last interaction of the User with the bot. The developer has to define the list of greeting messages to the property greetingMessages. A greeting message contains 3 properties,

quicκ (IActivity[]): A list of message activities that are sent quickly from the front end (can be only text or suggested actions)
conversationNodeId (string): The Conversation Node Id to be passed back to HBF-bot so that a specific Node gets triggered
triggerWhenInactiveFor (number): The time in SECONDS that MUST pass from the last User interaction with the bot, so that the greeting message gets triggered.

In order for a greeting message to be correctly defined, the developer must define either the quick property or the conversationNodeId or both. The triggerWhenInactiveFor is required for all the messages if the number of the messages is greater than 1, and it can be omitted if there is only one greeting message defined.

The logic behind the decision of which greeting message is going to be sent is simple. The greeting message that has triggerWhenInactiveFor less than the time that has passed since the last User interaction, BUT it is closest to it compared to the others, will get triggered.

Example:

The User chats with the bot and leaves the page. After N seconds she reloads the page with the webchat, in order to chat with the bot again. The greetings for the bot on the webchat are defined bellow. The results will be shown right after the snippet.

{
  "greetingMessages": [
    { //Message 1
      "conversationNodeId": "welcome-back-in-10-seconds-node",
      "triggerWhenInactiveFor": 10
    },
    { //Message 2
      "quick": [
        {
          "type": "message",
          "text": "Welcome back. It's been an hour since we talked! :)"
        },
        {
          "type": "message",
          "text": "How can I help you?"
        }
      ],
      "triggerWhenInactiveFor": 3600
    },
    { //Message 3
      "quick": [
        {
          "type": "message",
          "text": "Hi! I am a color bot."
        },
        {
          "type": "message",
          "text": "Please choose one color of the options bellow.",
          "suggestedActions": {
            "actions": [
              {
                "type": "imBack",
                "title": "Blue",
                "value": "Blue"
              },
              {
                "type": "imBack",
                "title": "Red",
                "value": "Red"
              },
              {
                "type": "imBack",
                "title": "Green",
                "value": "Green"
              }
            ]
          }
        }
      ],
      "conversationNodeId": "intro-node",
      "triggerWhenInactiveFor": 86400
    }
  ]
}

Based on the list of greetingMessages above, there are the following cases for the N factor:

{ 0 < N < 10 }: No Message will be sent
{ 10 < N < 3600 }: Message 1 will be sent
{ 3600 < N < 86400 }: Message 2 will be sent
{ 86400 < N}: Message 3 will be sent

Reminder Messages

Using the same schema as with greetingMessages but for the idleReminderMessages property, we can have reminder messages for when the user has been idle for a specific time period. These reminders can be either a jump to a conversation node, plain text or suggested actions. Keep in mind that these reminders are not taken into account when the user is in a live-chat conversation.

Example:

The User chats with the bot for a while (or doesn't interact at all) and then they go idle. After the specified amount of time the bot will start sending reminder messages

{
  "idleReminderMessages": [
    { //Message 1
      "conversationNodeId": "idle-node",
      "triggerWhenInactiveFor": 500
    },
    { //Message 2
      "quick": [
        {
          "type": "message",
          "text": "It's been an hour since we talked, are you still there?"
        }
      ],
      "triggerWhenInactiveFor": 3600
    },
    { //Message 3
      "quick": [
        {
          "type": "message",
          "text": "Are you still there?",
          "suggestedActions": {
            "actions": [
              {
                "type": "imBack",
                "title": "Yes",
                "value": "Yes"
              },
              {
                "type": "imBack",
                "title": "No",
                "value": "No"
              }
            ]
          }
        }
      ],
      "triggerWhenInactiveFor": 1800
    }
  ]
}

Message History

Using the messageHistory object property, we can enable a message history for the chat (stored in local storage) while also setting specific limits for it. The properties we can use are enabled, sendGreetingMessage, maxNumberOfMessages and maxNumberOfSessions. The enabled property must be set to true for the feature to work. sendGreetingMessage is another boolean field, if set to true the intro message will be resent when the webchat is reloaded. The maxNumberOfSessions and maxNumberOfMessages properties are limits to how many sessions should be stored in history and the maximum number of messages to keep track of, respectively. Keep in mind that setting maxNumberOfSessions to 0 means storing all of the sessions, and setting maxNumberOfMessages to 0 is like disabling the feature.

Example:

The following configuration enables the message history feature to save up to 15 messages and 1 session, without sending the greeting message again on reload.

{
	"messageHistory": {
		"enabled": true,
		"sendGreetingMessage": false,
		"maxNumberOfMessages": 15,
		"maxNumberOfSessions": 1
	}
}

Custom Data Functions

If the developer of the WebPage wants to pass user specific data for the bot or other metadata there are some functions that (s)he can create in the WebPage and the WebChat will invoke them during the initialization. Those are the HBF_retrieveUserId, HBF_retrieveUserInfo and HBF_retrieveMetadata.

window.HBF_retrieveUserId

If the WebPage that the hosts the WebChat has logged-in users, and its user has a specific identifier, it is suggested to use this function to pass the identifier so that the WebChat can keep the same subscriber even if the users gets logged in with different PCs or browsers.
The function can be asynchronous
⚠️ The identifier must be unique per user

    /**
     * @returns { Promise<string | undefined> }
     */
    window.HBF_retrieveUserId = function() {
        return "unique-logged-in-user-identifier";
    }

window.HBF_retrieveUserInfo

Sets the name, email, language and any custom data if needed for the user and sends them to the Bot Backend. Custom data may be anything related to the user that might be useful for analytics or business logic, e.g. phone number, preferences, etc
The function can be asynchronous, and it should return a specific schema as shown below.

    /**
     * @returns { Promise<{ 
     *      email?: string; 
     *      name?: string; 
     *      firstName?: string; 
     *      lastName?: string; 
     *      language?: string;
     *      customData?: { [x: string]: string | boolean | number }; 
     *  }> }
     */
    window.HBF_retrieveUserInfo = function() {
        return {
            name: "John Doe",
            email: "[email protected]",
            language: "zh-yue",
            customData: {
                "key1": "value1",
                "key3": false,
                "key5": 123,
            }
        }
    }

window.HBF_retrieveMetadata

Passes custom JSON data to the Bot Backend that might be useful for analytics or business logic and that are not connected directly with the user. e.g. Page domain, browser, mobile device, etc.
The function can be asynchronous

    /**
     * @returns { [x: string]: unknown }
     */
    window.HBF_retrieveMetadata = function() {
        return {
            key1: string, 
            key2: {
                key4: string
            }, 
            key5: number, 
            key3: boolean
        }
    }

Multiple Instances in the same Webpage

It is possible to have multiple webchats in a webpage. The only restriction is that only one of them may be in Bubble Mode. In order to do that for each bot we should define the botDivId inside the options and this value should target a specific <div> in the webpage. The relation should be 1-1, 1 Div per 1 bot.

Exposed Functions from window.HBFWebchat

HBFWebchat.getTranscript(options)

If the WebChat installation has enabled the configuration keepTranscript: true, then the transcript of the chat will be available to be fetched from the Library with this function. The return value is a list of the Transcript Items as shown in file transcriptItem.ts.

The name and the email properties are optional.

Example:

[
    {
        "text": "How may I help you?",
        "from": {
            "role": "bot"
        },
        "timestamp": "2023-10-20T10:56:30.1397392Z"
    },
    {
        "text": "Open Google in a new window!",
        "from": {
            "name": "John Doe",
            "email": "[email protected]",
            "role": "user"
        },
        "timestamp": "2023-10-20T10:56:36.452Z"
    },
    {
        "text": "Here you go!",
        "from": {
            "role": "bot"
        },
        "timestamp": "2023-10-20T10:56:39.705138Z"
    },
    {
        "text": "Thank you!",
        "from": {
            "name": "John Doe",
            "email": "[email protected]",
            "role": "user"
        },
        "timestamp": "2023-10-20T10:56:41.112Z"
    }
]

Other Features

Go to a webpage that has the Webchat Widget in Bubble mode with the parameter hws=on in the URL, the page will load with the Widget open, but you will be able to close it again. Add the parameter hws=alwayson in the URL and the webchat will load open, and will hide the x icon in the header.
Go to a webpage that has the Webchat Widget with the parameter
- hcn=<CONVERSATION_NODE_ID> in the URL, when the webchat will open it will start on the specified Conversation Node
- hin=<INTENT_NAME> in the URL, when the webchat will open it will start triggering the specified Intent
Go to a webpage that has the Webchat Widget with the parameter hsh=<UNIQUE_SUBSCRIBER_ID> in the URL, when the webchat starts it will continue the conversation for the subscriber with handle UNIQUE_SUBSCRIBER_ID
Inside a WebPage that features a Webchat, the Developers of the WebPage can add one or more buttons
- with the class btn-hcn and data data-hcn="<CONVERSATION_NODE_ID>" data-target-div="<ID_OF_BOT_DIV>" and then, when those buttons get clicked the webchat will begin from the specified Conversation Node. Developers can also add data-hcn-title="<FRIENDLY_TEXT>" to the data which will be used to describe the action triggered when the button is clicked e.g. Request live chat
- with the class btn-hin and data data-hin="<INTENT_NAME>" data-target-div="<ID_OF_BOT_DIV>" and then, when those buttons get clicked the webchat will start by triggering the specified Intent. Developers can also add data-hin-title="<FRIENDLY_TEXT>" to the data which will be used to describe the action triggered when the button is clicked e.g. Request live chat

Getting Started

Prerequisites

The only requirement is that you must have installed Node v16 (tested with v16) and NPM v6.14.0 or above (tested with v8).

Run Locally for Development

At first, make sure you have the configurations/options that belong to an existing Deployment in the Database. The required ones are:
- The deploymentId. It is the Deployment id of the WebChat in the Database.
- The apiUrl of the specified Environment.
Create a local directory in the root of the project. Everything inside that folder gets git-ignored.
Create a config.js file inside local/ and export the preferred bot configurations/options, e.g.
```
module.exports = {
   deploymentId: "63c7e78d8a643f6722dd433c",
   apiUrl: "https://core.dev.helvia.ai/"
}
```
You can pass more configurations if you want, but the above are the bare minimum to make the webchat working on Development Mode.
(OPTIONAL) Create a style.css file inside local/ and add custom styling that cannot be configured through the options/configurations exported by config.js.
Run npm install and then npm start. That way you will start the webpack-dev-server and build the /src directory of the project on-the-fly by running the development configurations of the webpack (webpack.common.js+webpack.development.js).
Now, you are able to make changes in the code inside /src and see them live.

NOTES:

Any changes made outside the src/ directory, will not get bundled in the Webchat Generic Library.
The directory local/ can be used for testing locally and developing custom styling for a specific Tenant/Project that is going to use the Webchat Library.

Contributing [as a Developer]

Before we move into the steps of the contributions, let's define some useful notes.

HBF Webchat Library uses a workflow similar to Git Flow. If you know Git Flow, you mostly know how to contribute, if not please spend a couple of minutes on studying it.
- NEVER commit directly to develop branch. ALWAYS create a new branch.
- For FIX, create a new fix branch from master with name fix/ and make the fix. Then make the PR.
- For FEATURE, create a new feature branch from develop with name feature/ and build it. Then make the PR.
- The code that exists in master MUST exist in develop, too.
- Follow strictly the rule: one feature per PR. Do not develop multiple features on the same feature branch.
HBF Webchat Library keeps a CHANGELOG generated automatically.
HBF Webchat Library uses Semantic Versioning 2.0.0. Bumped almost automatically.
HBF Webchat Library uses an exact version of Prettier. Format the code before the PR.

Steps

Clone the repository git clone [email protected]:Helvia/hbf-webchat.git
Create your feature/fix branch following the rules we discussed in the notes above git checkout -b <branch-name>
Develop and Format your code with Prettier.
Commit your changes git commit -m 'Add some AmazingFeature/Fix'
Rebase your branch with the latest changes of the base branch git rebase <base-branch>
Push your branch to remote git push -f origin <branch-name>
Submit a pull request back to the base branch 🚀 😃

Contributing [as Leader/Code Reviewer]

HBF Webchat Library uses the module Standard Version for the releases.

Merging Pull Requests

PRs are merged with --squash and a commit message. Therefore, we don't care about the commits inside the feature or fix branches.
PR merge commits must follow the Conventional Commits Specification.
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope, and a subject:
```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```
The header is mandatory, and the scope of the header is optional. The type must be one of the following:
- feat: A commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in semantic versioning).
- fix: A commit of the type fix patches a bug in your codebase (this correlates with PATCH in semantic versioning)
- chore: Any small semantic change (version bump)
- build: Changes that affect the build system or external dependencies
- ci: Changes to our CI configuration files and scripts
- docs: Documentation only changes
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- test: Adding missing tests or correcting existing tests
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
Append a ! after the type/scope, to introduce a breaking API change (correlating with MAJOR in semantic versioning). A BREAKING CHANGE can be part of commits of any type.
The footer should contain a closing reference to an issue if any.
Samples: (even more samples)
```
docs(changelog): update changelog to beta.5
```
```
fix(release): need to depend on latest rxjs and zone.js
  
The version in our package.json gets copied to the one we publish, and users need the latest of these.
```
CHANGELOG is generated automatically based on the Conventional Commits.
Versioning is generated automatically based on the Conventional Commits.

Making a Release

Normal

To prepare develop for release you just need to execute this command on the develop branch:

npm run release

This command will automatically:

Retrieve the current version of your repository by looking at packagge.json, falling back to the last git tag.
bump the version in package.json based on your commits (it uses the Conventional Commits standard).
Generates a changelog based on your commits (uses conventional-changelog under the hood).
Creates a new commit including your package.json and updated CHANGELOG.md.
Creates a new tag with the new version number.

After that, you just need to merge develop into master and push all the changes.

HotFix

Hotfixes are merged directly to master branch, so you just need to execute this command on the master branch:

npm run release

After that, you just need to rebase the develop with the master and push all the changes.

BETA

To prepare develop for a BETA release you just need to execute this command on the develop branch:

npm run release:beta

After that, you just need to merge develop into master and push all the changes.

Upload on CDN for Production

NOTE: This workflow will soon be replaced by CI/CD.

Let's say that you have contributed, and your Pull Request (PR) has been merged (for Contribution rules check here and here).

Please make sure you have installed and configured awscli on your bash environment. If you don't know how, follow the official installation guide and the configuration guide. This has to be done once.

Checkout to master branch and pull the latest changes. git checkout master && git pull
Upload the code to AWS S3 for CDN npm run up-on-cdn. The Webpack, alongside the Babel will build the src code and will create a /dist folder. Then this folder will be synced with s3 bucket through awscli and then the /dist will be removed. Follow the logs to learn the link to the new version of the HBF Webchat Library.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

HBF Webchat Library

About the Project

Built With

Installation

Guide

Available Options

Greeting Messages

Reminder Messages

Message History

Custom Data Functions

window.HBF_retrieveUserId

window.HBF_retrieveUserInfo

window.HBF_retrieveMetadata

Multiple Instances in the same Webpage

Exposed Functions from window.HBFWebchat

HBFWebchat.getTranscript(options)

Other Features

Getting Started

Prerequisites

Run Locally for Development

Contributing [as a Developer]

Steps

Contributing [as Leader/Code Reviewer]

Merging Pull Requests

Making a Release

Normal

HotFix

BETA

Upload on CDN for Production