Вебхуки для сервиса расширения

Вебхуки — это HTTP-методы, которые Pyrus вызывает в вашем сервисе при наступлении определенных событий.

GET pulse

Heartbeat-запрос, который используется для проверки доступности вашего сервиса. Не содержит параметров. Ваш сервер должен ответить статусом 2хх.

Пример запроса через curl:

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

POST authorize

Используется для авторизации во внешней системе при подключении расширения к форме. В ответе должны содержаться информация об интеграции.

Параметры при авторизации по ключам доступа:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). Массив объектов вида:

code — строка. строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.

value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.

Возвращает:

account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе (ID группы в ВКонтакте, имя бота в Telegram итд). Указывается в случае успешной авторизации.
account_name — строка. Название аккаунта расширения (имя бота в Telegram, название группы ВКонтакте и т.д.). Указывается в случае успешной авторизации. Отображается в настройках расширения.
error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке.

Пример запроса через curl:

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

Тело ответа:

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

Параметры при авторизации по протоколу OAuth 2.0:

authorization_code — строка. Код авторизации. Указывается после прохождения пользователем авторизации для получения постоянного токена;

grant_type — строка, authorization_code при авторизации, refresh_token при обновлении авторизационного токена;

client_id — строка, значение поля client_id. Заполняется при авторизации по протоколу OAuth 2.0 в ЛК, в блоке основных настроек расширения (шаг 1);

client_secret — строка, значение поля client_secret. Заполняется при авторизации по протоколу OAuth 2.0 в ЛК, в блоке основных настроек расширения (шаг 1)

scope — строка, значение поля scope. Заполняется при авторизации по протоколу OAuth 2.0 в основных настройках расширения (шаг 1).

redirect_uri — строка. Всегда указывается значение https://pyrus.com/integrations/oauthorization.

Возвращает:

account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе (ID группы в ВКонтакте, имя бота в Telegram и т.д). Указывается в случае успешной авторизации.

account_name — строка. Название аккаунта расширения (имя бота в Telegram, название группы ВКонтакте и т.д.). Указывается в случае успешной авторизации. Отображается в настройках расширения.

access_token — строка. Токен авторизации.

refresh_token — строка. Refresh-токен для обновления токена авторизации.

error_code — строка, необязательная. Код ошибки.

error — строка, необязательная. Сообщение об ошибке.

Возможные коды ошибок:

no_account — во внешней системе не найден пользователь с такими учетными данными.

bad_authorization_code — неправильный код авторизации.

bad_refresh_token — неверный refresh токен.

internal_error — внутренняя ошибка сервера.

Пример запроса через curl:

curl -X POST \
https://your-service-adress.com/authorize \
-H 'Content-Type: application/json' \
-H 'User-Agent: Pyrus-Bot-4' \
-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" ,
}'

Тело ответа:

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

GET getavailablenumbers

Если ваше расширение поддерживает функции API-телефонии, этот запрос вызывается после авторизации для получения всех доступных номеров для обработки звонков. Пользователь выберет номера, звонки с которых и на которые будут обрабатываться в форме.

Параметры:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). .

Массив объектов вида:

code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.

value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.

access_token — строка. OAuth токен. Указывается при авторизации по протоколу OAuth 2.0.

Возвращает:

numbers — массив строк. Номера, доступные для обработки звонков.
error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке.

Пример запроса через curl:

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

Тело ответа:

{
"numbers":[ 2043, 2044, 2058]
}

POST sendmessage

Вызывается при создании комментария из внешнего канала в задаче Pyrus. Внешний канал, как правило, создается методом integrations/getmessage.

При нажатии кнопки Отправить будет создан комментарий в задаче и вызван метод POST sendmessage.

Параметры:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1):

code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.

value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.

access_token — строка. OAuth токен. Указывается при авторизации по протоколу OAuth 2.0.
channel_id — строка. Уникальный идентификатор канала для сообщений в расширения (Id чата в телеграм, Id пользователя ВКонтакте и т.д.). Pyrus берет его из запроса integrations/getmessage.
message_type — строка. Поле "Код типа сообщения", который появляется при включенной функции онлайн-чатов. Онлайн-чаты можно подключить в ЛК в блоке подключения дополнительных функций (шаг 2).
message_text — строка. Текст сообщения. Максимальная длина — 10000 символов.
attachment_ids — массив чисел. ID файлов вложений. Файл вложений можно скачать с помощью метода files/download/{file-id}.

Возвращает:

error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке.

Допустимые значения кода результата отправки сообщения:

bad_credentials — данные пользователя устарели, требуется повторная авторизация.
account_blocked_by_user — пользователь заблокировал прием сообщений от данного аккаунта.
external_error — не удалось отправить сообщение из-за ошибки во внешней системе.
internal_error — внутренняя ошибка сервера.

Пример запроса через curl:

curl -X POST \
https://your-service-adress.com/sendmessage \
-H 'Content-Type: application/json' \
-H 'User-Agent: Pyrus-Bot-4' \
-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 ]
}'

POST toggle

Используется для включения/отключения уведомлений о новых событиях во внешней системе для аккаунта расширения.

Параметры:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). Массив объектов вида:

code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.

value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.

access_token — строка, OAuth-токен. Указывается при авторизации по протоколу OAuth 2.0.
enabled — булево поле. Имеет значение true при включении уведомлений и значение false при отключении.

Возвращает:

error_code — строка, необязательная. Код ошибки.
error — строка, необязательная. Сообщение об ошибке.

Допустимые значения кода результата обработки запроса:

bad_credentials — данные пользователя устарели, требуется повторная авторизация.
internal_error — внутренняя ошибка сервера.

Пример запроса через curl:

curl -X POST \
https://your-service-adress.com/toggle \
-H 'Content-Type: application/json' \
-H 'User-Agent: Pyrus-Bot-4' \
-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

Уведомление о событии в задаче по форме, к которой подключено расширение. Вызывается при создании задачи, в случае изменения полей формы, привязанных к параметрам из расширения, при смене ответственного, при принятии ответственным какого-либо решения, а также при завершении задачи. Кроме того, вызывается при получении комментария к задаче в случае, если в настройках расширения установлена галочка Отслеживать внутренние события, либо если комментарий отправлен из другого расширения, в котором осуществляется такое отслеживание.

Параметры:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). Массив объектов вида:

code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.

value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.

access_token — строка, OAuth-токен. Указывается при авторизации по протоколу OAuth 2.0.
task_id — число. ID задачи в Pyrus.
event_person — пользователь, вызвавший событие. Объект вида:

user_id — число, идентификатор пользователя;

first_name — строка, имя пользователя;

last_name — строка, фамилия пользователя;

work_phone — строка, рабочий телефон пользователя;

resolution — строка. Принятое пользователем решение. Может принимать одно из следующих значений:
- approved — пользователь утвердил задачу;
- rejected — задача была отклонена;
- acknowledged — задача просмотрена;
- later — решение отменено или задача была отложена.
responsible_person — пользователь, указанный ответственным в задаче. Может быть пустым. Объект вида:

user_id — число, идентификатор пользователя;

first_name — строка, имя пользователя;

last_name — строка, фамилия пользователя;

work_phone — строка, рабочий телефон пользователя.

mappings — значения полей формы Pyrus, привязанных к параметрам расширения. Массив объектов вида:

key — строка, код поля формы Pyrus;

value — строка, значение поля формы Pyrus.

event_type — строка. Тип события. Может принимать следующие значения:
- create — при создании задачи;
- close — при закрытии задачи;
- comment — при создании комментария в задаче.

Возвращает:

error_code — строка, необязательная. Код ошибки;

error — строка, необязательная. Сообщение об ошибке.

Допустимые значения кода результата обработки запроса:

bad_credentials — данные пользователя устарели, требуется повторная авторизация;
internal_error — внутренняя ошибка сервера.

Пример запроса через curl:

curl -X POST \
https://your-service-adress.com/event \
-H 'Content-Type: application/json' \
-H 'User-Agent: Pyrus-Bot-4' \
-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"
}'

Вебхуки для сервиса расширения

GET pulse

POST authorize

GET getavailablenumbers

POST sendmessage

POST toggle

POST event

Была ли эта статья полезной?