Вебхуки для сервиса расширения
Вебхуки — это HTTP-методы, которые Pyrus вызывает в вашем сервисе при наступлении определенных событий.
GET /pulse
Heartbeat-запрос, который используется для проверки доступности вашего сервиса. Не содержит параметров. Ваш сервер должен ответить статусом 2хх.
Пример запроса через curl:
curl -X GET \ https://your-service-adress.com/pulse \ -H 'User-Agent: Pyrus-Extensions-1' \ -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-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"}
]
}'
Тело ответа:
{
"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-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"
}'
Тело ответа:
{
"account_id": "uniqueID12345",
"account_name": "Test account",
"access_token": "dkfjvviUHMHkakchsb827KDndjg",
"refresh_token": "UyebcyINsybd72Cbsj21KsAscn"
}
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-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
Уведомление о событии в задаче по форме, к которой подключено расширение. Вызывается при создании задачи, в случае изменения полей формы, привязанных к параметрам из расширения, при смене ответственного, при принятии ответственным какого-либо решения, а также при завершении задачи. Кроме того, вызывается при получении комментария к задаче в случае, если в настройках расширения установлена галочка Отслеживать внутренние события, либо если комментарий отправлен из другого расширения, в котором осуществляется такое отслеживание.
Параметры:
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-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
Вызывается при создании комментария из внешнего канала в задаче 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-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
Если ваше расширение поддерживает функции 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-Extensions-1' \ -H 'X-Pyrus-Sig: <SIGNATURE>' \ -H 'X-Pyrus-Retry: 1/3'
Тело ответа:
{
"numbers": [
"2043",
"8 800 111-22-33",
"support phone"
]
}