Webex Bots with Ngrok made easy

[Dirk-Jan Uittenbogaard]

TIME: 5 minutes (if Ngrok & pipenv are installed)  

DIFFICULT? No

TESTED ON: MacOS, Windows 10

WHY?

• Really easy to quickly test a bot
• Can be used if your bot code runs inside the firewall
• (Without publicly accessible URL for the webhook to talk to)
• The code automatically creates/updates webhooks to point to the right URL (Ngrok)
• Easy to run your own bot demo
• No server/hosting/platform dependencies
• Don't want to use Ngrok? Check out my easy "Bot with Websockets" code!​​​​​​​

Instructions

A - Prepare

• Create a Webex bot 
• Download the code here  
• Check if you have python: "python -V"
  version should be 3.9 or higher
• Check if you have pip: "python -m pip -V"
  'pip' is used to install Python libraries

​​​​​B - Create a folder for the bot and copy the bot files to this folder

1. "mkdir webex-bot-ngrok"
2. "cd webex-bot-ngrok"
3. copy bot files to this folder 
   (When using Pipenv, also copy "Pipfile")

C - Install "Ngrok" 

1. Check if you have Ngrok: "ngrok"
2. If not installed, download the Ngrok installer and run it. 

______________ D/E/F/G below: only if you use Pipenv ______________

D - Install "Pipenv" (if not installed)

1. Check if you have pipenv: "pipenv -V"
2. If not, install it: "python -m pip install pipenv"

E - Create Pipfile: (or use the supplied Pipfile)

1. (Mac) "touch Pipfile" (creating the file)
2. Edit "Pipfile"
3. Paste content below in the Pipfile and save it. The folder now contains 1 file: "Pipfile" and Pipenv is ready to do its job.

[source]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "webex-bot-using-ngrok"
[dev-packages]
[packages]
requests = "*"
webexteamssdk = "*"
flask = "*"
[requires]
python_version = "3.9"

F - Setup virtual environment

1. "Pipenv install"
   Based on the Pipfile, this creates a local environment with the required packages.

G - Activate the created virtual environment

1. "Pipenv shell"
   Your prompt changes to indicate you are in the "isolated" setup.​​​​​​​

​​​​​​​NOTE: When you start the bot, you need to be in the Pipenv shell. Otherwise, it will not have the right libraries available.

Alternatively: type "pipenv run python webex-bot-ngrok.py"

This directly runs the python code inside the pipenv environment. 

______________ D/E/F/G above: only if you use Pipenv ______________

H - Set bot token environment variable

• (MacOS): export MY_BOT_TOKEN='YOUR_TOKEN_HERE'
• (Windows): set MY_BOT_TOKEN=YOUR_TOKEN_HERE

I - Run the Bot (Python code)

1. "python webex-bot-ngrok.py"  
2. When the "___start_____" message appears, test the bot!

J - Test the bot

1. Send "test" to the bot.
2. It should repeat your message.
3. Send "hello" to the bot.
4. It should respond differently.

NEXT?

update the "process_message" function to make it respond to the commands that you are sending.

LIKE IT?

In order for me to create presentations, demos, labs and more:  let me know you liked it  (click the "helpful" button or leave a comment)

Pipenv! WHAT DOES PIPENV DO? Create a Pipfile with your package & python requirements. Then run "pipenv install" to create an isolated environment with the python version and the required python libraries. These are not installed system-wide but inside the 'virtual environment' that you can activate. GREAT? Yes, it is great to test a setup or library without having to install it system wide. You can have multiple virtual environments that each have different versions, libraries etc., without affecting the system wide setup. DIFFFICULT? No. Really, it isn't. Follow the instructions below to see it working.

Ngrok? Ngrok is a small application that can setup a tunnel from 'the internet' to the computer running the ngrok application.

CUSTOMIZE script

There are a few customizations that you can do:

• change the webserver port (default: 4111)
  Variable: webserver_port = 4111  
• enable debugging (default: False)
  With debugging enabled your code will be relaunched every time you save your python code.
  Variable: webserver_debug = False  
• change the Ngrok status port number (default for the first Ngrok tunnel you open = 4040).
  Can be useful if you run multiple Ngrok tunnels they will all have the same status URL but with a different port number (4040, 4041, 4042 etc.)
  Variable: ngrok_port = 4040  
• Put your bot token in code instead of an environment variable (bad practice but if you have your reasons, I won't stop you)
  How? After "my_bot_token=", replace the os.getenv with your bot token between quotes and remove the if clause after this statement.

And the most important customization: change what it is that your bot should do!

FAQ

Q: NGROK: I don't want to/can use Ngrok

A: Then check out my alternative solution: Webex Bot using Websockets. 

Q: NGROK: My Ngrok tunnel expires in 2 hours!

A: Stop Ngrok and start it again. Your code also has to restart to use the new Ngrok public_url.

     OR create a (free) Ngrok account and go here to get your API token and see how to use it.

           After that, no code modifications are needed.

Q: NGROK: Can the bot code wash my dishes?

A: I have tried it but I am missing a critical library: dishcontrol (version 8.1 or above).

Q: NGROK: Can I prevent Ngrok tunnels from expiring?

A: Yes. Create a free Ngrok account. That will give you 1 tunnel that doesn't expire.

Q: NGROK: I have a problem with Ngrok

A: if you have more than one Ngrok tunnel active at the same time, only the first tunnel (with web interface port 4040) is used. 

Q: NGROK: How do I exit the Pipenv virtual environment?

A: Mac: CTRL-D and Windows: type "exit" 

Do this without Pipenv?

Use the instructions above, except:

- skip step D, E, F and G
- install the required Python libraries manually:

• python -m pip install requests
• python -m pip install webexteamssdk
• python -m pip install flask

- Continue with step H

MORE developer resources & projects:  cs.co/webexdevinfo  

[Alex Stevenson]

Excellent article! Clear, concise and fun.