Основные концепции
Взаимодействие Pyrus с сервисом расширений основано на механизме вебхуков (запросов от Pyrus к сервису расширения) и методов Extensions API (запросов от сервиса расширения к Pyrus). В зависимости от функционала расширения может использоваться разный набор методов и вебхуков.
Авторизация во внешней системе
При установке расширения в форму пользователь проходит авторизацию во внешней системе. Pyrus поддерживает два способа авторизации: через OAuth 2.0 и ключи доступа.
Если внешняя система поддерживает оба способа авторизации, то реализация через OAuth 2.0 является предпочтительной.
Авторизация по протоколу OAuth 2.0
При авторизации по протоколу OAuth 2.0 у пользователя в браузере открывается новая вкладка со ссылкой для авторизации во внешней системе, указанной на странице основных настроек ЛК в блоке Авторизация по OAuth 2.0. При этом в конец ссылки добавляется дополнительный текстовый параметр state. Этот параметр необходим для дальнейшей авторизации в Pyrus. После успешной авторизации вам необходимо перенаправить пользователя на адрес https://pyrus.com/, где state_string — строка, переданная Pyrus при открытии ссылки для авторизации, а token — код авторизации. Далее Pyrus отправляет на ваш сервис запрос authorize с полученным кодом авторизации. Помимо этого, в теле запроса будут указаны дополнительные поля client_id, client_secret, scope, если они заполнены, параметр redirect_uri со значением https://pyrus.com/integrations/oauthorization и параметр grant_type со значением access_token при авторизации или refresh_token при восстановлении доступа. В теле ответа должен содержаться авторизационный токен, который Pyrus будет отправлять в запросах к вашему сервису и refresh-токен для обновления авторизационного токена. Pyrus обновляет авторизационный токен, если в поле error_code возникает ошибка expired_token в ответе любого из веб-хуков для расширений.
Авторизация по ключам доступа
При авторизации во внешней системе по ключам доступа пользователю предлагается ввести параметры для авторизации на странице основных настроек расширения в блоке Авторизация по параметрам в ЛК. Pyrus отправляет на ваш сервис запрос authorize, в теле которого содержатся введенные пользователем данные. О результатах авторизации Pyrus узнает из ответа.
Типовые сценарии
Расширения Pyrus позволяют интегрироваться с различными видами внешних систем: мессенджеры, соц. сети, телефония, ЭДО и т. д. Для этого Pyrus предоставляет дополнительные функции, которые можно активировать в личном кабинете разработчика при настройке расширения на шаге Обмен данными с формой.
Онлайн-чат
Сценарий Онлайн-чат позволяет добавить внешний канал общения в задаче для двустороннего обмена сообщениями. Для отправки сообщения из внешней системы в Pyrus и обратно будут доступны метод Extensions API /getmessage и вебхук /sendmessage соответственно.
Если внешняя система позволяет начать диалог с пользователем, то необходимо реализовать вебхук /createdialog и задать в настройках сценария набор обязательных для начала диалога полей (например, номер телефона или название аккаунта).
Если внешняя система поддерживает разные источники сообщений от одного пользователя (например, личное сообщение, комментарий под постом и т.д.), то можно добавить эти источники в виде типов сообщений при настройке сценария. Pyrus будет регистрировать сообщения из разных источников в отдельных задачах, а также покажет название источника в заголовке комментария.
При подключении расширения в форму пользователь сможет настроить приветственное сообщение, которое Pyrus будет отправлять во внешний канал при создании задачи.
Телефония
Сценарий Телефония позволяет расширению регистрировать входящие звонки при обращении клиента по телефону в виде задач по форме в Pyrus, а также прикладывать запись разговоров в созданную задачу. Для этого расширению будут доступны методы Extensions API /call и /attachcallrecord.
При подключении расширения пользователь сможет выбрать номера телефонов, звонки на которые должны регистрироваться в задачах по форме. Для этого необходимо реализовать на стороне сервиса расширения обработку вебхука /getavailablenumbers.
Маршрутизация
Сценарий Маршрутизация позволит пользователю при подключении расширения в форму выбрать этапы маршрута, на которых расширение должно быть активно. Это необходимо для расширений, которые однократно обрабатывают форму Pyrus, например, подгружают в форму данные из внешней системы, отправляют документ на подпись, проверяют корректность заполнения полей и т. д. На выбранных этапах Pyrus будет вызывать вебхук /event, который необходимо обработать сервису расширения.
Мониторинг недоступности вашего сервиса
После публикации новой версии расширения (или во время ее тестирования) Pyrus начнет отправлять запросы о действиях пользователя на адрес, указанный на странице основных настроек в личном кабинете разработчика (ЛК). Также Pyrus периодически отправляет запрос pulse для проверки доступности вашего сервиса. Ваш веб-сервис должен отвечать статусом 2xx на все запросы в течение 10 секунд после вызова. Если ваш сервис недоступен или отвечает статусом, отличным от 2хх, Pyrus отправит второй запрос через 11 секунд, а затем третий — через 22 секунды. Номер попытки содержится в заголовке X-Pyrus-Retry. Значение — одно из трех: «1/3», «2/3» или «3/3». В числителе номер попытки, начиная с единицы, а в знаменателе — количество попыток (три попытки). Для первого вызова, который не является повтором, ставится значение «1/3». Если за три попытки связаться не удалось, Pyrus обновит статус опубликованной версии расширения на Технический сбой, что приведет к невозможности ее использования. Об этом вы получите уведомление по электронной почте, указанной в общих настройках расширения. Pyrus будет продолжать отправлять на ваш сервис heartbeat-запрос pulse. Как только ваш сервис станет доступен, Pyrus обновит статус версии расширения на Опубликована.
Включение/отключение расширения
Пользователь может приостановить работу подключенного к форме расширения, чтобы не получать уведомления о новых событиях. При этом Pyrus отправляет на ваш сервис запрос POST toggle. Если работа аккаунта приостановлена, Pyrus будет игнорировать все уведомления о новых событиях для данного аккаунта, поэтому стоит прекратить отправку уведомлений о новых событиях для отключенных аккаунтов, чтобы избежать блокировки из-за исчерпания лимита запросов.