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 5000 calls per 10 minutes for all PublicAPI calls. 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 json
import time
import BaseHTTPServer
import hmac
import hashlib
import base64

HOST_NAME = '127.0.0.1'  # !!!Do not forget to replace the address!!!
PORT_NUMBER = 80 

class Payload(object):
	def __init__(self, j):
		self.__dict__ = json.loads(j)

def toHexValue(i):
	if i < 10 :
		return chr(ord('0') + i) 
	else:
		return chr(ord('A') + i - 10)

def toHexValue(i):
	result = '';
	for ch in hash:
		l = ord(ch) % 16
		h = ord(ch) // 16
		result += ''.join([toHexValue(h), toHexValue(l)])
	return result

def isSignatureCorrect(message, signature, secret):
	return toHex(hmac.new(secret, msg=message, digestmod=hashlib.sha1).digest()) == signature;

class MyHandler(BaseHTTPServer.BaseHTTPRequestHandler):
	def do_POST(s):
		s.send_response(200)
		s.send_header("Content-type", "application/json")
		s.end_headers()
		
		secret = "This-is-bot-secret-key-VtBOEesdOnIcqGaWQeFkWFqyzgdt2PGsZVWBc8h8H0-xU9ux-dN37IjcAqf2pzeqoo5FqdtoH";
		signature = s.headers['x-pyrus-sig']
		message = s.rfile.read(int(s.headers['content-length']))

		req = Payload(message)
		
		if isSignatureCorrect(message, signature, secret):
			s.wfile.write("{\"Id\": %d, \"Text\": \"Hello world\", \"ApprovalChoice\": \"Approved\"}" % req.TaskId)
		else:
			s.wfile.write("signature incorrect")
		
if __name__ == '__main__':
	server_class = BaseHTTPServer.HTTPServer
	httpd = server_class((HOST_NAME, PORT_NUMBER), MyHandler)
	print time.asctime(), "Server Starts - %s:%s" % (HOST_NAME, PORT_NUMBER)
	try:
		httpd.serve_forever()
	except KeyboardInterrupt:
		pass
	httpd.server_close()
	print time.asctime(), "Server Stops - %s:%s" % (HOST_NAME, PORT_NUMBER)

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.