A Flask based Webex Teams chat bot.
Project description
webexteamsbot
This package makes creating Webex Teams bots in Python super simple.
This package is based on the previous ciscosparkbot project. This version will both move to new Webex Teams branding as well as add new functionality. If you've used
ciscosparkbot
you will find this package very similar and familiar.
Prerequisites
If you don't already have a Webex Teams account, go ahead and register for one. They are free.
-
You'll need to start by adding your bot to the Webex Teams website.
-
Click Create a New App
-
Click Create a Bot.
-
Fill out all the details about your bot. You'll need to set a name, username, icon (either upload one or choose a sample), and provide a description.
-
Click Add Bot.
-
On the Congratulations screen, make sure to copy the Bot's Access Token, you will need this in a second.
Installation
Python 3.6+ is recommended. Python 2.7 should also work.
-
Create a virtualenv and install the module
python3.6 -m venv venv source venv/bin/activate pip install webexteamsbot
Usage
-
The easiest way to use this module is to set a few environment variables
Note: See ngrok for details on setting up an easy HTTP tunnel for development.
export TEAMS_BOT_URL=https://mypublicsite.io export TEAMS_BOT_TOKEN=<your bots token> export TEAMS_BOT_EMAIL=<your bots email> export TEAMS_BOT_APP_NAME=<your bots name>
-
A sample script is also provided for your convenience
# -*- coding: utf-8 -*- """ Sample code for using webexteamsbot """ import os import requests from webexteamsbot import TeamsBot from webexteamsbot.models import Response # Retrieve required details from environment variables bot_email = os.getenv("TEAMS_BOT_EMAIL") teams_token = os.getenv("TEAMS_BOT_TOKEN") bot_url = os.getenv("TEAMS_BOT_URL") bot_app_name = os.getenv("TEAMS_BOT_APP_NAME") # Create a Bot Object # Note: debug mode prints out more details about processing to terminal bot = TeamsBot( bot_app_name, teams_bot_token=teams_token, teams_bot_url=bot_url, teams_bot_email=bot_email, debug=True, ) # Create a custom bot greeting function returned when no command is given. # The default behavior of the bot is to return the '/help' command response def greeting(incoming_msg): # Loopkup details about sender sender = bot.teams.people.get(incoming_msg.personId) # Create a Response object and craft a reply in Markdown. response = Response() response.markdown = "Hello {}, I'm a chat bot. ".format(sender.firstName) response.markdown += "See what I can do by asking for **/help**." return response # Create functions that will be linked to bot commands to add capabilities # ------------------------------------------------------------------------ # A simple command that returns a basic string that will be sent as a reply def do_something(incoming_msg): """ Sample function to do some action. :param incoming_msg: The incoming message object from Teams :return: A text or markdown based reply """ return "i did what you said - {}".format(incoming_msg.text) # An example using a Response object. Response objects allow more complex # replies including sending files, html, markdown, or text. Rsponse objects # can also set a roomId to send response to a different room from where # incoming message was recieved. def ret_message(incoming_msg): """ Sample function that uses a Response object for more options. :param incoming_msg: The incoming message object from Teams :return: A Response object based reply """ # Create a object to create a reply. response = Response() # Set the text of the reply. response.text = "Here's a fun little meme." # Craft a URL for a file to attach to message u = "https://sayingimages.com/wp-content/uploads/" u = u + "aaaaaalll-righty-then-alrighty-meme.jpg" response.files = u return response # An example command the illustrates using details from incoming message within # the command processing. def current_time(incoming_msg): """ Sample function that returns the current time for a provided timezone :param incoming_msg: The incoming message object from Teams :return: A Response object based reply """ # Extract the message content, without the command "/time" timezone = bot.extract_message("/time", incoming_msg.text).strip() # Craft REST API URL to retrieve current time # Using API from http://worldclockapi.com u = "http://worldclockapi.com/api/json/{timezone}/now".format( timezone=timezone ) r = requests.get(u).json() # If an invalid timezone is provided, the serviceResponse will include # error message if r["serviceResponse"]: return "Error: " + r["serviceResponse"] # Format of returned data is "YYYY-MM-DDTHH:MM<OFFSET>" # Example "2018-11-11T22:09-05:00" returned_data = r["currentDateTime"].split("T") cur_date = returned_data[0] cur_time = returned_data[1][:5] timezone_name = r["timeZoneName"] # Craft a reply string. reply = "In {TZ} it is currently {TIME} on {DATE}.".format( TZ=timezone_name, TIME=cur_time, DATE=cur_date ) return reply # Create help message for current_time command current_time_help = "Look up the current time for a given timezone. " current_time_help += "_Example: **/time EST**_" # Set the bot greeting. bot.set_greeting(greeting) # Add new commands to the box. bot.add_command("/dosomething", "help for do something", do_something) bot.add_command( "/demo", "Sample that creates a Teams message to be returned.", ret_message ) bot.add_command("/time", current_time_help, current_time) # Every bot includes a default "/echo" command. You can remove it, or any # other command with the remove_command(command) method. bot.remove_command("/echo") if __name__ == "__main__": # Run Bot bot.run(host="0.0.0.0", port=5000)
ngrok
ngrok will make easy for you to develop your code with a live bot.
You can find installation instructions here: https://ngrok.com/download
-
After you've installed
ngrok
, in another window start the servicengrok http 5000
-
You should see a screen that looks like this:
ngrok by @inconshreveable (Ctrl+C to quit) Session Status online Version 2.2.4 Region United States (us) Web Interface http://127.0.0.1:4040 Forwarding http://this.is.the.url.you.need -> localhost:5000 Forwarding https://this.is.the.url.you.need -> localhost:5000 Connections ttl opn rt1 rt5 p50 p90 2 0 0.00 0.00 0.77 1.16 HTTP Requests ------------- POST / 200 OK
-
Make sure and update your environment with this url:
export TEAMS_BOT_URL=https://this.is.the.url.you.need
-
Now launch your bot!!
python sample.py
Local Development
If you have an idea for a feature you would like to see, we gladly accept pull requests. To get started developing, simply run the following..
git clone https://github.com/hpreston/webexteamsbot
cd webexteamsbot
pip install -r requirements_dev.txt
python setup.py develop
Linting
We use flake 8 to lint our code. Please keep the repository clean by running:
flake8
Testing
Tests are located in the tests directory.
To run the tests in the tests
folder, you can run the following command
from the project root.
coverage run --source=webexteamsbot setup.py test
coverage html
This will generate a code coverage report in a directory called htmlcov
Credits
The initial packaging of the original ciscosparkbot
project was done by Kevin Corbin.
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
History
0.1.0 (2018-11-10)
- First release on PyPI.
0.1.1 (2018-11-10)
- Second release on PyPI.
0.1.2 (2018-11-11)
- Added feature to easily change the bot greeting
- Updated Example bot
sample.py
with better documentation and examples - Allow Response() objects to specify alternative roomId for reply
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for webexteamsbot-0.1.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d0a1544343f419274931057fb09864d4148d279ed7e65ddb069a61b2075f4c6d |
|
MD5 | 39e1c345d4b8de17ccf8c70f1f68815e |
|
BLAKE2b-256 | cdf6fb9e2c0df384c06908e8f8eb6ff399ab8e297559e5f6796bcac8c4db62f6 |