Bots are virtual Pyrus users that can be directed to perform tasks or approve forms. Each bot has an associated program (a web service) that performs a specific function. When a task or form is routed to the bot, Pyrus invokes a call to the web service. The bot performs its action and then returns the result to Pyrus. Pyrus stores the results in comment or form fields and forwards the task to the next workflow stage (or returns it to a previous stage).

Bots help when you need to address a workflow task or ensure integration with your company’s internal systems. Possible scenarios include:

• Sending a custom notification to a user. When a request has passed a certain stage of approval (for example, a payment was approved), it goes to the bot. The people who want to see the task through — say, your vendor — will receive an SMS or email notification. Next, a third-party application, such as online payment platform, generates the payment order automatically.
• Checking budget limits. The bot checks the spending limit for the supplier — if the limit is exceeded, the bot reports this and returns the request to the previous stage.
• Preventing duplicate payments. When a request for invoice approval comes to the bot, it queries the register and analyzes the content of the previous requests to look for duplicates. If none are found, the bot approves the request and forwards it to the next participant.

The bot plays whatever part of the workflow you program it to. In this case, it is important to take two limitations into account:

• a bot cannot send a task to another bot (the system will not allow you to do that);
• two bots cannot operate within the same workflow stage.

A bot is a special type of Pyrus account. You can create one from the Bots tab in User Management. A company can create up to 100 bots. The number of bot calls is limited: you can make 500 calls per 10 minutes. A bot account’s payment terms are identical to those of a regular employee account.

Each bot is given a name to serve as a unique identifier, like bot@892ccfa1c8360e2e8309. You cannot log into the system through a web interface or mobile app using this login name; it merely lets you to get a token and call the Pyrus API using the bot’s credentials.

You need to develop a handler app for each bot, and host these apps on your server. When a task is delivered to a bot’s Inbox, it sends a request to the event handler.

Here is an example of bot code written in Python.

import hmac
import hashlib
import json
from flask import Flask
from flask import request

app = Flask(__name__)

@app.route("/", methods=['GET', 'POST'])
def index():
    body = request.data
    signature = request.headers['x-pyrus-sig']
    secret = 'This-is-bot-secret-key-VtBOEesdOnIcqGaWQeFkWFqyzgdt2PGsZVWBc8h8H0-xU9ux-dN37IjcAqf2pzeqoo5FqdtoH'

    if _is_signature_correct(body, secret, signature):
        return _prepare_response(body.decode('utf-8'))

def _is_signature_correct(message, secret, signature):
    secret = str.encode(secret)
    digest = hmac.new(secret, msg=message, digestmod=hashlib.sha1).hexdigest()
    return hmac.compare_digest(digest, signature.lower())

def _prepare_response(body):
    task = json.loads(body)["task"]
    task_author = task["author"]["email"]
    return "{{\"text\": \"Hello, {}. This task approved by bot.\", \"approval_choice\": \"approved\"}}".format(task_author)

if __name__ == "__main__":
    app.run("127.0.0.1", 5001) # !!!Do not forget to replace the address!!!

Pyrus uses the POST method to send an HTTPS request to your bot. Your bot must respond to the request with the 2XX status within 60 seconds of this call. If the bot server is unavailable or responds with any other status, Pyrus sends a second request in 61 seconds and a third one in 122 seconds. You can see the number of attempts in X-Pyrus-Retry, the additional header of the request. If Pyrus fails to communicate within three attempts, it will stop trying to call the bot until someone comments on the task. Then Pyrus will carry out another three attempts.

To create and configure bots, you need to have the right to configuration integrations and edit catalogs in Pyrus.