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

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

Чтобы убедиться в том, что запрос был отправлен Pyrus, а не кем-то другим, в запросах присутствует заголовок X-Pyrus-Sig, в значении которого указывается подпись запроса. Для проверки подписи необходимо к телу запроса добавить секретный ключ расширения, вычислить для получившейся строки HMAC-дайджест с использованием алгоритма SHA1 и сравнить его со значением в заголовке X-Pyrus-Sig. Примеры реализации проверки подписи на различных языках программирования можно посмотреть здесь.

GET /pulse

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

Пример запроса через 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

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

По ключам доступа

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

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

Возвращает:

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

Пример запроса через 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"}
    ]
  }'

Тело ответа:

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

По протоколу OAuth 2.0

Параметры при авторизации по протоколу 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 — строка, необязательная. Сообщение об ошибке.

Пример запроса через 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"
  }'

Тело ответа:

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

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

no_account — во внешней системе не найден пользователь с такими учетными данными.
bad_authorization_code — неправильный код авторизации.
bad_refresh_token — неверный refresh токен.
internal_error — внутренняя ошибка сервера.

POST /toggle

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

Параметры:

account_id — строка. Уникальный идентификатор аккаунта расширения во внешней системе.
credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). Массив объектов вида:
- code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.
- value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.
access_token — строка, OAuth-токен. Указывается при авторизации по протоколу OAuth 2.0.
enabled — булево поле. Имеет значение true при включении уведомлений и значение false при отключении.
deleted — булево поле. Имеет значение true, когда интеграция удалена из формы.

Возвращает:

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

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

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

Пример запроса через 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 '{
    "account_id" = "d3d2f5e1-c61a-4cf8-ae5e-af9820cbc87a",
    "credentials":[
       {"code":"login", "value":"test@email.com"},
       {"code":"password", "value":"pass123"}
    ],
    "enabled": true,
    "deleted": false
  }'

POST /event

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

Параметры:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). Массив объектов вида:
- code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.
- value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.
account_id — строка. Уникальный идентификатор аккаунта интеграции во внешней системе или в Pyrus в случае, если расширение подключается без авторизации.
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.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. Внешний канал, как правило, создается методом /getmessage.

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

Параметры запроса:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1):
- code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.
- value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.
access_token — строка. OAuth токен. Указывается при авторизации по протоколу OAuth 2.0.
channel_id — строка. Уникальный идентификатор канала для сообщений в расширения (Id чата в телеграм, Id пользователя ВКонтакте и т. д.). Pyrus берет его из запроса /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.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]
  }'

POST /createdialog

Используется для того, чтобы начать чат с клиентом прямо из задачи Pyrus первыми, не ожидая входящего сообщения от него.

Для инициации чата необходимо:

В настройках расширения в личном кабинете разработчика включить функцию Онлайн-чат и выбрать поля для чата — набор доступных расширению полей формы, которые необходимы для начала диалога (например, номер телефона или название аккаунта).
Подключить расширение к форме и настроить сопоставление выбранных полей с формой.
Как только в задаче будут заполнены все необходимые для начала общения поля, в сервис расширения отправится запрос POST /createdialog. В ответ на запрос сервис расширения должен вернуть channel_id и channel_name, после чего в задаче появится внешний канал для общения с клиентом.

Параметры запроса:

credentials — данные для авторизации по параметрам, указываются в личном кабинете разработчика в блоке основных настроек расширения. Массив объектов:
- code — строковый код параметра для авторизации по параметрам. Максимальная длина — 50 символов.
- value — строка. Значения параметра для авторизации. Максимальная длина — 500 символов.
access_token — строка. OAuth токен. Указывается при авторизации по протоколу OAuth 2.0.
mappings — данные полей инициализации диалога. Массив объектов вида:
- key — строка, код поля формы Pyrus.
- value — строка, значение поля формы Pyrus.
account_id — строка. Идентификатор подключенного пользователем аккаунта.

Возвращает:

channel_id — строка, обязательный параметр. Уникальный идентификатор канала для сообщений в расширении (Id чата в телеграм, Id пользователя ВКонтакте и т.д.). В дальнейшем Pyrus берет его для обработки запроса /getmessage и отправки сообщения во внешний сервис с помощью запроса sendmessage.
channel_name — строка, обязательный параметр. Название чата, которое отображается в окне выбора внешнего канала в задаче.
message_type — строка, необязательный параметр. Поле “Код типа сообщения”, который появляется при включенной функции онлайн-чатов. Не более 100 символов.
error_code — строка, необязательный параметр. Код ошибки.
error — строка, необязательный параметр. Сообщение об ошибке.

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

curl -X POST \
  https://your-service.com/createdialog \
  -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":"api_key", "value":"test@email.com"},
      {"code":"password", "value":"pass123"}
    ],
    "mappings": [
		{"code":"PhoneNumberFrom", "value":"79999999999"},
		{"code":"SenderEmail", "value":"test@email.com"}
	],
	"account_id": "uniqueID12345"
  }'

Тело ответа:

{
	"channel_id": "87654321",
	"channel_name": "Ivan Ivanov",
	"message_type": "Telegram"
}

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

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

GET /getavailablenumbers

Необходимо реализовать при включенной функции Телефония

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

Параметры (передаются в query string):

<auth_field_code> — строка. Коды параметров и их значения для авторизации по параметрам, которые были указаны в личном кабинете разработчика (ЛК) в блоке основных настроек расширения (шаг 1). Пример:
```
?username=qwe123&access_code=654321
```
access_token — строка. OAuth токен. Указывается при авторизации по протоколу OAuth 2.0.

Возвращает:

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

Пример запроса через 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'

Тело ответа:

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

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

GET /pulse

POST /authorize

По ключам доступа

По протоколу OAuth 2.0

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

POST /toggle

POST /event

POST /sendmessage

POST /createdialog

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

GET /getavailablenumbers

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