Example: creating a bot

This section walks you through developing a bot that supports auto-reply and approval. Also you can download the bot sample and deploy it to heroku. This information will be useful for application developers.

Create a page with an HTTPS address on your website, e.g. https://example.com/autoresponse. This event handler page will receive requests from your Pyrus bot. Add code to the event handler as follows:

1. Verify the signature to make sure that a request really comes from Pyrus. Calculate the request body signature:

   python:

     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())
   

   php:

   strtoupper(hash_hmac("sha1", $response_body_as_string, $security_key))
   

   ruby:

   OpenSSL::HMAC.hexdigest('sha1', security_key, response_body_as_string).upcase
   

   С#:

   public static bool IsSignatureCorrect(string msg, string sig, string secret)
   {
     if (msg is null)
       throw new ArgumentNullException(nameof(msg));
     if (secret is null)
       throw new ArgumentNullException(nameof(secret));
   
     byte[] hashValue;
     using (var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secret)))
     {
       hashValue = hmac.ComputeHash(Encoding.UTF8.GetBytes(msg));
     }
   
     return ToHexString(hashValue) == sig;
   }
   
   private static string ToHexString(IReadOnlyList<byte> hash)
   {
     if (hash == null)
       throw new ArgumentNullException(nameof(hash));
   
     var chArrayLength = hash.Count * 2;
     var chArray = new char[chArrayLength];
   
     for (int i = 0, index = 0; i < chArrayLength; i += 2, index++)
     {
       var b = hash[index];
       chArray[i] = GetHexValue(b / 16);
       chArray[i + 1] = GetHexValue(b % 16);
     }
   
     return new string(chArray);
   }
   
   private static char GetHexValue(int i)
   {
     return i < 10
       ? (char)('0' + i)
       : (char)('A' + i - 10);
   }
   

2. Select author.email value from received task object (see the complete description):

   {
     "id": 5600,
     "text": "New task",
     "create_date": "2016-12-02T11:20:22Z",
     "last_modified_date": "2016-12-02T11:20:22Z",
     "parent_task_id": 0,
     "author": {
       "id": 1731,
       "first_name": "tester",
       "last_name": "papirus",
       "email": "test@pyrus.com"
     },
     "approvals": [[{
       "person": {
           "id": 21913,
           "first_name": "bot",
           "last_name": "papirus",
           "email": "bot@pyrus.com"
         },
         "approval_choice": "waiting"
       }],
       [{
         "person": {
           "id": 1731,
           "first_name": "tester",
           "last_name": "papirus",
           "email": "test@pyrus.com"
         },
       "approval_choice": "waiting"
       }]],
     "comments": [{
       "create_date": "2016-12-02T11:20:22Z",
       "author": {
         "id": 1731,
         "first_name": "tester",
         "last_name": "papirus",
         "email": "test@pyrus.com"
       },
       "approvals_added": [{
         "person": {
           "id": 21913,
           "first_name": "bot",
           "last_name": "papirus",
           "email": "bot@pyrus.com"
         },
         "step": 1
       },
       {
         "person": {
           "id": 1731,
           "first_name": "tester",
           "last_name": "papirus",
           "email": "test@pyrus.com"
         },
         "step": 2
       }],
       "id": 12208
     }]
   }
   

   In the above example author.email = test@pyrus.com.

3. Generate the response body:

   {
     "text": "Hello, test@pyrus.com. This task approved by bot.",
     "approval_choice": "approved"
   }
   

   In this example:

   • text (optional parameter): Comment text. If it is blank, the bot adds an empty text comment.
   • approval_choice (optional parameter): Bot approval option. If no approval is required, the server ignores this parameter.

4. Return the HTTP response '200 ОК' and the body as described above.

   Here is a full example of a bot 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'
       return _prepare_response(body.decode('utf-8'))
   
   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!!!
   

   Now, add the new bot and enter the address of event handler in the URL field (in our example, https://example.com/autoresponse).

   To check out your work, assign a task to the bot in Pyrus with an approval request. Make sure that the task receives the Approved by bot reply, and that bot approval is enabled.