Bots are configured on a dedicated tab in User Management. To create a bot, click Add New Bot.

Configure the bot in the popup window:

• Name: Enter any bot name.
• URL: Enter a web address on your website. That page must contain 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 here, 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.

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 in Pyrus API format.
  task_id: The task that triggered the event. See the details here.
  access_token: A token for the Pyrus API call, which is valid for 5 minutes. During this period, the bot immediately returns a 200 code without a comment, calls the external system, and makes the necessary calculations. This may take up to 5 minutes. Next, the bot makes a request with this token to add a comment to the task via PublicAPI.

{
  "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. The value is the signature of the URL line with Security Key in hex format. The signature is calculated as an HMAC digest with the SHA1 secure hash algorithm.
• 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.