Creating a new bot

Note: a user with Configuration manager privileges can create and manage bots.

Bots are configured in the Bots section.

To create a bot, click Add bot.

Configure the bot:

• Name: Enter any bot name.
• URL: Enter the address of a page on your website that contains the event handler code. When an event triggers the bot, Pyrus makes a request to this URL address. Only HTTPS addresses are allowed. Click Add.

Pyrus will generate the parameters of a new bot and display them in a popup window:

• Login: A bot login. The format is bot@<guid>.
• ClientId and Security Key are required for API calls. Security Key is used to sign each call and guarantees that the calls are made on Pyrus’s behalf.

You can change the security key value in the Security Key line by clicking Reset. This is useful if you suspect that the current security key is compromised. After you reset the key, the attacker will not be able to get a new token using the old key. At the same time, any previously configured bots will continue to operate.

After the bot is added, it will be available in the Bots tab. To change the configuration of your new bot, visit its profile.

Here you can set Additional rights to the bot. Use Supervisor and Configuration manager privileges.

Specify the following information when setting up the bot in detail.

1. Timezone of the bot so it can receive fields from the task that contain date and time data, with the correct timezone taken into account.

2. Bot locale, which may influence some of the parameters of the way dates are displayed.

3. Data transferred when the bot is called. Using this setting, you can select and transfer all comments along with the task, or only the last comment. The setting helps keep the traffic flow under control when there are too many comments.

   

You can also disable the bot in the Status line.

Configuring a bot

A bot configuration consists of: a URL address for calls, Security Key, ClientId, and Enabled/Disabled parameters.

URL: The address of a page on your website. The page must contain the event handler code. When a bot receives a task, Pyrus sends a request to this address. Only HTTPS addresses are allowed.

Certificate Requirements: The HTTPS certificate must be verifiable. The certificate chain must be traceable to a trusted certification center.

Security Key and ClientId values are used for API calls, and they are generated automatically when the bot is created. Security Key is used to sign each call, guaranteeing that the calls are made on Pyrus’s behalf.

Data Structure

The POST Request

• Body.

  task: A task where the event appeared. The field format is the same as the response from the API request getting a task.

  task_id: The ID number of the task that triggered the event. See the details here.

  access_token: authorization token. A token for the Pyrus API call, which is valid for 5 minutes. During this period, the bot can send requests to Pyrus through PublicAPI using access_token for authorization. If it takes more than 30 seconds to process the call, we recommend returning a 200 code without the body of the request. After completing the calculations, we recommend creating a comment in the task by sending a request for adding a comment through PublicAPI using access_token.

  {
    "task_id":5600,
    "task":{/* task with notes */},
    "access_token":"{token}"
  }
  

• Pyrus-Bot-4: User Agent header. In this case, 4 stands for the protocol version (the same as Pyrus API version).

• X-Pyrus-Sig: An additional header. This value is a string with a signature confirming that the request actually came from Pyrus. To verify this signature, add your Security Key to the request body and calculate* an HMAC digest for the resulting string with the SHA1 secure hash algorithm. Here's an example of signature verification in Python.

• X-Pyrus-Retry: An additional header. The value is either 1/3, or 2/3, or 3/3. The numerator is the attempt count ( starting with 1), the denominator is the total number of attempts available (3). For the first non-repeat request, the value would be 1/3.

Response: HTTP 2XX

If required, the response body can also be specified. The response body has the same structure as the Pyrus API CreateComment request. A header authorization is not required.