API базы знаний: как выдавать инструкции по вопросу

Традиционная база знаний ждёт, пока пользователь найдёт нужную статью. Но поисковая строка, дерево разделов и длинная страница добавляют действия в момент, когда человеку нужна помощь. API меняет точку входа: приложение передаёт вопрос, а сервис возвращает подходящий ответ и материал, на котором он основан.

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

Что должно вернуться из API

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

{
  "answer": "Откройте Настройки → Оплата и добавьте карту.",
  "source": {
    "id": "billing-payment-method",
    "title": "Как изменить способ оплаты",
    "url": "/guides/billing-payment-method"
  }
}

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

Как работает путь от вопроса к инструкции

1. Соберите вопрос и безопасный контекст. Передавайте только то, что нужно для подбора ответа: язык, раздел продукта или роль пользователя. Не отправляйте секреты и лишние персональные сведения.
2. Найдите подходящие материалы. Поиск должен учитывать не только совпадение отдельных слов, но и смысл формулировки. Пользователь может сказать «поменять карту», хотя в инструкции написано «обновить способ оплаты».
3. Сформируйте ответ из найденного источника. Коротко назовите действие и сохраните ссылки на конкретную инструкцию. Если релевантной инструкции нет, лучше попросить уточнить вопрос или показать канал связи.
4. Покажите продолжение. Для простого запроса хватит одного или двух шагов. Рядом оставьте ссылку «Открыть полную инструкцию» и предложите связаться с поддержкой, если ответ не подходит.

Почему ссылка на источник важна

Ответ без источника трудно проверить и поддерживать. Пользователь не может увидеть весь процесс, а команда не знает, какая версия базы использовалась. Ссылка создаёт прозрачный путь от краткой подсказки к полному объяснению.

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

Подготовьте инструкции до интеграции

API не исправит противоречивую базу знаний. Начните с конкретных задач, которые часто вызывают обращения. Убедитесь, что инструкции:

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

Для похожих действий используйте синонимы и распространённые формулировки в описаниях. Храните понятные идентификаторы и связи между гайдами: например, «настроить оплату» может ссылаться на инструкции о карте, счёте и смене тарифа.

Встройте ответ в подходящий интерфейс

В виджете поддержки это может быть мини-диалог с ответом и кнопкой на источник. Внутри SaaS-продукта — небольшой блок помощи рядом с настройкой. В боте — короткий текст с GIF и ссылкой. Один API может обслуживать несколько интерфейсов, если формат ответа не привязан к конкретному экрану.

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

Проверяйте полезность, а не только скорость

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

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

План первого запуска

1. Выберите одну точку входа, например поиск помощи в продукте.
2. Соберите 20–30 частых вопросов из обращений или интервью.
3. Подготовьте и проверьте соответствующие инструкции.
4. Определите схему ответа и правила, когда API должен воздержаться.
5. Проведите тест на реальных формулировках и исправьте слабые места.
6. Добавьте сбор обратной связи и передавайте команде неразрешённые вопросы.

Инструкции через API превращают справку из каталога страниц в работающую часть продукта. Чтобы это было действительно полезно, начните с актуальных материалов, отдавайте человеку короткий ответ и всегда оставляйте путь к полному источнику.

← Читать другие статьи