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.

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

You can also disable the bot in the Status line.

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.

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

If you want to block the bot, click Block. When a bot is deleted, it is removed from the list and the corresponding non-activated user is terminated (shown on the Terminated list in Members).

If a blocked bot user is restored, all the bot settings are restored to their previous states. You can block and restore the bot as many times as you want.

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.

• 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.

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.