A Cisco Webex Teams bot is an automated user within the Webex Teams platform that can be interacted with, enhancing the user experience within an organisation. The following instructions will guide you through the steps required to create and run your own Cisco Webex Teams Bot.
Go to the Cisco Webex website and select Teams in the Sign in drop down menu on the top right corner. Fill in your details and follow the instructions to create an account.
Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Find out more about git here.
The git installation will depend on your machine's Operating System (OS). After installing, confirm that git is available by entering the following command on terminal.
git --version- Install git on MacOS
Probably the quickest way to get git on your machine is to install it with Homebrew. Homebrew is a free and open-source software package management system that simplifies the installation of software on Apple's macOS operating system and Linux.
To install Homebrew, open Terminal and run the following command.
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"Once the installation is finished, install Git by running the following command.
brew install git- Install git on Ubuntu/Linux
To install Git on your machine, run each of the following commands in your terminal sequentially.
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git- Install git on Windows
Go to the Downloading Git for Windows page, download and install it. Keep all the settings standard as you run through the installation process.
Docker is an open platform for developing, shipping, and running applications. It is the most trendy container technology for running modern software apps particularly in the cloud. Find out more about Docker and containers here.
The docker installation will depend on your operating system. After installing, confirm that Docker is available by entering the following command on terminal.
docker -v- Install Docker on MacOS
Go to the Install Docker Desktop for Mac webpage. Head to Docker Hub by clicking the Download the Docker Hub button. After checking if your Apple Mac OS version fits the requirements, click on the Get Docker button and follow the installation instructions.
- Install Docker on Ubuntu/Linux
To set up the Docker repository in your machine, run each of the following command lines in your terminal sequentially.
sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg2 software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"Finally, to install Docker simply run
sudo apt-get update
sudo apt-get install docker-ce- Install Docker on Windows
Go to the Install Docker Toolbox on Windows webpage and click on Get Docker Toolbox for Windows to start download. Follow the installation, accept admin prompts and requests to install network adapters.
- Install Docker on other OS
Please find instructions on how to install Docker on other Operating Systems here.
Go to Cisco Webex for Developers and log in with your Cisco Webex Teams account details.
Click Documentation on the top bar and select the Bots section on the left. On this Bots Documentation webpage you will find an extended explanation on what are Bots and how to create them.
To proceed, click on the Create a Bot button and fill up all the required information to describe your new Bot. Finally, scroll down and click on the Add Bot button. Your Bot has now been created.
Click on Regenerate Access Token and save it since you will need it later.
- Non-Windows Users
Good news! This is quite a trivial step for you since you just need to open your terminal. We recommend you work on your home directory, /home/<username> (Linux) or /Users/<username> (macOS), both shown as ~. However, you can navigate to another directory using cd <other-directory>.
- Windows Users
Open the Docker Quickstart Terminal from the Start Menu. Once you see an ASCII boat in the terminal (the Docker logo) and can type in the terminal, navigate to the Public directory by running the following command.
cd /c/Users/PublicNote that if c isn't your Windows drive letter, you must replace it with the correct drive letter.
Remember that you must continue working on this terminal for the following steps.
Clone the current git repository recursively with submodules to your local machine by running the following command on your terminal.
git clone --recursive https://github.com/haskalpa/docker-webexteams-bot-example.gitIf you run the command ls, you will find all the directories and files inside your current directory. To go to directory you have just cloned simply run cd docker-webexteams-bot-example. Try running ls and check that you can see all the files you will need to get your Bot up and running.
Remember the access token for the bot that you saved earlier? Here is where you will need it.
Open the folder that you have just created, docker-webexteams-bot-example. Inside you will find a folder named config, open it. Then, create a copy of the config_example.yaml file and rename it to config.yaml.
Open the new file with your favourite text editor. If you still do not have one, take a quick look at Atom, Visual Studio Code or (in case you are a very brave developer) Vim. This is what the file contents should look like:
---
hello_bot:
teams_access_token: <my_bot_access_token>Yep, you guessed it! Replace <my_bot_access_token> with the Access Token you save during the Create a Bot step.
Back to the terminal window: run the following command to build your Docker container.
./build.shAfter a couple of seconds, you should get a Successfully built message in your terminal window.
If you are a Windows user, you will need to start with Step 1. If not, just skip this step and go directly to Step 2.
Step 1
Open Notepad++ and open the file run_hello_bot.sh. You don't have Notepad++? Just quickly install it here.
Once you have opened the file, go to the Edit menu on the top bar and click EOL Conversion. Set this to Unix (LF). Then, save the file and close Notepad++.
Repeat the above with hello_bot/run.sh.
Step 2
Run the Docker container with the following command.
./run_hello_bot.shLogin to your Webex Teams account and Create a space by clicking the + button. Chose a name for the new space. Then, add your Bot to this space with the Bot Username you specified during the Create a Bot step. The format of this username should be [email protected].
Say hello to your bot by tagging it using it's name, then typing hello. Typing and saying @<botname> hello should have the bot reply hello, person who has email <your email>, congratulations! You managed to set up your first Bot.
The bot is essentially running a single Python file, hello_bot.py. Through the Webex Teams API, once the bot receives a message, it also receives the Person who sent the message, which includes various details about them. One of these details is the email account of the user that messaged it.
If your bot seems to be having problems, have a look at the logs with
docker logs -f hello_botNeed to do some troubleshooting? The following steps will help you if you need to debug your Python script. Open docker shell into your container with
docker exec -it hello_bot bashTo show running processes for all user run inside the shell
ps auxwYou should get a list similar to
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
root 1 0.0 0.0 18028 2948 pts/0 Ss 11:45 0:00 bash /workspace/run.sh
root 7 0.2 0.0 20536 14676 pts/0 Sl 11:45 0:00 ngrok http 5000 -bind-tls=true -config /opt/config/ngrok.yaml -log=
root 23 0.1 0.2 103268 40200 pts/0 S 11:45 0:00 python hello_bot.py
root 24 0.0 0.0 18236 3296 pts/0 S+ 11:45 0:00 bash
root 34 0.0 0.0 18240 3384 pts/1 Ss 11:49 0:00 bash
root 44 0.0 0.0 34424 2808 pts/1 R+ 11:49 0:00 ps auxwHere you will find your script running, a line with python hello_bot.py as the command. In this example, the process has the ID 23. Therefore, to kill the python bot script you will need to run inside the shell.
kill 23If you want to confirm the previous step, run ps auxw again and check that the python hello_bot.py line has disappeared. You can now make changes to your hello_bot.py script. To run it again, you just need to run the following command.
python hello_bot.pyTo exit the docker shell just run exit.
- Cisco Webex Teams App Hub: Get some inspiration to develop your own bot from this list of Cisco Webex Teams Bot examples