Webhooks for extension service

Webhooks are HTTP methods that Pyrus calls in your service when certain events occur.

GET /pulse

A heartbeat request used to check the availability of your service. It does not contain any parameters. Your server should respond with a 2xx status.

Example request using curl:

curl -X GET \
  https://your-service.com/pulse \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3'

POST /authorize

Used for authorizing in an external system when connecting the extension to a form. The response should contain information about the integration.

Parameters for authorizing with access keys:

credentials — data for authorization based on parameters, specified in the developer's personal account (PA) in the basic settings block of the extension (step 1). An array of objects in the following format:
- code — string. String code of the parameter for authorization via parameters. Maximum length — 50 characters.
- value — string. Value of the authorization parameter. Max length 500 characters.

Returns:

account_id — string. Unique identifier of the extension account in the external system (group ID in VKontakte, bot name in Telegram, etc.). Specified at authorization.
account_name — string. Name of the extension account (bot name in Telegram, group name in VKontakte, etc.). Specified at authorization. Displayed in the extension settings.
error_code — string, optional. Error code.
error — string, optional. Error message.

Example request using curl:

curl -X POST \
  https://your-service.com/authorize \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3' \
  -d '{
    "credentials":[
      {"code":"login", "value":"test@email.com"},
      {"code":"password", "value":"pass123"}
    ]
  }'

Response body:

{
  "account_id": "uniqueID12345",
  "account_name": "Test account"
}

Parameters for authorizing with OAuth 2.0 protocol:

authorization_code — string. Authorization code. Specified after the user completes authorization to obtain a permanent token.
grant_type — string, authorization_code for authorization, refresh_token for token refresh.
client_id — string, value of the client_id field. Filled in when authorizing with OAuth 2.0 protocol in the control panel, in the extension's basic settings block (step 1).
client_secret — string, value of the client_secret field. Filled in when authorizing with OAuth 2.0 protocol in the control panel, in the extension's basic settings block (step 1).
scope — string, value of the scope field. Filled in when authorizing with OAuth 2.0 protocol in the extension's basic settings (step 1).
redirect_uri — string. Always specify the value https://pyrus.com/integrations/oauthorization.

Returns:

account_id — string. Unique identifier of the extension account in the external system (group ID in VKontakte, bot name in Telegram, etc.). Specified at authorization.
account_name — string. Name of the extension account (bot name in Telegram, group name in VKontakte, etc.). Specified at authorization. Displayed in the extension settings.
access_token — string. Authorization token.
refresh_token — string. Refresh token for token refresh.
error_code — string, optional. Error code.
error — string, optional. Error message.

Possible error codes:

no_account — no user with entered credentials found in the external system.
bad_authorization_code — incorrect authorization code.
bad_refresh_token — invalid refresh token.
internal_error — internal server error.

Example request using curl:

curl -X POST \
  https://your-service.com/authorize \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3' \
  -d '{
    "code": "idjfLjV2hc72cA" ,
    "client_id": "384592" ,
    "client_secret": "JnchsYYwbc92Isj" ,
    "scope": "offline_access,profile_settings" ,
    "grant_type": "authorization_code"
  }'

Response body:

{

  "account_id": "uniqueID12345",
  "account_name": "Test account",
  "access_token": "dkfjvviUHMHkakchsb827KDndjg",
  "refresh_token": "UyebcyINsybd72Cbsj21KsAscn"
}

POST /toggle

Used to enable/disable notifications about new events in an external system for the extension account.

Parameters:

credentials — data for authorizing by parameters, specified in the developer's personal account (PA) in the extension's basic settings block (step 1). An array of objects in the form:
code — string code of the parameter for authorizing via parameters. Max length 50 characters.
value — string. Parameter values for authorization. Max length 500 characters.
access_token — string, OAuth token. Specified when authorizing via OAuth 2.0 protocol.
enabled — boolean field. Has a value of true when notifications are enabled and false when disabled.

Returns:

error_code — string, optional. Error code.
error — string, optional. Error message.

Allowed values for the processing request result code:

bad_credentials — user data is outdated, reauthorization is required.
internal_error — internal server error.

Example request via curl:

curl -X POST \
  https://your-service.com/toggle \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3' \
  -d '{
    "credentials":[
      {"code":"login", "value":"test@email.com"},
      {"code":"password", "value":"pass123"}
    ],
    "enabled": true
  }'

POST /event

Notification of an event in a task, in the form to which the extension is connected. Called when a task is created, when fields in the form linked to parameters from the extension are changed, when the responsible person is changed, when the responsible person makes a decision, and when the task is completed. In addition, it is called when a comment is received on the task if the extension settings have the checkbox Track internal events set, or if the comment is sent from another extension that tracks such events.

Parameters:

credentials — data for authorization by parameters, specified in the developer's personal account (PA) in the main settings block of the extension (step 1). An array of objects of the following type:
- code — string code of the parameter for authorizing via parameters. Max length 50 characters.
- value — string. Parameter values for authorization. Max length 500 characters.
access_token — string, OAuth token. Specified when authorizing via OAuth 2.0 protocol.
task_id — number. ID of the task in Pyrus.
event_person — user who triggered the event. Object of the following type:
- user_id — number, user identifier;
- first_name — string, user's first name;
- last_name — string, user's last name;
- work_phone — string, user's work phone;
resolution — string. User's decision. Can take one of the following values:
- approved — task has been approved by user;
- rejected — task was rejected;
- acknowledged— task was viewed;
- later — decision was canceled or task was postponed.
responsible_person — user specified as responsible in the task. Can be empty. Object of the following type:
- user_id — number, user identifier;
- first_name — string, user's first name;
- last_name — string, user's last name;
- work_phone — string, user's work phone.
mappings — values of Pyrus form fields linked to extension parameters. An array of objects of the following type:
- key — string, Pyrus form field code;
- values — string, Pyrus form field value.
event_type — string. Type of event. Can take the following values:
- create — when creating a task;
- close — when closing a task;
- comment — when creating a comment in a task.

Returns:

error_code — string, optional. Error code;
error — string, optional. Error message.

Allowed values for the request processing result code:

bad_credentials — user data is outdated, reauthorization is required;
internal_error — internal server error.

Example request via curl:

curl -X POST \
  https://your-service.com/event \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3' \
  -d '{
    "credentials":[
      {"code":"login", "value":"test@email.com"},
      {"code":"password", "value":"pass123"}
    ],
    "task_id": 223412,
    "event_person": {
      "user_id": "34231",
      "first_name": "Ilya",
      "last_name": "Laserson",
      "work_phone": "+79338762030",
      "resolution": "approved"
    },
    "responsible_person":{
      "user_id": "34231",
      "first_name": "Ilya",
      "last_name": "Laserson",
      "work_phone": "+79338762030"
    },
    "mappings":[
      {"code":"PhoneNumberFrom", "value":"200"},
      {"code":"Subject", "value":"Здравствуйте!"}
    ],
    "event_type": "comment"
  }'

POST /sendmessage

Required when the Online Chat function is enabled.

Called when a comment is created from an external channel in the Pyrus task. The external channel is usually created using the /getmessage method.

When the Send button in an external channel is clicked, a comment is created in the task and the POST sendmessage method is called.

Parameters:

credentials — data for authorizing with parameters, specified in the developer's personal account (PA) in the main settings block of the extension (step 1):
- code — string code of the parameter for authorizing using parameters. Max length 50 characters;
- value — string. Parameter values for authorization. Max length 500 characters.
access_token — string. OAuth token. Specified when authorizing via OAuth 2.0 protocol.
channel_id — string. Unique identifier of the messaging channel in extensions (Telegram chat ID, VKontakte user ID, etc.). Pyrus takes it from the /getmessage request.
message_type — string. Field "Message Type Code", which appears when the online chat function is enabled. Online chats can be connected in the PA in the additional functions connection block (step 2).
message_text — string. Message text. Max length 10000 characters.
attachment_ids — array of numbers. IDs of attachment files. Attachment files can be downloaded using the files/download/{file-id} method.

Returns:

error_code — string, optional. Error code.
error — string, optional. Error message.

Allowed values for message sending result code:

bad_credentials — user data is outdated, re-authorization is required.
account_blocked_by_user — the user has blocked messages from this account.
external_error — failed to send message due to an error in an external system.
internal_error — server internal error.

Example request via curl:

curl -X POST \
  https://your-service.com/sendmessage \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3' \
  -d '{
    "credentials":[
      {"code":"login", "value":"test@email.com"},
      {"code":"password", "value":"pass123"}
    ],
    "channel_id": 87654321,
    "message_type": "message",
    "message_text": "Please, write a review",
    "attachment_ids":[12345, 67890]
  }'

GET /getavailablenumbers

Required when the Telephony function is enabled.

If your extension supports API telephony functions, this request is made after authorization to get all available numbers for call processing. The user will select the numbers from which, and to which, calls will be processed in the form.

Parameters (passed in the query string):

<auth_field_code> — string. Parameter codes and their values for authorizing using the parameters specified in the developer's personal account (PA) in the extension's basic settings block (step 1). Example:

?username=qwe123&access_code=654321

access_token — string. OAuth token. Specified when authorizing with OAuth 2.0 protocol.

Returns:

numbers — array of strings. Numbers available for call processing.
error_code — string, optional. Error code.
error — string, optional. Error message.

Example request using curl:

curl -X GET \
  https://your-service.com/getavailablenumbers?access_token=ds233sdasdlfgoasd \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Pyrus-Extensions-1' \
  -H 'X-Pyrus-Sig: <SIGNATURE>' \
  -H 'X-Pyrus-Retry: 1/3'

Response body:

{
  "numbers": [
    "2043",
    "8 800 111-22-33",
    "support phone"
  ]
}

Webhooks for extension service

GET /pulse

POST /authorize

Parameters for authorizing with access keys:

Parameters for authorizing with OAuth 2.0 protocol:

POST /toggle

POST /event

POST /sendmessage

GET /getavailablenumbers

Was this article helpful?