Demo chatbot for giosg platform
Please read the following documentation so that you understand the basic principles of how chatbots work on giosg platform as "apps":
How it works?
The chatbot has the following functionality:
- When a new chat is routed to the bot, it automatically joins it and sends a message containing link buttons for different topics
- Whenever a link topic button is clicked, it sends another message (and offers the same buttons)
- It also offers a button for inviting a human to the chat. If clicked, the bot will invite an online team to the chat if found.
- When inviting people, the bot tries to find a team by default with the name "Customer service". This may be configured.
- Finally, after inviting a team, the bot asks if their help was useful or not. It then leaves the chat.
requirements.txtcontains Python (PIP) requirements for running and developing the bot
server/conf.pyreads the configuration for the chatbot from the environment variables
server/server.pydefines the Flask server app and the URL routings
server/views.pydefines the views for handling incoming HTTP requests
server/bot.pydefines the functional logic of the chatbot
server/giosg.pydefines simple utility functions for making HTTP requests to the giosg HTTP API
server/tests/contains unit tests for the app
server/templates/contains the HTML template for the "front page" of the bot server
Setting up local dev environment
Clone the repository
git clone https://github.com/giosg/demo-bot.git
Create a Python 2.7 virtualenv for the project:
cd demo-bot mkvirtualenv -a . -r requirements.txt demo-bot
To later switch to the virtualenv and to the folder:
To ensure that you have the latest PIP requirements installed:
pip install -r requirements.txt
Set up environment variables
Add the correct information to your environment variables required by the bot.
TIP: You can add these lines to the virtualenv postactive hook file (
$VIRTUAL_ENV/bin/postactivate), so that they are automatically applied whenever you
workon on your virtualenv!
# REQUIRED: A shared secret that the chatbot requires to be provided as the `secret` parameter in webhook requests export SECRET_STRING="bEsTsEcReT" # OPTIONAL: Name of the team which bot will invite to the chats, if online. Defaults to "Customer service" export INVITEE_TEAM_NAME="Chat agents"
Set up the app
Please follow the giosg APPs documentation to perform the following steps:
- Create a giosg APP to your organization account, with the webhooks as described below
- Install the app, probably to your own organization, at least while developing
- Route chats from the desired room to the chatbot by adding the created bot user to a router
The chatbot will react to the events in the giosg system. It needs to be notified by HTTP webhooks whenever there are new chats or chat messages. For this purpose, you need to configure the following webhooks, as described in the documentation
|Endpoint URL||Channel pattern||What to subscribe|
<YOUR_SECRET> needs to be replaced with your custom random secret string you used in
SECRET_STRING environment variable.
your-chatbot-host.com needs to be replaced with the domain where your chatbot is hosted.
For local development using
localhost won't of course work, as giosg servers cannot reach your local environment.
Instead, you can use a tunneling service, such as ngrok. After launching your local server, tunnel your traffic with this command:
./ngrok http 5000
Then use the printed hostname as
https://your-chatbot-host.com in the webhook configurations, e.g.
After installing the dependencies, you can run the tests locally:
python -m unittest discover
Running dev environment
The Flask application runs locally in
Run the server with the following command.
Use the host
0.0.0.0 if you are using a tunnel such as ngrok.
export FLASK_APP="server/server.py" flask run --host=0.0.0.0
You may want to the your docker image locally before publishing it:
- You must first build image first
docker build -t <tag_name> .,
- where you show give some human readable tag name that you recognize
- Run the flask server
docker run -e FLASK_APP=server/server.py -p 5000:8000 <tag_name> flask run --host='0.0.0.0'
- Also you have to provide Bot's ID etc as environment variables