Интеграция Telegram-CRM с HubSpot Knowledge Base: Устранение неполадок

При подключении Telegram-CRM к базе знаний HubSpot (Knowledge Base) пользователи нередко сталкиваются с ситуациями, когда автоматический подбор статей не срабатывает, ссылки на релевантные материалы не отображаются в интерфейсе агента, а созданные тикеты остаются без контекстных предложений. Ниже разобраны типичные проблемы, их причины и пошаговые методы диагностики.

Проблема 1: Статьи базы знаний не подгружаются при создании тикета

Симптом: После настройки интеграции при открытии нового обращения в топик-группе Telegram агент не видит предложений из HubSpot Knowledge Base. Поле «Рекомендованные статьи» остаётся пустым.

Причина: Наиболее частый источник — некорректные права доступа API-ключа или отсутствие синхронизации категорий базы знаний. HubSpot использует многоуровневую систему разрешений: даже если ключ сгенерирован, он может не иметь доступа к чтению объектов Knowledge Base.

Пошаговое решение:

1. Проверьте область действия API-ключа. В настройках интеграции Telegram-CRM убедитесь, что выбранный ключ имеет доступ к модулю `Content` (или `Knowledge Base`). В интерфейсе HubSpot перейдите в «Настройки» → «Интеграции» → «Ключи API». Убедитесь, что для ключа включены права на чтение (`GET`) для endpoint `/cms/v3/hubdb/` и `/knowledge-base/v1/articles/`.
2. Проверьте статус публикации статей. HubSpot Knowledge Base различает черновики и опубликованные статьи. Telegram-CRM по умолчанию подтягивает только опубликованные материалы. Если статьи находятся в статусе «Черновик», они не будут отображаться. Переведите необходимые статьи в статус «Опубликовано» через редактор HubSpot.
3. Проверьте фильтры по категориям. В некоторых Telegram-CRM предусмотрена настройка, ограничивающая выборку статей определёнными категориями или разделами. Убедитесь, что фильтры не исключают нужные категории. Например, если в CRM задан фильтр по разделу «Техническая поддержка», а статья находится в разделе «Биллинг», она не будет предложена.
4. Выполните тестовый запрос. Используя любой HTTP-клиент (например, Postman или curl), отправьте GET-запрос к HubSpot API для получения списка статей. Пример запроса:

``` GET https://api.hubapi.com/cms/v3/hubdb/tables Authorization: Bearer {ваш_ключ} ``` Если ответ содержит пустой массив `results`, проблема на стороне HubSpot: либо нет опубликованных статей, либо ключ не имеет доступа.

Когда требуется специалист: Если после проверки всех пунктов статьи по-прежнему не загружаются, вероятна ошибка на уровне конфигурации прокси или сетевых политик. В этом случае обратитесь к администратору инфраструктуры для проверки, не блокирует ли корпоративный firewall исходящие запросы к `api.hubapi.com`.

Проблема 2: Предлагаются нерелевантные статьи из базы знаний

Симптом: Интеграция работает, но агент видит рекомендации, которые не соответствуют теме обращения клиента. Например, на вопрос по настройке уведомлений система предлагает статьи по тарифам.

Причина: HubSpot Knowledge Base использует полнотекстовый поиск по ключевым словам. Если в тексте обращения (тикете) присутствуют общие слова или отсутствуют специфические термины, алгоритм подбирает статьи с низкой релевантностью. Кроме того, на точность влияет структура самой базы знаний: отсутствие мета-тегов, неправильно назначенные категории.

Пошаговое решение:

1. Проверьте настройки алгоритма подбора. В Telegram-CRM может быть два режима: «По ключевым словам» и «По категории обращения». Если выбран первый, убедитесь, что в тексте тикета достаточно уникальных терминов. Если выбран второй — проверьте, что категории в CRM сопоставлены с разделами базы знаний.
2. Оптимизируйте статьи в HubSpot. Добавьте каждой статье поле «Ключевые слова» (Keywords) и перечислите 3–5 специфических терминов, по которым она должна находиться. Например, для статьи о настройке SLA укажите: «SLA, время первого ответа, FRT, соглашение об уровне обслуживания».
3. Проверьте приоритет статей. HubSpot позволяет задавать вес (priority) для каждой статьи. Если несколько материалов содержат одни и те же ключевые слова, система отдаёт приоритет статье с более высоким весом. Убедитесь, что наиболее важные статьи имеют повышенный приоритет.
4. Выполните тестовый поиск. В интерфейсе HubSpot Knowledge Base используйте строку поиска, чтобы увидеть, какие статьи выдаются по запросу, аналогичному тексту тикета. Если результаты не совпадают с ожидаемыми, скорректируйте содержимое статей.

Когда требуется специалист: Если проблема сохраняется после оптимизации базы знаний, возможно, требуется настройка кастомного алгоритма подбора статей. В этом случае необходимо привлечь разработчика Telegram-CRM для настройки правил маппинга или подключения AI-модуля. Подробнее о возможностях AI для подбора статей читайте в статье Использование AI для подбора релевантных статей базы знаний.

Проблема 3: Ошибка авторизации при подключении к HubSpot

Симптом: При попытке настроить интеграцию Telegram-CRM с HubSpot Knowledge Base появляется сообщение об ошибке: «401 Unauthorized» или «403 Forbidden». Интеграция не сохраняется.

Причина: Истёк срок действия токена доступа, либо токен не имеет необходимых разрешений. HubSpot использует OAuth 2.0, и токены имеют ограниченный срок жизни (обычно 30 дней для refresh-токена). Кроме того, если интеграция была настроена с использованием приватного приложения (Private App), ключ мог быть отозван.

Пошаговое решение:

1. Проверьте срок действия токена. В настройках HubSpot перейдите в раздел «Приватные приложения» (Private Apps) и посмотрите дату создания ключа. Если прошло более 30 дней, сгенерируйте новый ключ.
2. Обновите токен в Telegram-CRM. В интерфейсе интеграции удалите старый ключ и введите новый. Убедитесь, что при генерации ключа выбраны все необходимые scope: `content`, `knowledge-base`, `tickets` (если требуется).
3. Проверьте, не заблокирован ли IP-адрес. HubSpot может блокировать запросы с IP-адресов, которые не внесены в белый список. Если ваш сервер Telegram-CRM расположен за динамическим IP, укажите статический адрес в настройках безопасности HubSpot.
4. Выполните проверку через тестовый запрос. Используйте тот же метод, что и в Проблеме 1, но с новым ключом. Если ответ содержит `401`, значит, ключ не активен или неправильно скопирован.

Когда требуется специалист: Если после генерации нового ключа ошибка сохраняется, проверьте, не настроена ли в HubSpot двухфакторная аутентификация для API-запросов. В редких случаях требуется создание публичного приложения (Public App) с перенаправлением OAuth. Обратитесь к администратору HubSpot для проверки политик безопасности.

Проблема 4: Статьи отображаются, но ссылки не кликабельны

Симптом: В интерфейсе Telegram-CRM агент видит названия статей из HubSpot Knowledge Base, но при нажатии на них не происходит перехода к полному тексту. Ссылки ведут на пустую страницу или выдают ошибку 404.

Причина: Несоответствие URL-адресов статей. HubSpot Knowledge Base генерирует ссылки вида `https://app.hubspot.com/knowledge/{portal_id}/article/{article_id}`, но Telegram-CRM может ожидать другой формат (например, публичную ссылку вида `https://knowledge.yourdomain.com/article/{slug}`). Если в настройках интеграции указан неверный базовый URL, ссылки будут нерабочими.

Пошаговое решение:

1. Проверьте настройки базового URL. В конфигурации интеграции Telegram-CRM найдите поле «Базовый URL базы знаний» или «Knowledge Base URL». Убедитесь, что он совпадает с публичным URL вашей базы знаний HubSpot. Если вы используете кастомный домен, укажите его (например, `https://docs.example.com`).
2. Проверьте, открыт ли доступ к базе знаний. Если база знаний закрыта для внешнего доступа (только для зарегистрированных пользователей HubSpot), ссылки могут быть недоступны для агентов, которые не авторизованы в HubSpot. Настройте публичный доступ к базе знаний или убедитесь, что все агенты имеют учётные записи HubSpot.
3. Проверьте формат ссылки в ответе API. Выполните тестовый запрос к API HubSpot для получения одной статьи:

``` GET https://api.hubapi.com/cms/v3/hubdb/tables/{table_id}/rows/{row_id} ``` В ответе найдите поле `url` или `link`. Сравните его с тем, что отображается в Telegram-CRM. Если они различаются, проблема в маппинге полей.

Когда требуется специалист: Если ссылки ведут на страницу входа HubSpot, а не на статью, вероятно, требуется настройка SSO (Single Sign-On) или публикация базы знаний на отдельном поддомене. В этом случае обратитесь к разработчику для настройки кастомного обработчика ссылок.

Проблема 5: Интеграция работает, но статьи не обновляются

Симптом: После добавления или изменения статей в HubSpot Knowledge Base Telegram-CRM продолжает показывать старые версии. Новые материалы не появляются в течение длительного времени.

Причина: Telegram-CRM может кэшировать список статей для ускорения работы. Кэш обновляется по расписанию (например, раз в час) или вручную. Если кэш не сброшен, новые статьи не отобразятся.

Пошаговое решение:

1. Проверьте настройки кэширования. В интерфейсе Telegram-CRM найдите раздел «Кэш базы знаний» или «Cache settings». Убедитесь, что интервал обновления кэша установлен в разумное значение (например, 15–30 минут). Если интервал слишком большой (например, 24 часа), сократите его.
2. Выполните принудительную синхронизацию. В большинстве Telegram-CRM есть кнопка «Синхронизировать сейчас» или «Refresh Knowledge Base». Нажмите её после внесения изменений в HubSpot.
3. Проверьте, не заблокирован ли endpoint изменений. HubSpot отправляет webhook-уведомления об изменениях в базе знаний. Убедитесь, что Telegram-CRM подписан на эти уведомления. В настройках HubSpot перейдите в «Webhooks» и проверьте, что endpoint Telegram-CRM указан корректно.

Когда требуется специалист: Если после принудительной синхронизации статьи не обновляются, возможно, нарушен механизм обработки webhook-уведомлений. Это требует анализа логов сервера Telegram-CRM. Обратитесь к администратору системы.

Интеграция Telegram-CRM с HubSpot Knowledge Base — многошаговый процесс, который может столкнуться с рядом типичных неполадок: от ошибок авторизации до некорректного отображения ссылок. Большинство проблем решается проверкой прав доступа API-ключа, настройками кэширования и корректным маппингом URL. Если после выполнения всех описанных шагов интеграция продолжает работать некорректно, вероятна необходимость в настройке кастомных правил подбора статей или подключении AI-модуля. Рекомендуется также ознакомиться с общей информацией об интеграциях Telegram-CRM с базой знаний в статье Интеграция Telegram-CRM с базой знаний и с пошаговой инструкцией по настройке автоматического подбора статей в Настройка автоматического подбора статей при создании тикета.