Tutorial
integrations:bots:how-to

How to create a Pyrus bot

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

A company can create up to 100 bots. The number of bot calls is unlimited. Payment terms for a bot account are identical to a regular employee account. But since it is a special account, it is created on the Bots tab in User Management section. It is listed as a non-activated user. Your company’s supervisor (the person who has created your organization account in Pyrus) can add and set up bots.

You choose a name for each bot. A unique invalid email address is generated as a login. API calls can be made from a bot account, but you cannot log into the system under such an account.

You need to develop a handler app for each bot and post it on your site. When a task is delivered to a bot’s Inbox, it sends a request to the event handler. After that the app starts: it can send an SMS message, an email, or perform other actions that you programmed.

A bot sends HTTPS requests using the POST method. You server must respond to a bot request with the 2XX status within 60 sec. If the server is unavailable, or responds with any other status, Pyrus sends a second request in 61 sec, and a third in 122 sec. The attempt count is included in the optional request header.

Configuring a Bot

A bot configuration includes: URL address, Security Key, ClientId, and the Enabled/Disabled parameters. URL: A web page address on your site. The page contains the event handler code. When a bot receives a task, Pyrus sends a request to this address. Only HTTPS addresses are supported. Certificate Requirements: The HTTPS certificate must be verifiable. The certificate chain must be traceable to a trusted certification center. The Security Key and ClientId values are generated automatically when the bot is created. They are used for API calls. The Security Key is used to sign each request and guarantees that the requests come from Pyrus.

Data Structure

The POST Request

  • Body. TaskNote full description. The data structure as a Notes array element within the TaskWithNotes object, which returns the GetTask API method with extra properties in the Note Json object: UserId (the bot user ID) and TaskId (the task that triggered the event). See the details here.
  • Pyrus-Bot-3 User Agent. 3 stands for the protocol version (same as the Public API version).
  • X-Pyrus-Sig optional header. The value is a hexadecimal Security Key signature of the URL string. The signature is calculated as a HMAC digest with the SHA1 secure hash algorithm.
  • X-Pyrus-Retry optional header. There are three values available: 1/3, 2/3, or 3/3. The numerator is the attempt count (the first number is 1), the denominator is the total number of attempts available (three). For the first non-repeat request the value would be 1/3.

Response: HTTP 2XX The response body can also be specified if required. The response body has the same structure as the Public API CreateComment request. A header authorization is not required.

Have any questions?

CONTACT US