Вебхуки для сервиса расширения
Вебхуки — это 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:
code — строка. Код авторизации. Указывается после прохождения пользователем авторизации для получения постоянного токена;
refresh_token — строка. Refresh-токен. Указывается при обновлении токена авторизации;
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] }
Тело ответа:
{ "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 — строка. Текст сообщения. Максимальная длина определяется настройками расширения.
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" }'