Merge branch 'lappis-unb-improve_bot_configuration'

README.md

@@ -87,7 +87,7 @@ To change the stemmers language, just set the environment variable `HUBOT_LANG`
 
 ## Deploy with Docker
 
-We have a Dockerfile that builds a lightweight image based in Linux Alpine with all the repository content so you can upload that image to a docker registry and deploy your chatbot from there.
+We have a Dockerfile that builds a lightweight image based in Linux Alpine with all the repository content so you can upload that image to a docker registry and deploy your chatbot from there. It is located on `docker` folder.
 
 You also can use `docker-compose.yml` file to load a local instance of Rocket.Chat, MongoDB and HubotNatural services, where you can change the parameters if you must.
 
@@ -164,6 +164,16 @@ You can change the attributes of variables and volumes to your specific needs an
 
 If you want to run only the hubot-natural service to connect an already running instance of Rocket.Chat, you just need to remember to set the `ROCKETCHAT_URL` to a correct value, like `https://open.rocket.chat`.
 
+## Bot configuration
+
+In order to correctly use Hubot Natural, after running `docker-compose up` command, it is necessary to do some configuration steps. To do that, there are two main options:
+
+The first one is to do manually the steps described at [bot config documentation](docs/config_bot.md).
+
+The second option is to execute the script `bot_config.py`, located at root directory on project. That will automatically configure bot based on following variables defined on script: `admin_name, admin_password, bot_name` and `bot_password`.  It is important to remember of properly set the values of this variables according to the context. The values used on `bot_name` and `bot_password` must be the same defined on docker-compose.yml, on the variables `ROCKETCHAT_USER` and `ROCKETCHAT_PASSWORD` respectively. And the values defined at `admin_name` and `admin_password` variables must be the credentials of an pre existent user on rocketchat, that has admin permissions.
+
+To create an admin user automatically, before executing the services, just define the variables `ADMIN_USERNAME` and `ADMIN_PASS` for rocketchat service on `docker-compose.yml`.
+
 ## Deploy with Hubot
 
 To deploy HubotNatural, first you have to install yo hubot-generator:
@@ -234,6 +244,11 @@ wait a minute for the loading process, and then you can talk to mybot.
 
 Take a look to adapters to run your bot in other platafforms.
 
+## Configure Live Transfer
+
+It's possible to configure Hubot Natural to redirect conversation to a real person, in moments when the bot can not help users as much as needed.
+To activate and configure `Live Transfer` feature, follow the steps described on [live transfer config documentation](docs/config_live_transfer.md).
+
 ## Env Variables:
 
 In your terminal window, run:

bot_config.py

+#!/usr/bin/env python3
+# coding: utf-8
+
+import requests
+import json
+import os
+
+host = "http://rocketchat:3000"
+path = "/api/v1/login"
+
+bot_name = 'ROCKETCHAT_USER'
+bot_password = 'ROCKETCHAT_PASSWORD'
+bot_email = botname + '@email.com'
+admin_name = 'ADMIN_USERNAME'
+admin_password = 'ADMIN_PASS'
+
+def get_authentication_token():
+    login_data = {"username": admin_name, "password": admin_password}
+    response = requests.post(host+path, data=json.dumps(login_data))
+    if response.json()['status'] == 'success':
+        print("login suceeded\n")
+
+        authToken = response.json()['data']['authToken']
+        userId = response.json()['data']['userId']
+        user_header = {
+            "X-Auth-Token": authToken,
+            "X-User-Id": userId,
+            "Content-Type": "application/json"
+        }
+
+        return user_header
+
+
+user_header = get_authentication_token()
+
+
+def create_user():
+    user_info = {
+        "name": bot_name,
+        "email": bot_email,
+        "password": bot_password,
+        "username": bot_name,
+        "requirePasswordChange": False,
+        "sendWelcomeEmail": True, "roles": ['bot']
+    }
+
+    create_user_response = requests.post(
+        host + "/api/v1/users.create",
+        data=json.dumps(user_info),
+        headers=user_header
+    )
+
+    if create_user_response.json()['success'] is True:
+        print("User has been sucessfully created!")
+    else:
+        print("Error while creating bot user!")
+
+
+def create_agent():
+    agent_info = {"username": bot_name}
+    create_agent_response = requests.post(
+        host + "/api/v1/livechat/users/agent",
+        data=json.dumps(agent_info),
+        headers=user_header
+    )
+
+    if create_agent_response.json()['success'] is True:
+        print("Bot agent has been sucessfully created!")
+    else:
+        print("Error while creating bot agent!")
+
+    return create_agent_response
+
+
+def configure_livechat():
+    # Enable Livechat
+    requests.post(
+        host + "/api/v1/settings/Livechat_enabled",
+        data=json.dumps({"value": True}),
+        headers=user_header
+    )
+
+    # Disable show pre-registration form
+    requests.post(
+        host + "/api/v1/settings/Livechat_registration_form",
+        data=json.dumps({"value": False}),
+        headers=user_header
+    )
+
+
+def create_department(bot_agent_id):
+    department_info = {
+        "department": {
+            "enabled": True,
+            "showOnRegistration": True,
+            "name": "department",
+            "description": "default department"
+        },
+        "agents": [{
+            "agentId": bot_agent_id,
+            "username": bot_name,
+            "count": 0,
+            "order": 0
+        }]
+    }
+    create_department_response = requests.post(
+        host + "/api/v1/livechat/department",
+        data=json.dumps(department_info),
+        headers=user_header
+    )
+
+    if create_department_response.json()['success'] is True:
+        print("Default department has been sucessfully created!")
+    else:
+        print("Error while creating department!")
+
+
+if user_header:
+    create_user()
+
+    create_agent_response = create_agent()
+    bot_agent_id = create_agent_response.json()['user']['_id']
+
+    configure_livechat()
+
+    create_department(bot_agent_id)
+
+else:
+    print("login failed")

docker-compose.yml

@@ -42,7 +42,9 @@ services:
 
   hubot-natural:
     # image: diegodorgam/hubot-natural:latest
-    build: .
+    build:
+      context: .
+      dockerfile: ./docker/Dockerfile
     restart: unless-stopped
     environment:
       - HUBOT_ADAPTER=rocketchat

docs/config_bot.md

+# Hubot Natural Bot
+
+## Adding Hubot Natural Bot
+
+To add the bot into your Rocket Chat, you must create an administrator account. In the initial screen, click on **Register a new account**, and fill the informations, you don't need to use a real email account.
+
+![New account example](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/new_account.png)
+
+Once you filled the informations, click on REGISTER A NEW ACCOUNT, and then go back to login page, and do login.
+
+In the left side menu, click on tree points icon, and then click on **Administration** option.
+
+After that, click on **Users** option. It will appear a right side bar, having the '+' button. Click on this button and fill the informations according to the following image. The name of bot can be modified, but must be used the user and password that are defined on ROCKETCHAT_USER and ROCKETCHAT_PASSWORD variables, on `production.yml` file. By default, the user and password are `botnat` and `botnatpass`, respectively.
+
+To add the role to bot, click the option **Select a Role**, select bot and click on **ADD ROLE** option. Then click on **Save**.
+
+![Adding bot tutorial](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/adding_bot.png)
+
+Now you are ready to talk to the bot using the channels, or using @botnat before the message.
+
+### Livechat
+
+The Livechat allows a feature of a window that can be integrated to other pages. To activate it, you must access again the **Administration** option, by clicking on three points icon, on the left side menu. Then click on **Livechat** option.
+
+![Livechat option on adm menu](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/livechat_sidebar.png)
+
+On the next screen, mark the **Livechat enabled** option as True, and the **Show pre-registration form** option as False, in order to not be asked for email and password when using chat. Click then in **SAVE CHANGES**.
+
+![Livechat activation screen](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/active_livechat.png)
+
+Close the left side menu, and click on three points icon. Select the **Livechat** option.
+
+![Livechat option](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/livechat_option.png)
+
+At the right side menu, select the **User Management** option. You must add the bot as an agent, so search for botnat, then click in **ADD**.
+
+![Adding bot as agent](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/add_agent.png)
+
+Now it is necessary to create an department. On the left side menu, click on **Departments**, and then click in **NEW DEPARTMENT**.
+
+![Adding bot as agent](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/new_department.png)
+
+On the next screen, write a name and a description for the department and add the bot by selecting him on **Available agents**. Then click on **Save** option.
+
+![Create new department](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/add_agent_to_department.png)
+
+On the left side menu, click at **Installation**. Now you only need to copy and paste the code on your site, where you want to integrate the conversation window.
+
+![Installation code](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/installation.png)
+
+After integrating the code to your site, a window like the one showed in the image should be available, and ready to use.
+
+![Livechat window](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/livechat_en.png)
+
+#### Welcome message on Livechat
+
+To fire a welcome message can be used **Triggers**. A **Trigger** fire an action according to a condition. A condition can be the user accessing an URL, or the time user stay on site. The action, in this case, is the welcome message send.
+
+To add a **trigger** to Livechat, on the left side menu, click on **Triggers** option. Then mark the option **Enabled** as **Yes**, and fill the trigger name and description. In case of the firing critery is the user entering a URL, then choose the option **Visitor page URL** on **Condition** field, and on the side field write the desired URL.
+Select the option **Send a message** at field **Action**, type the bot name(**botnat**) and the welcome message. After all, click on **Save**.
+
+![Livechat Trigger URL](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/trigger_url.png)
+
+## Updating the YAML
+
+
+To read more information about the YAML structure and how to modify it, access the [Hubot-Natural README](https://github.com/RocketChat/hubot-natural/blob/master/README.md).

docs/config_live_transfer.md

+# Config Live Transfer
+
+In order to user `Live Transfer` feature, it is necessary to do some steps.
+
+The first thing to do is to set the department hash, on the file used as corpus on bot. The department hash must be placed on `department` field, in the section named `livechat-transfer`, as showed on the image below. The file being used as corpus is the one defined on field `HUBOT_CORPUS`field, at docker-compose file.
+
+![Updating corpus file](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/update_corpus.png)
+
+The department hash can be obtained on the URL in department `edit screen` as showed on image below.
+
+![Getting department id](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/department_hash.png)
+
+To get to department `edit screen` close the left side menu, and click on three points icon. Select the **Livechat** option.
+
+![Livechat option](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/livechat_option.png)
+
+Now it is necessary to select the department to be used on transfer action. On the left side menu, click on **Departments**, and then click on the department name.
+
+![Select department](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/new_department.png)
+
+Once you got the department hash and placed on corpus file, restart the hubot-natural service, in order to update the container and reload `corpus` file.
+
+Lastly is important to remember that the live transfer conversation channel will be created between any available user on department. For that, the user must be online, and must be previously added as an agent on department being used(The one defined on corpus file). For that, You must first add the user as an agent. At the right side menu, select the **User Management** option. , so search for the user you want, then click in **ADD**.
+
+![Adding user as agent](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/add_as_agent.png)
+
+Then again on the department edit screen, add the user to department by selecting him on **Available agents**. Then click on **Save** option.
+
+![Add agent to department](https://gitlab.com/lappis-unb/projects/minc/rouanet-bot/wikis/images/add_user_to_department.png)