OK API: ИИ-агент для сообщений и заявок

OK API — интерфейс Одноклассников для приложений: методы сообщений, друзей, групп и игр. Агент подключается как приложение ОК и превращает переписку и обращения в учтённые заявки.

Агент — программа, которая выполняет дело целиком. Он не советует, что ответить: он забирает сообщения, определяет тему, находит прошлые обращения автора и приносит карточку заявки. Чат-бот выдал бы текст, агент возвращается с зарегистрированным делом.

Три признака: работает в ваших сервисах, доводит до результата, работает без вас. Обращения, пришедшие вечером, разобраны до утра.

Коннектор — описание подключения: где взять ключи приложения, как проверить связь и какие данные открыты. Не плагин и не доработка сообщества: вы создаёте приложение в кабинете, и на этом настройка заканчивается.

Пароль коннектор не хранит: он работает по ключу приложения и сессии, выданной под задачу. Доступ отзывается на стороне приложения.

Каждый метод доступен по двум адресам: через fb.do с именем метода и через путь с группой и названием. Обязательные общие параметры — публичный ключ приложения и подпись запроса; сессия пользователя передаётся отдельным параметром и в части методов может быть обязательной, необязательной или запрещённой. Ответ приходит в JSON, есть порядковый номер запроса и флаг отметки онлайна.

Подпись считается по своим правилам: без сессии берётся секрет приложения, с сессией — хэш от токена и секрета; параметры сортируются по ключам. Приложение создаётся после получения прав разработчика: заполняются название, короткое имя и описание, а ключи приходят на почту. Отдельно описаны обработка ошибок, ограничения приложения и верификация сервисов.

### Входящая корреспонденция: регистрация и резолюция

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

### Заявки из почты, форм и мессенджеров

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

### Сводки по обращениям: день и месяц

Агент считает обращения по темам и каналам, отмечает рост и повторные вопросы, показывает, сколько заявок закрыто правилом, а сколько ушло человеку. Сводка за день и за месяц приходит текстом и таблицей, вместе с долей обращений без ответа.

Права приложения и подпись запросов остаются на стороне владельца: агент не расширяет себе доступ. Спорные обращения, ответы от имени бренда и блокировки пользователей — решение сотрудника.

Нужно приложение ОК: права разработчика выдаются в Одноклассниках, приложение добавляется в разделе для разработчиков, а ключи приходят письмом на привязанную почту. Платформа выбирается под задачу: OAuth для доступа к данным, Web для запуска внутри сайта, мобильная для приложений. Перед запуском проверяются ограничения приложения и верификация сервиса.

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

Что такое агент, если коротко? Программа, которая выполняет работу в ваших сервисах до результата, а не пересказывает, как её сделать.

Что такое коннектор? Описание подключения: где взять ключи, как проверить связь и какие данные доступны. Пароль не хранится.

Почему запросы иногда отклоняются? Чаще всего из-за подписи, устаревшей сессии или ограничений приложения. Агент показывает код ошибки, а исправление прав — на стороне владельца приложения.