Omnidesk через MCP: обращения, ответы клиенту и база знаний из чата

Обзор

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

Доступ к API устроен непривычно, и это важнее, чем кажется. Ключ выдаётся не интеграции, а конкретному сотруднику: «Настройки → Сотрудники → сотрудник → API-ключ». API видит ровно то, что видит этот человек, и действует его правами. Подключая Omnidesk, владелец проекта выбирает не только систему, но и от чьего имени в ней будут работать.

Второй особенности не видно, пока не начнёшь ходить в API из кода: общего адреса у Omnidesk нет. Каждая компания живёт на своём поддомене (https://компания.omnidesk.ru), и адрес называет владелец при подключении. Для человека в браузере это ничего не меняет, для системы — меняет всё: запрос уходит по адресу, который назвали снаружи, поэтому все обращения к Omnidesk идут через транспорт с ограничениями, не позволяющий увести запрос во внутреннюю сеть.

API целиком: 103 действия

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

Не вошли три действия — создание обращения, ответ и заметка с файлами: у них тот же адрес и метод, что у обычных, но тело загружается вложениями, а не JSON. Действие, которое не может сработать ни разу, хуже его отсутствия, поэтому оно названо отсутствующим, а не сделано наполовину. Файлы при этом не потеряны: ссылку на уже загруженный файл принимают и обычные действия.

Ответ клиенту — это не запись в базу

Из 103 действий 71 меняет данные, и каждое требует у источника отдельного разрешения на запись. Разрешение выдаёт владелец проекта, по умолчанию его нет: подключённый Omnidesk сначала только читается.

Разделение проходит не по «портит или не портит базу». Ответ клиенту уходит человеку в его канал — в почту, в мессенджер, в чат на сайте, — и отозвать его нельзя. Удаление обращения, объединение двух карточек клиента, смена ответственного видны команде поддержки. Всё это — запись, даже когда формально это «просто ещё одна строка в переписке».

Есть и обратная сторона. Проверка обязательных полей идёт до похода в Omnidesk, по тому же снимку документации. Причём проверка знает разницу между «обязательно» и «хотя бы одно из»: текст ответа Omnidesk принимает как обычный текст или как HTML, клиента обращения — по почте, телефону, идентификатору в вашей системе или контакту в мессенджере. Требовать их все значило бы отказывать законным вызовам; требовать ни одного — отправлять заведомо отклоняемый запрос.

Что это даёт в чате

Подключённый Omnidesk доступен и в чате Mira, и через MCP-сервер в Claude, Cursor или другом клиенте, который умеет MCP. Разговор с системой поддержки идёт словами, а не переключением вкладок:

• «Сколько обращений в работе и сколько висят без ответа больше суток?»
• «Покажи переписку по обращению 1420 и предложи ответ».
• «Какие оценки клиенты ставили на прошлой неделе и за что снижали?»
• «Найди статьи базы знаний про возврат — их стоит обновить?»

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

Как подключить

1. В Omnidesk: «Настройки → Сотрудники» → выберите сотрудника, чьими правами будет работать Mira → скопируйте его API-ключ.
2. Запомните адрес компании — тот поддомен, по которому вы входите: https://компания.omnidesk.ru.
3. В Mira: проект → источники → Omnidesk → адрес компании, почта сотрудника и API-ключ.

Разрешение на запись выдаётся отдельно и в любой момент снимается. Пока его нет, Omnidesk отвечает на вопросы, но ничего в нём не меняет.