Chat History Server

User generated content can be stored on-premise or in a ServisBOT customer’s private cloud if required due to security or regulation. Our Chat History Server (CHS) provides secure storage of all conversations with end-users.

Technical Details

  • Our CHS is a Node.js application
    • Recommended Minimum Hardware : 1 CPU, 3GB RAM
  • The CHS is intended to connect to a customer managed MySQL 8 or MsSQL 2017 Database

Installation Instructions

These instructions use docker run to instantiate the CHS, however you may chose to run the container using Docker Compose, Docker Swarm or Kubernetes. Additional integration may be required to run in different container management systems, please contact your customer service representative.

MySQL 8 and MsSQL 2017 are supported as persistence layer. Additional persistence implementations may be provided at additional cost, please contact your customer service representative.

Prerequisites

  • A server with Docker installed to host the CHS application
  • An instance of MySQL or MsSQL running that is accessible from the CHS container
  • CHS Enabled for your organization and configured (contact customer support once your CHS is available.)

Configure the Database Instance

  • Create a database called ServisbotChatHistory (this name can be chosen by the customer to follow their own conventions and standards)
  • Run the following SQL against the database

    MySQL

CREATE TABLE IF NOT EXISTS Messages (
  Id BIGINT UNIQUE NOT NULL AUTO_INCREMENT,
  ConversationId VARCHAR(60) NOT NULL,
  Organization VARCHAR(60) NOT NULL,
  Identity VARCHAR(60) NOT NULL,
  Contents TEXT NOT NULL,
  MessageId VARCHAR(60) NOT NULL,
  Timestamp BIGINT NOT NULL,
  SbId VARCHAR(100) NOT NULL UNIQUE,
  PRIMARY KEY (Id),
  INDEX ConversationId (ConversationId),
  INDEX Timestamp (Timestamp),
  INDEX Organization (Organization)
);

CREATE TABLE IF NOT EXISTS Interactions (
  Id BIGINT UNIQUE NOT NULL AUTO_INCREMENT,
  ConversationId VARCHAR(60) NOT NULL,
  Organization VARCHAR(60) NOT NULL,
  Identity VARCHAR(60) NOT NULL,
  Contents TEXT NOT NULL,
  MessageId VARCHAR(60) NOT NULL,
  Timestamp BIGINT NOT NULL,
  SbId VARCHAR(100) NOT NULL UNIQUE,
  PRIMARY KEY (Id),
  INDEX ConversationId (ConversationId),
  INDEX Timestamp (Timestamp),
  INDEX Organization (Organization)
);

Note: The Contents column on all tables also supports the “JSON” type.

MsSQL

CREATE DATABASE ServisbotChatHistory;
GO
USE ServisbotChatHistory;
CREATE TABLE Messages ( 
  Id BIGINT NOT NULL IDENTITY, 
  ConversationId VARCHAR(60) NOT NULL, 
  Organization VARCHAR(60) NOT NULL, 
  [Identity] VARCHAR(60) NOT NULL, 
  Contents nvarchar(max) NOT NULL, 
  MessageId VARCHAR(60) NOT NULL, 
  Timestamp BIGINT NOT NULL, 
  SbId VARCHAR(100) NOT NULL, 
  PRIMARY KEY (Id), 
  INDEX ConversationId (ConversationId), 
  INDEX Timestamp (Timestamp), 
  INDEX Organization (Organization), 
  UNIQUE(SbId) 
);
GO

CREATE TABLE Interactions ( 
  Id BIGINT NOT NULL IDENTITY, 
  ConversationId VARCHAR(60) NOT NULL, 
  Organization VARCHAR(60) NOT NULL, 
  [Identity] VARCHAR(60) NOT NULL, 
  Contents nvarchar(max) NOT NULL, 
  MessageId VARCHAR(60) NOT NULL, 
  Timestamp BIGINT NOT NULL, 
  SbId VARCHAR(100) NOT NULL, 
  PRIMARY KEY (Id), 
  INDEX ConversationId (ConversationId), 
  INDEX Timestamp (Timestamp), 
  INDEX Organization (Organization), 
  UNIQUE(SbId) 
);
GO

Build the CHS Docker Image

git clone git@github.com:servisbot/servisbot-labs.git
cd servisbot-labs/sb-chat-history-server
docker build -t servisbot/chat-history-server . 

Configure your environment

An environment file called chs.env is configured to be used with docker run

LOG_LEVEL=info
DB_HOST=my-database-instance
DB_USER=myuser
DB_PASSWORD=my-password
DB_PORT=3306
DB_CONNECTION_LIMIT=10
APP_VERSION=v1
DB_IMPLEMENTATION=MYSQL
  • LOG_LEVEL : set to info for standard operation, debug, warn & error also available
  • DB_HOST : The host name or IP address of the MySQL or MsSQL instance
  • DB_USER : The user authorized to read and write to/from DB_NAME
  • DB_PASSWORD : The password for DB_USER
  • DB_PORT : The port that the database instance is listening on
  • DB_CONNECTION_LIMIT : Connection pooling is used in the CHS, this limit the number of connections in the pool
  • APP_VERSION : the version of the CHS server you want to run. You can find the version below
  • DB_IMPLEMENTATION: the chosen database implementation: MYSQL or MSSQL

Adjust the settings to match any alternate requirements that you have.

It is also possible to tune the Node.js runtime via

NODE_OPTIONS=--max-old-space-size=512

Versions

When you pass in the version only those routes get mounted on the api. So if you pass in v1 you wont be able to hit v2.

Below is a list of the current supported versions

  • v1

CHS API

The CHS API documentation is available at the root of the CHS @ /swagger/api.yml e.g. https://mychs.com/swagger/api.yml

Initiate the Container

docker run -d -p "8080:8080" --name=sb-chs --env-file=chs.env servisbot/chat-history-server:<specific-version>

Explanation :

  • -d will run the CHS container as a daemon. Remove the -d flag to in your current terminal session.
  • -p "8090:8080" will map port 8090 on the host machine to the port that the application is running on within the docker container. (The application runs on port 8080 within the CHS container)
  • --name=sb-chs this will name your container, you may prefer to leave this blank
  • --env-file=chs.env load the Environment Variables from the preconfigured file from the previous steps

Run docker ps to ensure the container is running. It is also possible to tail the logs via:

docker logs -f sb-chs

Confirm Installation

Once you have the docker container running the main application, you can test the application / database configuration by running sb-cli app chs-discover <ip/url> command against that server.

Note: The logged in user must have the IT role in their organization to have access to this command.

  • <ip/url> is an HTTP/HTTPS URL or IP of the CHS
  • This command tests the /about,/persist, and /history endpoints by storing and retrieving some test data.
  • If /about fails, the other endpoints are not tested.

Example:

sb-cli app chs-discovery http://127.0.0.1:8080

Starting CHS Discovery command
conversationId: app_conversation_id_ABCDEFG

1. Testing server route /about:
{
  "ok": true,
  "version": "v1",
  "status": 200
}
Result: /about is working normally.

2. Testing server route /persist:
{
  "status": 200,
  "statusText": "OK"
}
Result: Successfully saved message 'CHS persistence test message'

3. Testing server route /history:
{
  "status" 200,
  "body": [
    {
      "id": "app_id_ABCDEFG",
      "to": "server",
      "key": "TIMELINEMESSAGE:::app_conversation_id_ABCDEFG:::12345678910:::app_id_ABCDEFG",
      "type": "TimelineMessage",
      "version": "v2",
      "contents": {
        "message": "CHS persistence test message"
      },
      "identity": "app_identity_ABCDEFG",
      "timestamp": 12345678910,
      "contentType": "message",
      "organization": "someorg",
      "correlationId": "aBc-deFGh",
      "conversationId": "app_conversation_id_ABCDEFG"
    }
  ],
  "ok": true
}
Result: The saved message has been retrieved successfully

chs-discovery result: /about, /persist and /history are all working normally

Finished CHS Discovery command

Your network will need to allow incoming traffic from the machine running the chs-discovery command.

Notes

  • All traffic towards the CHS from ServisBot originates from a known set of IP Addresses, these will need to be allowed through your network infrastructure to ensure communication between ServisBot and the CHS.

Enabling CHS for your org

If you have purchased this add-on for ServisBOT, reach out to your customer care representative with the URL or domain where your CHS can be reached. Once enabled you can use this URL to test the addon via sb-cli chs commands.

Testing

Once everything is configured user generated content will be persisted in your CHS instead of ServisBOT.

  • Test one of your bots, if you do no have one created yet, follow Getting Started Docs

  • Review the Chat History

  • Log into your mysql/mssql instance and review the data stored in the messages_v1 table

Infrastructure

The following IPs will need to be whitelisted for ingress in your firewall to allow communication for ServisBot.

EU-1

34.248.122.125/32
52.49.224.4/32

US-1

34.231.250.115/32
52.1.103.10/32