Kookeebeta
Назад к блогу

Добавьте ИИ-ассистента на любой сайт одной строкой кода

Help CenterDenis Povarov

До сих пор у виджета чата Kookee было требование, о котором никто не просил: React.

Если React у вас уже есть, это не проблема. Но если ваш маркетинговый сайт на WordPress, магазин на Shopify, документация на генераторе статических сайтов или приложение на Vue либо Angular, поставить виджет было нельзя. Он отвечал на вопросы по вашим статьям справки, и получить его можно было только на «правильном» фреймворке.

Теперь этого требования нет. Виджет чата поставляется как обычный тег script.

Одна строка

HTML 
<script async src="https://kookee.dev/chat/latest.js" data-api-key="YOUR_API_KEY"></script>

Вставьте её перед </body>, и на сайте появится плавающий ассистент, который отвечает по опубликованным статьям вашего центра помощи. Без npm install, без сборки, без настройки бандлера и без фреймворка.

Чтобы всё заработало, проверьте две вещи:

  1. Готовый сниппет с уже подставленным ключом лежит в панели управления: страница Виджет для сайта вашего проекта, вкладка Установка. Скопируйте его оттуда, а не набирайте URL вручную.

  2. Добавьте домен сайта в Разрешённые источники проекта. Как только в списке появится хотя бы одна запись, запросы со всех остальных адресов отклоняются. Так никто не вытащит ваш ключ из кода страницы и не запустит вашего ассистента на своём сайте.

Когда значок чата появляется, но ни на один вопрос нет ответа, чаще всего домена просто нет в этом списке. Если ответы не приходят, сначала проверьте список источников.

На что он отвечает

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

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

Настройка под ваш сайт

Всё, что касается внешнего вида, задаётся data-атрибутами, поэтому виджет настроит и не разработчик — достаточно поправить одну строку в шаблоне страницы:

HTML 
<script
  async
  src="https://kookee.dev/chat/latest.js"
  data-api-key="YOUR_API_KEY"
  data-title="Поддержка"
  data-greeting="Здравствуйте! Задайте любой вопрос о продукте."
  data-placeholder="Введите вопрос…"
  data-launcher-label="Нужна помощь?"
  data-position="bottom-left"
  data-theme="auto"
  data-primary-color="#ff6b00"
></script>

data-position принимает bottom-right или bottom-left, data-theme — light, dark или auto, а data-locale задаёт язык. data-base-url нужен, чтобы направить виджет на другой хост API.

Виджет отрисовывается внутри shadow root, и именно поэтому его безопасно вставлять на сайт, который делали не вы. CSS вашей страницы не проникнет внутрь и не перекрасит чат, а CSS чата не вытечет наружу и не сломает вёрстку. Тема Shopify с агрессивными глобальными селекторами его не заденет.

JS API — когда атрибутов не хватает

Атрибутов хватает для типичных случаев. Если нужно встроить ассистента в собственный интерфейс, есть window.KookeeChat:

JavaScript 
KookeeChat.open();
KookeeChat.close();
KookeeChat.toggle();
KookeeChat.sendMessage('Как сбросить пароль?');
KookeeChat.clearMessages();

Например, ваша ссылка «Написать в поддержку» может открывать ассистента, а не почтовый клиент:

JavaScript 
document.querySelector('#support-link').addEventListener('click', (event) => {
  event.preventDefault();
  KookeeChat.open();
});

События — это подписки, и каждая возвращает свою функцию отписки:

JavaScript 
const unsubscribe = KookeeChat.on('sourceClick', (source) => {
  analytics.track('help_article_opened', { slug: source.slug });
});

on() также принимает open и close. А если нужен полный контроль над настройками без атрибутов, вызовите init() сами: он принимает всё то же, что и атрибуты, и ещё несколько параметров, которые атрибутами не задать:

JavaScript 
KookeeChat.init({
  apiKey: 'YOUR_API_KEY',
  greeting: 'Чем могу помочь?',
  suggestions: ['С чего начать?', 'Какие есть тарифы?', 'Как отменить подписку?'],
  hideLauncher: true,
  zIndex: 9999,
  offset: { x: 24, y: 96 },
  onSourceClick: (source) => window.open(`/help/${source.slug}`, '_blank'),
  onOpenChange: (isOpen) => console.log('chat open:', isOpen),
});

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

Типы для TypeScript лежат по адресу https://kookee.dev/chat/latest.d.ts.

Мелочи, которые заметны в работе

Разговор сохраняется при переходах между страницами в одной вкладке: пользователь, который задал вопрос на странице цен и перешёл к описанию возможностей, не теряет нить. Свёрнутый чат тоже сохраняет разговор, очищает его только кнопка Новый чат. Для длинных ответов есть развёрнутый режим на всю высоту экрана, а подпись у кнопки чата пользователь может закрыть, если ему хватает одного значка.

Ничего из этого не нужно настраивать. Благодаря этим мелочам виджет не выглядит как iframe, прикрученный сбоку.

Если у вас уже React

Ничего не меняется:

tsx 
import { KookeeChatWidget } from '@kookee/react/chat';

В React-приложении этот компонент по-прежнему лучший выбор: он живёт в вашем дереве компонентов и принимает пропсы, как любой другой. Тег script его не заменяет. Он нужен гораздо большему числу сайтов, которые никогда не стали бы ставить пакет React ради кнопки чата, а теперь им и не придётся.