Tutorial
integrations:bots:sample

Example: creating a bot

This section shows how to develop a bot. The information is intended for software developers.

Create a HTTPS page on your site. This handler page will receive requests from a Pyrus bot. Add code to the event handler. The code pattern is as follows.

1. Verify the signature to make sure that a request comes from Pyrus.

  • To calculate the request body signature:

php: strtoupper(hash_hmac(“sha1”, $response_body_as_string, $security_key))
ruby: OpenSSL::HMAC.hexdigest(“sha1”, security_key, response_body_as_string).upcase

These functions convert a string request into a UTF-8 byte array and calculate an HMAC digest using the SHA1 secure hash algorithm.

  • Compare it to the X-Pyrus-Sig header to verify that the request has really come from Pyrus. If the headers do not to match, the script is terminated.

2. The Author.Id and TaskId values are retrieved from the received Note object (see the complete description):

  {
      “UserId”: 400,
      “TaskId”: 123456,
      “CreateDate”: “/Date(1447718400000)/”,
      “Author”: {
          “Id”: 300,
          “FirstName”: “John”,
          “LastName”: “Smith”
      },
      “ReassignedTo”: {
          “Id”: 400,
          “FirstName”: “Auto-Response Bot”,
          “LastName”: “”
      },
      “DueDateChanged”: “/Date(1447718400000)/”,
      “ApprovalsAdded”: [[{
          “Id”: 300,
          “FirstName”: “John”,
          “LastName”: “Smith”
      },
      {
          “Id”: 400,
          “FirstName”: “Auto-Response Bot”,
          “LastName”: “”
      }]]
  }

In the above example Author.Id = 300, TaskId = 123456. 3. A reply body is generated:

  {
      “TaskId”: 123456,
      “Text”: “Approved by bot.”, 
      “ApprovalChoice”: “Approved”, 
      “ResponsibleId” : 300  
  }

In this example: TaskId (mandatory parameter): ID of the task to be changed by the bot.
Text (optional parameter): Comment text. If it is blank, the bot adds an empty text comment.
ApprovalChoice (optional parameter): Bot approval option. If no approval is required, the server ignores this parameter.
ResponsibleId (optional parameter): Setting a new assignee for the task to be changed. If it is left blank, the bot remains the task’s assignee.

4. Send back HTTP 200 ОК and the body as shown above.

Now you have to add a new bot in Pyrus on the bot configuration page. Enter the handler address in the URL field.

Have any questions?

CONTACT US