Errbot Plugin Development

Errbot plugins are fairly easy to develop. Before we get to developing one, lets create a condusive environment for the errbot plugin development. This document will guide you on how to setup errbot environment for plugin development, how to publish your plugins, and some gotchas.

NOTE: This document will not go beyond a hello world example.

Create Virtualenv

First ensure the virtualenv library is installed, otherwise install it.

$ sudo pip install -U virtualenv

Create an errbot virtualenv with python3 as the default python for the environment.

$ virtualenv -p python3 errbot

The above command should create an errbot directory in the location where your run the command from, thats your virtualenv directory. Start using this virtual environment for your errbot plugin development

$ cd errbot
$ source bin/activate

Now you are ready with the virtualenv for your errbot plugin development.

Errbot Prepare

From this point on all the commands are run from inside the virtualenv. First of all you would need to install errbot package.

(errbot) $ pip install errbot

This should install errbot(version: 5.0.1) into virtualenv.

Errbot Init to Text Mode

Now that you have you virtualenv, and errbot installed in it, you could initialize an errbot project. First create an test directory, and then initialize.

(errbot) $ mkdir errtest
(errbot) $ cd errtest
(errbot) $ errbot -i . 

The directory should look like this.

(errbot) $ tree .
.
├── config.py
├── data
└── plugins
    └── err-example
        ├── example.plug
        └── example.py

3 directories, 3 files

You should be ready to launch the errbot in text mode with a very basic configuration(config.py) file.

(errbot) $ errbot -T                                                                                                                                                                           samuel@samuel-HP-ProBook-430-G3
12:46:37 INFO     errbot.cli                Config check passed...
12:46:37 INFO     errbot.cli                Selected backend 'Text'.
...
...
12:46:38 DEBUG    errbot.plugins.Help       Logger for plugin initialized...
12:46:38 DEBUG    errbot.plugins.Backup     Logger for plugin initialized...
12:46:38 DEBUG    errbot.plugins.Health     Logger for plugin initialized...
12:46:38 DEBUG    errbot.bootstrap          Start serving commands from the text backend

 >>> 

Go ahead the type in !help to see the builtin commands,

 >>> !help
All commands

 Backup
 Backup related commands.
• !backup - Backup everything.
 ChatRoom
 This is a basic implementation of a chatroom
• !room invite - Invite one or more people into a chatroom.
• !room join - Join (creating it first if needed) a chatroom.
• !room leave - Leave a chatroom.
• !room create - Create a chatroom.
...
...
• !whoami - A simple command echoing the details of your identifier. Useful to debug iden...
• !log tail - Display a tail of the log of n lines or 40 by default
• !render test - Tests / showcases the markdown rendering on your current backend
• !history - display the command history

>>>

The Example Plugin

If you explore your errtest directory you should find an example plugin at plugins/example directory. In this directory you should find two files,

(errbot) $ cd plugins/err-example
(errbot) $ ls -l
total 12
-rw-rw-r-- 1 samuel samuel  145 Aug  8 12:42 example.plug
-rw-rw-r-- 1 samuel samuel  668 Aug  8 12:42 example.py
drwxrwxr-x 2 samuel samuel 4096 Aug  8 12:46 __pycache__

example.plug and example.py. The example.plug is the plugin metadata file, this describes about plugin, and which module to load for this plugin(defined by the Module in the plug file).

[Core]
Name = Example
Module = example

[Documentation]
Description = This is a simple plugin example to get you started.

[Python]
Version = 2+

Your First Plugin

Let us create a plugin that will tell of the http url is available(200) or not(anything else). First create directory in the plugins directory(plugins), call it httping( missed p intentionally).

(errbot)$ mkdir httping
(errbot)$ cd httping

For the httping plugin you would need to create three files, httping.plug, httping.py and requirements.txt.

(errbot)$ touch {httping.plug,httping.py,requirements.txt}

Since you would be using Requests library, we neeed to put that in the requirements.txt file. Open the file and put the following line in it and save.

requests

Install the requests library by running the fillowing command

(errbot)$ pip install -r requirements.txt

The need of requirements.txt is to tell errbot the dependencies for this plugin. Next you should write up your httping.plug file with appropriate data. Open the file and put text in there and save.

[Core]
Name = Httping
Module = httping

[Documentation]
Description = Ping http endpoints for availability

[Python]
Version = 2+

You can now write the python module for httping. Open the httping.py and fill in the following the code.

from errbot import BotPlugin, arg_botcmd, botcmd
import requests

class Httping(BotPlugin):

    @botcmd
    def hello_httping(self, msg, args):
        return 'Hi there! Welcome to httping'

    @arg_botcmd('url', type=str)
    def httping(self, msg, url=None):
        """
        Sends a HTTP GET request to the url and returns the status code
        """
        r = requests.get(url)
        return r.status_code

Notice the @botcmd and @arg_botcmd decorators, they convert the function they decorate into bot commands, hello_httping and httping respectively. Go back to the errtest directory, and fire up errbot in Text mode, to test your plugin.

(errbot)$ cd ../..
(errbot)$ errbot -T
15:33:06 INFO     errbot.cli                Config check passed...
15:33:06 INFO     errbot.cli                Selected backend 'Text'.
...
...
15:33:06 INFO     errbot.plugin_manager     Installing packages from '/virtualenv/errbot/errtest/plugins/httping/requirements.txt'.
Requirement already satisfied: requests in /virtualenv/errbot/lib/python3.5/site-packages (from -r /virtualenv/errbot/errtest/plugins/httping/requirements.txt (line 1))
Requirement already satisfied: idna<2.6,>=2.5 in /virtualenv/errbot/lib/python3.5/site-packages (from requests->-r /virtualenv/errbot/errtest/plugins/httping/requirements.txt (line 1))
Requirement already satisfied: urllib3<1.23,>=1.21.1 in /virtualenv/errbot/lib/python3.5/site-packages (from requests->-r /virtualenv/errbot/errtest/plugins/httping/requirements.txt (line 1))
Requirement already satisfied: certifi>=2017.4.17 in /virtualenv/errbot/lib/python3.5/site-packages (from requests->-r /virtualenv/errbot/errtest/plugins/httping/requirements.txt (line 1))
Requirement already satisfied: chardet<3.1.0,>=3.0.2 in /virtualenv/errbot/lib/python3.5/site-packages (from requests->-r /virtualenv/errbot/errtest/plugins/httping/requirements.txt (line 1))
...
...
15:33:07 DEBUG    errbot.plugins.Health     Logger for plugin initialized...
15:33:07 DEBUG    errbot.bootstrap          Start serving commands from the text backend

 >>> 

Notice that your errbot plugin manager picked up the httping and loaded it. Just type !help Httping,

 >>> !help Httping
Httping
 Ping http endpoints for availability
• !hello httping - (undocumented)
• !httping - usage: httping [-h] url

You could now command your bot to act. Give it try.

>>> !hello httping
Hi there! Welcome to httping

>>> !httping https://google.com
200

>>> !httping https://freshdesk.com
200
>>> !httping https://freshdesk.com/zzzz

>>> 404

Congratulations, you have created a new plugin.

Be Useful, Publish Httping

Now that you have developed httping plugin for errbot, it cannot be doing anything sitting idle in your virtualenv. Publish it to the world by creating a github repo called err-httping(name is your choice, I prefer to prefix the bot plugins err-).

Before you push your code to your repository, create README.md with text on what your plugin will do. In your plugin directory.

(errbot) $ cd plugins/httping
(errbot) $ git init .
(errbot) $ git add .
(errbot) $ git commit -m "Initial commit of errbot httping plugin" 
[master (root-commit) 0e543ff] Initial commit of errbot httping plugin
 4 files changed, 28 insertions(+)
 create mode 100644 README.md
 create mode 100644 httping.plug
 create mode 100644 httping.py
 create mode 100644 requirements.txt
(errbot) $ ### Time to add the remote repo, choose yours :)###
(errbot) $ git remote add origin git@github.com:samof76/err-httping.git
(errbot) $ git push -u origin master

So here is my Httping repo, use that as a refernce.

Gotchas

Do not share any secrets through plugins, you could use documentation provided here to pass the configuration across.

Take stock of all your plugin dependencies(python packages) and list them in the requirements.txt file, even missing one would fail your plugin installation.

Graphical outputs like images, cards etc., do not work in Text mode so its better to create two HipChat accounts(one for yourself and other for the bot), and test out. So there will be a document on how to do that as well.

Show Comments