How Pyrus interacts with the extension service

Pyrus interacts with the extension service via webhooks (requests from Pyrus to the extension service) and Extensions API methods (requests from the extension service to Pyrus). Depending on the extension's functionality, different sets of methods and webhooks may be used.

Access to Extensions API

Extensions API methods are available at https://extensions.pyrus.com/v1/. To authorize requests, you need to make a POST token request and obtain an access token. The token you receive must be specified in the HTTP Authorization header for each API request:

Authorization: Bearer gAAAAA15vmSeoj*******

The token has a limited validity period, so your application should be able to re-authenticate if the token is revoked. The authorization token may be revoked in the following cases:

• the token has expired;
• the secret key of your extension has been revoked by the Pyrus administrator or security service. If this happens, all issued tokens will be revoked.

General requirements

Parameters of POST requests are passed in the request body in JSON format. Parameters of GET requests are passed in the URL and, if special characters are present, they must be escaped using urlencode. All responses are passed in the response body in JSON format. When passing numbers, a period is used as the separator between the integer and decimal parts. Dates are passed in ISO 8601 format. The response from the server always comes with a zero time zone. Empty fields are not returned in the response. In case of an error, the response body should include the fields:

• error — error message;
• error_code — error code string.

In case of an erroneous call, the most appropriate HTTP Status Code is returned.

Signature verification

To ensure that the request was sent by Pyrus and not someone else, the requests contain the X-Pyrus-Sig header, whose value indicates the signature of the request. To verify the signature, you need to add the extension's secret key to the request body, calculate the HMAC digest for the resulting string using the SHA1 algorithm, and compare it to the value in the X-Pyrus-Sig header. Examples of implementing signature verification in different programming languages can be found here.

Authorizing in the external system

When installing the extension, the user must be authorized in an external system. Pyrus supports two methods of authorization — via access keys and via OAuth 2.0 protocol.

Authorizing via access keys

When logging in to an external system via access keys, the user is prompted to enter parameters for authorization on the main settings page of the extension in the Authorization by Parameters block in the Pyrus account. This sends an authorize request to your service, containing the user-entered data. Pyrus learns the authorization results from the response.

Authorizing via OAuth 2.0 protocol

When authorizing via the OAuth 2.0 protocol, a new tab opens in the user's browser with a link for authorization in the external system specified on the main settings page in the Authorization by OAuth 2.0 block in their Pyrus account. An additional text parameter called state is added to the end of the link. This parameter is necessary for further authorization in Pyrus. After logging in successfully, you need to redirect the user to the address https://pyrus.com/integrations/oauthorization?state=<state_string>&code=<token>, where state_string is the string passed by Pyrus when opening the authorization link, and token is the authorization code. Pyrus then sends an authorize request to your service, with the received authorization code. Furthermore, the request body will include additional fields such as client_id, client_secret, scope, if filled, a redirect_uri parameter with the value https://pyrus.com/integrations/oauthorization, and a grant_type parameter with the value authorization_code for authorization or refresh_token for access restoration. The response body should contain an authorization token that Pyrus will use in requests to your service, and a refresh token for updating the authorization token. Pyrus updates the authorization token if the error_code field in the response of any of the webhooks for extensions shows an expired_token error.

Connecting without authorization

The extension can be connected automatically, without specifying authorization credentials. In this case, Pyrus generates an account_id for the extension, which is sent to the extension service in the /event webhook for processing.

Note: when connecting without authorization, the Online Chat and Telephony features will not be available.

Common scenarios

Pyrus extensions allow integration with various types of external systems: messengers, social networks, telephony, EDI, etc.

For this purpose, Pyrus provides additional features that can be activated in the developer's personal account when configuring the extension at the Data Exchange with Form step.

Online Chat

The Online Chat scenario allows adding an external communication channel in a task for two-way messaging. The Extensions API method /getmessage and the /sendmessage webhook will be available for sending messages from the external system to Pyrus and vice versa.

If the external system allows initiating a dialog with the user, the /createdialog webhook must be implemented, and a set of fields required to start a dialog (e.g., phone number or account name) must be specified in the scenario settings.

If the external system supports different message sources from the same user (e.g., direct message, comment on a post, etc.), these sources can be added as message types when configuring the scenario. Pyrus will register messages from different sources in separate tasks and will also display the source name in the comment header.

When connecting the extension to a form, the user will be able to set up a welcome message that Pyrus will send to the external channel when a task is created.

Telephony

The Telephony scenario allows the extension to register incoming calls when a customer contacts via phone as form-based tasks in Pyrus, and also to attach call recordings to the created task.

The Extensions API methods /call and /attachcallrecord will be available for this purpose.

When connecting the extension, the user will be able to select phone numbers for which calls should be registered as tasks. To enable this, the extension service must handle the /getavailablenumbers webhook.

Workflow

The Workflow scenario will allow the user, when connecting the extension to a form, to select the route steps at which the extension should be active.

This is necessary for extensions that process a Pyrus form once, for example, loading data from an external system into the form, sending a document for signing, checking the correctness of field entries, etc.

At the selected steps where approvers are assigned, Pyrus will call the /event webhook, which must be processed by the extension service.

Note: the /event webhook call on the selected step will work correctly only if the 'Track Internal Events' checkbox is enabled in the extension settings (comments, task status changes, transition to the next step, form field changes, and assignee changes).

Accessibility of your service

After publishing a new version of the extension (or when testing it), Pyrus will start sending requests about user actions to the address specified on the main settings page in the developer's personal account (PA). Pyrus also periodically sends a pulse request to check the availability of your service.

Your web service must respond to the call with a 2xx status to all requests within 10 seconds. If your service is unavailable or responds with a status other than 2xx, Pyrus will send a second request after 11 seconds, and then a third one after 22 seconds.

The attempt number is contained in the X-Pyrus-Retry header. The value is one of three: "1/3", "2/3", or "3/3". The numerator is the attempt number, starting from one, and the denominator is the number of attempts (three attempts).

The value "1/3" is set for the first call. If it is not possible to connect in three attempts, Pyrus will update the status of the published extension version to Technical Failure, making it unusable.

You will receive a notification at the email specified in the general extension settings. Pyrus will continue to send heartbeat requests to your service. Once your service becomes available, Pyrus will update the status of the extension version to Published.

Enabling/disabling extension

The user can pause the extension account in order to not receive notifications about new events. In that case, Pyrus sends a POST toggle request to your service. If the account is paused, Pyrus will ignore all notifications about new events for this account, so stop sending notifications for disabled accounts to avoid being blocked due to exceeding the request limit.