Skip to main content

A Flask based Webex Teams chat bot.

Project description

webexteamsbot

This package makes creating Webex Teams bots in Python super simple.

PyPI version published

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.

  1. You'll need to start by adding your bot to the Webex Teams website.

    https://developer.webex.com/my-apps

  2. Click Create a New App

    add-app

  3. Click Create a Bot.

    create-bot

  4. 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.

    add-bot

  5. Click Add Bot.

  6. On the Congratulations screen, make sure to copy the Bot's Access Token, you will need this in a second.

    enter-details

Installation

Python 3.6+ is recommended. Python 2.7 should also work.

  1. Create a virtualenv and install the module

    python3.6 -m venv venv
    source venv/bin/activate
    pip install webexteamsbot
    

Usage

  1. 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>
    
  2. A basic bot requires very little code to get going.

    import os
    from webexteamsbot import TeamsBot
    
    # 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
    bot = TeamsBot(
        bot_app_name,
        teams_bot_token=teams_token,
        teams_bot_url=bot_url,
        teams_bot_email=bot_email,
    )
    
    
    # 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)
    
    
    # Add new commands to the box.
    bot.add_command("/dosomething", "help for do something", do_something)
    
    
    if __name__ == "__main__":
        # Run Bot
        bot.run(host="0.0.0.0", port=5000)
    
  3. A sample script that shows more advanced bot features and customization is also provided in the repo.

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

  1. After you've installed ngrok, in another window start the service

    ngrok http 5000
    
  2. 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
    
  3. Make sure and update your environment with this url:

    export TEAMS_BOT_URL=https://this.is.the.url.you.need
    
    
  4. 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

0.1.2.1 (2018-11-11)

  • Updated README with a very simple bot example with a link to the full sample.py script

0.1.3.0 (2019-10-03)

  • Adding new features for cards and membership management (Thanks @joshand!)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for webexteamsbot, version 0.1.3.0
Filename, size File type Python version Upload date Hashes
Filename, size webexteamsbot-0.1.3.0-py2.py3-none-any.whl (10.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size webexteamsbot-0.1.3.0.tar.gz (19.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page