Подключения

Откуда бот-категоризатор получает диалоги и куда записывает категории

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

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

Если вам нужна интеграция, которой пока нет в списке, напишите нам.

Как это работает

Схема одинакова для всех подключений:

Хелпдеск отправляет вебхук

Правило в хелпдеске срабатывает при завершении обращения и отправляет на адрес бота вебхук. В теле запроса передаётся только идентификатор тикета.

Бот забирает диалог

Перед классификацией бот сам запрашивает у хелпдеска содержимое тикета: тему обращения и все публичные сообщения. Служебные и внутренние комментарии в работу не берутся.

Бот записывает категории

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

Если по тикету категория уже определена, повторный вебхук отбрасывается: обращение к хелпдеску не выполняется и кредиты не списываются. Поэтому дублирующиеся срабатывания правила не приводят к лишним расходам.

Куда записывается результат

Для HelpDeskEddy и Юздеск доступны два способа записи, их можно использовать вместе:

  • Записывать категории как теги тикета — включено по умолчанию. Категории добавляются к уже проставленным тегам, существующие теги не затираются.
  • Пользовательское поле — необязательный параметр. Если поле выбрано, категории записываются также в него.

Категория записывается полным путём: подкатегория выглядит как Родитель / Дочерняя. Если бот присвоил несколько категорий, записываются все.

Если запись в хелпдеск не удалась — например, отозван API-ключ или у сотрудника нет прав, — в разделе События появляется соответствующая запись.

HelpDeskEddy

Категоризатор использует то же подключение, что и бот-оператор, но настроек меньше: агент, метка Wikibot и параметры ответа не нужны — бот ничего не отвечает.

Включите интеграцию

В разделе Подключения включите интеграцию HelpDeskEddy и заполните:

  • Домен — ваш домен HelpDeskEddy.
  • Почта — почта сотрудника в HelpDeskEddy.
  • API ключ — создаётся по пути: Контакты → выбор сотрудника → API key
    (на странице https://<ваш домен>.helpdeskeddy.com/ru/contacts/).

Нажмите Проверить подключение, чтобы убедиться, что данные введены верно.

Настройте запись результата

Оставьте включённым флажок Записывать категории как теги тикета или снимите его, если метки заявки вам не нужны.

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

Нажмите Добавить, чтобы сохранить подключение.

Скопируйте Webhook URL

В настройках интеграции скопируйте Webhook URL вашего бота.

Настройте правило на закрытие заявки

Перейдите по пути «Управление» → «Диспетчер» и нажмите «Добавить правило».

Условие:

  • Статус заявки изменился на «Закрыта» (или другой финальный статус, который используется у вас).

Действие:

  • Отправить вебхук, тип запроса POST, формат JSON, без авторизации.
  • Укажите URL, скопированный в предыдущем пункте.
  • Укажите тело запроса:
{
  "id": {ticket_id}
}
Проверьте работу

Закройте тестовую заявку и убедитесь, что через несколько секунд у неё появилась метка с категорией. Ход обработки виден в журнале.

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

Юздеск

Как и в HelpDeskEddy, категоризатору не нужны агенты: поля Агент Wikibot и Агент для перевода в форме не отображаются.

Получите Webhook URL

В разделе Подключения включите интеграцию Юздеск и скопируйте поле Webhook URL.

Создайте API-канал в Юздеске

API-канал нужен только для того, чтобы получить секретный ключ. Остальные действия должны быть отключены.
Создайте API-канал и укажите в качестве Redirect url скопированный Webhook URL.

Задайте секретный ключ

Скопируйте Секретный ключ из настроек канала и введите его в форму подключения на портале.

Настройте запись результата

Оставьте включённым флажок Записывать категории как теги тикета или снимите его, если теги вам не нужны. При необходимости укажите Пользовательское поле.

Нажмите Добавить, чтобы сохранить подключение.

Добавьте правило Юздеск

Создайте правило, которое отправляет запрос в Wikibot при закрытии обращения.

Когда

  • Статус заявки изменился

Что

  • Все условия — статус равно «Закрыт» (или другой финальный статус, который используется у вас)

Сделать

  • POST запрос
{
  "url": "ЗДЕСЬ ВАШ WEBHOOK URL",
  "data": {
    "id": "{{ticket_id}}"
  }
}
Проверьте работу

Закройте тестовое обращение и убедитесь, что у него появился тег с категорией. Ход обработки виден в журнале.

API

Если вы работаете в системе, для которой готовой интеграции нет, отправляйте диалоги на категоризацию сами — методом Категоризировать диалог.

В отличие от интеграций с хелпдесками, здесь текст диалога передаёте вы: бот никуда за ним не ходит. Ключ для авторизации создаётся в разделе Настройки → API ключи вашего бота.

Базовый URL этого метода — https://api.wikibot.pro/api, без /bot, в отличие от остальных методов API.

Обработка асинхронная: метод сразу возвращает идентификатор запроса, а результат приходит POST-запросом на ваш webhook URL, заданный методом Задать webhook URL:

{
  "botId": "7f3c1e0a-...",
  "chatId": "12345",
  "requestId": "a1b2c3d4-...",
  "type": "CATEGORIZED",
  "categories": [
    {
      "path": ["cat_9f21ab", "cat_4d70e1"],
      "titlePath": ["Оплата", "Возврат средств"],
      "reason": "Клиент просит вернуть деньги за подписку"
    }
  ]
}

Поле type повторяет результат обработки: CATEGORIZED, UNCATEGORIZED, SKIP или ERROR. При значении ERROR текст ошибки приходит в поле error.

В path передаются идентификаторы категорий от корня до присвоенной, в titlePath — их названия. Идентификаторы не меняются при переименовании категории, поэтому для сопоставления надёжнее использовать именно их.

Результаты, полученные через API, попадают в журнал и аналитику наравне с обращениями из хелпдесков. Если webhook URL не задан, результат всё равно сохраняется — его можно посмотреть в журнале.

Повторный запрос с тем же chatId не обрабатывается: если категория по этому диалогу уже определена, запрос отбрасывается и кредиты не списываются. На webhook URL при этом придёт ответ с type: "SKIP" и пустым списком категорий.

На этой странице