Подключение чат-виджета Chatterfy
Готовый чат-виджет Chatterfy можно встроить на сайт одним тегом <script> . После подключения в правом нижнем углу появится кнопка чата, а по клику откроется панель для общения с ботом или оператором.
Когда использовать Widget. Выбирайте этот вариант, если нужен готовый интерфейс чата без разработки собственного фронтенда. Для собственного интерфейса используйте Client API.
Создание Widget-бота
Откройте создание нового бота и пройдите мастер настройки. Основные этапы одинаковы для Widget и API (Web); отличается только выбранная платформа.
- На экране выбора платформы отметьте Widget и нажмите кнопку продолжения.
Выбор Widget при создании бота. - Укажите пространство, тему бота и при необходимости добавьте описание и теги.
Общие параметры создаваемого бота. - Задайте понятное имя. Его можно будет изменить позднее в настройках бота.
Имя бота в мастере создания. - Можно импортировать настройки существующего бота или настроить новый бот вручную.
Импорт настроек или ручная конфигурация. - Укажите задержку ответа и при необходимости создайте кастомные поля.
Задержка ответа и кастомные поля. - Выберите модели для анализа сообщений и формирования ответов.
Модели для маршрутизации и ответов бота. - Опишите роль бота, запрещённые действия и требования к оформлению ответов, затем завершите создание.
Global Legend, Global Restrictions и User Restrictions.
Что потребуется
Loader: https://cdn-widget.chatterfy.ai/loader.js
Публичный ключ бота: client_key вида cli_...
Сайт с HTTPS: обязателен для записи голосовых сообщений; localhost подходит для разработки.
Быстрый старт
Добавьте код перед закрывающим тегом
</body>:html
<script
src="https://cdn-widget.chatterfy.ai/loader.js"
data-widget-key="cli_example_key"
></script>После загрузки скрипта кнопка чата появится автоматически. Цвет, тема, мультичаты и вложения загружаются из настроек бота — передавать их в коде страницы не нужно.
Отложенная инициализация
Если виджет должен запускаться только после загрузки страницы или выполнения вашей логики, вызовите
init() самостоятельно:html
<script src="https://cdn-widget.chatterfy.ai/loader.js" data-widget-key="cli_example_key"></script>
<script>
window.addEventListener('load', () => {
ChatterfyWidget.init()
})
</script>Где взять client_key
Откройте настройки нужного бота и скопируйте публичный ключ вида
cli_.... Loader использует его, чтобы создать пользовательскую сессию и загрузить настройки виджета.
JavaScript API
После загрузки loader на странице доступен объект
window.ChatterfyWidget:init(config?) — инициализирует виджет и монтирует кнопку. Вызывайте один раз.open() — открывает панель чата.close() — сворачивает панель в кнопку.toggle() — переключает открытое и закрытое состояние.identify(user) — меняет пользователя и пересоздаёт сессию, например после входа в аккаунт.shutdown() — полностью удаляет виджет и сбрасывает его состояние, например при выходе пользователя.javascript
document.querySelector('#help').addEventListener('click', () => {
ChatterfyWidget.open()
})Инициализация пользователя
Метод
init(config) принимает только ключ бота и данные конкретного посетителя. Настройки внешнего вида остаются в конфигурации бота.javascript
ChatterfyWidget.init({
widgetKey: 'cli_...',
user: {
externalId: 'user-42',
firstName: 'Alex',
lastName: 'Taylor',
imageUrl: 'https://site.com/avatars/42.jpg',
},
additionalInfo: {
plan: 'pro',
orderId: 12345,
custom_fields: {
utm_source: 'google',
},
},
})widgetKey — публичный ключ бота. Можно не передавать, если он указан в data-widget-key.user.externalId — стабильный идентификатор пользователя на вашей стороне.user.firstName / lastName — имя и фамилия посетителя.user.imageUrl — публичная HTTPS-ссылка на аватарку. Квадратные изображения выглядят лучше всего.additionalInfo — произвольный JSON-контекст для оператора: тариф, номер заказа, текущая страница и другие данные.Важно: additionalInfo и imageUrl записываются в момент создания чата. Передача новых значений не изменит уже существующий чат.
Кастомные поля чата
Объект
custom_fields внутри additionalInfo заполняет кастомные поля, которые оператор видит в карточке чата и использует в фильтрах.javascript
ChatterfyWidget.init({
additionalInfo: {
custom_fields: {
city: 'example-city',
utm_source: 'google',
},
},
})Используйте ключи полей из настроек бота, а не их ID.
Неизвестные поля игнорируются и не мешают созданию чата.
Допустимы строки, числа и true/false. Объекты и массивы пропускаются.
Строки длиннее 1000 символов обрезаются.
Поля заполняются только при создании чата и не перезаписывают существующие значения.
Настройки внешнего вида и поведения
Эти параметры задаются в настройках бота и автоматически применяются на всех сайтах, где подключён виджет:
Предпросмотр
Нажмите кнопку открытия чата, чтобы проверить виджет прямо в настройках. Предпросмотр создаёт реальную пользовательскую сессию и чат появится в списке бота.
Оформление
Здесь настраиваются основной цвет, тема, скругление, стиль шапки и оформление исходящих сообщений.
primary_color — цвет кнопки, шапки и исходящих сообщений.theme_mode — светлая, тёмная или автоматическая.corner_radius — скругление панели, сообщений и поля ввода в пикселях.header_style — цветной или обычный.message_style — насыщенный или мягкий.multiple_chats — один чат или список чатов с возможностью создавать новые.attachments — вложения и запись голосовых сообщений.Поведение и доступ
Включите мультичаты и вложения при необходимости. В этом же блоке будет доступно ограничение доменов, с которых разрешено открывать виджет.
Как виджет запоминает посетителя
- Вызовите init() без user. Сервер создаст external_id вида visitor_<uuid>, а loader сохранит его в localStorage.
- Передайте стабильный externalId из вашей системы. История чатов будет привязана к этому идентификатору.
- Вызовите identify({ externalId, firstName, ... }). Виджет пересоздаст сессию для нового пользователя.
- Вызовите ChatterfyWidget.shutdown(), чтобы удалить виджет и сбросить текущую сессию.
Как это работает
Loader создаёт iframe, поэтому стили и скрипты сайта не конфликтуют с интерфейсом чата.
Страница и iframe обмениваются командами через postMessage.
Ответы бота и оператора приходят в реальном времени автоматически.
На одной странице должен работать один экземпляр виджета и один вызов init().
Типовые сценарии
Анонимный чат на лендинге
html
<script
src="https://cdn-widget.chatterfy.ai/loader.js"
data-widget-key="cli_..."
onload="ChatterfyWidget.init()"
></script>Личный кабинет или SPA
javascript
ChatterfyWidget.init({
user: {
externalId: currentUser.id,
firstName: currentUser.name,
},
})
logoutButton.addEventListener('click', () => {
ChatterfyWidget.shutdown()
})Требования и ограничения
Loader загружается по HTTPS с cdn-widget.chatterfy.ai.
Поддерживаются актуальные версии браузеров.
Для голосовых сообщений странице требуется HTTPS; localhost разрешён для разработки.
Если сайт использует Permissions-Policy, доступ к микрофону должен быть разрешён.
Служебные параметры apiBase и appBase менять не нужно.
После изменения цвета, темы, мультичатов или вложений в настройках бота обновлять код на сайте не требуется — виджет получит новые параметры при следующем запуске сессии.
Эта статья была полезна?