Как встроить техподдержку прямо в своё приложение: Embedded Support API
Обращение создаётся внутри вашего продукта, ответ возвращается туда же. Разбираем схему доступа, автосоздание учётных записей и подписанные вебхуки.
Любая команда, у которой есть собственный продукт с пользователями, рано или поздно упирается в одну и ту же развилку.
Первый путь — отправить пользователя за помощью наружу: ссылка на портал поддержки, отдельная регистрация, отдельный пароль. Технически это делается за час. Практически — часть людей не доходит. Человек, у которого что-то не получилось прямо сейчас, редко готов заводить вторую учётную запись ради того, чтобы сообщить о проблеме. Обращения не исчезают: они превращаются в молчаливый отток и в сообщения в социальных сетях, куда писать проще.
Второй путь — сделать поддержку внутри приложения. Форма обращения в интерфейсе — это действительно недолго. Проблемы начинаются на следующем шаге. Пользователю нужно видеть статус: приняли, работают, решили. Нужна история переписки, иначе при повторном обращении всё начинается сначала. Нужны уведомления обеим сторонам. Специалистам нужны очереди, приоритеты, сроки реакции. Руководителю — отчётность. Растущей команде — разграничение прав. И каждый из этих пунктов конкурирует за время с основным продуктом, ради которого компания и существует.
Embedded Support API убирает необходимость выбирать. Форма обращения остаётся там, где она и была — в интерфейсе вашего продукта. За ней работает полноценный Service Desk со всем перечисленным. Разрабатывать и поддерживать это самим больше не нужно.
Как устроен доступ
Схема двухуровневая, и это не формальность, а принципиальное решение.
Секретный ключ интеграции живёт только на вашем сервере. Он никогда не попадает в браузер, в мобильное приложение, в исходники клиентской части. Когда пользователю нужно обратиться в поддержку, ваш сервер обменивает этот ключ на короткоживущий токен конкретного пользователя. Именно этот токен и работает в приложении.
Практический смысл простой. Если клиентскую часть удалось скомпрометировать — открыли исходники, перехватили трафик, достали данные из памяти устройства — злоумышленник получает токен одного пользователя с ограниченным сроком жизни. Он не получает доступа к чужим обращениям и не может действовать от имени вашего приложения целиком.
Состояние интеграции проверяется на каждом запросе, а не только в момент выдачи токена. Это важно для сценария отзыва: если вы отключили приложение или перевыпустили ключ, ранее выданные пользовательские токены перестают работать немедленно. Ждать, пока истечёт срок их жизни, не нужно — а значит, при подозрении на утечку у вас есть рычаг, срабатывающий мгновенно.
Время жизни токена настраивается: от пяти минут до суток. Короткий срок безопаснее, длинный удобнее для приложений, где пользователь редко переоткрывает сессию.
Учётные записи создаются сами
Отдельная регистрация в системе поддержки не требуется. Учётная запись заводится автоматически при первом обращении пользователя — по идентификатору, который вы передаёте со своей стороны.
Это работает и для частных лиц, за которыми не стоит юридическое лицо. Исторически системы поддержки строились вокруг компаний-заказчиков: обращение принадлежит организации, права выводятся из членства в ней. Для продуктов с розничной аудиторией такая модель не подходит — и она не навязывается: обращение может принадлежать человеку.
Если важно, чтобы клиентская часть не могла выдать одного пользователя за другого, идентификатор дополнительно подписывается на вашем сервере. Тогда подмена идентификатора в клиенте не даст доступа к чужой переписке.
Ответы возвращаются в приложение
Когда специалист отвечает, событие уходит вебхуком на указанный вами адрес. Каждое событие подписывается криптографически: принимающая сторона проверяет подпись и точно знает, что запрос пришёл от системы поддержки, а не подделан.
Отправляются три типа событий: обращение создано, добавлено сообщение, изменился статус. Этого достаточно, чтобы показать пользователю актуальную картину, не опрашивая систему постоянно.
Журнал доставок виден в карточке интеграции: какие события ушли, какие вернули ошибку, сколько было попыток. Если вебхуки перестали доходить, причина видна сразу — а не выясняется через переписку с технической поддержкой поставщика.
Настройка не требует чтения исходников
Отдельно стоит сказать про то, чего в интеграциях обычно не хватает — про диагностику.
Карточка интеграции проверяет собственную конфигурацию и показывает, что настроено неверно: проект не выбран, форма обращения отключена, форма привязана к другому проекту, у проекта неподходящий тип. Это видно администратору в интерфейсе, до того как разработчик на другой стороне получит отказ.
Ответы API устроены так же. Вместо общего «настроено неверно» система называет конкретную причину и конкретный объект, из-за которого запрос не прошёл. По опыту первых интеграций это экономит несколько часов на каждой — ровно то время, которое обычно уходит на переписку в формате «у нас не работает» — «а что именно».
С чего начать
Для подключения нужны три вещи: проект Service Desk, куда будут попадать обращения, форма обращения и созданная интеграция с ключом. Всё настраивается в интерфейсе администратора, писать код на этом этапе не требуется.
Со стороны разработчика — один серверный обработчик, который обменивает ключ на пользовательский токен, и вызовы REST из клиента. Спецификация, примеры кода для сервера и клиента, схема вебхуков и типовые ошибки собраны в документации для разработчиков.