Документация EasyChat — установка онлайн-чата и JavaScript API

Установка виджета

Код лучше размещать перед закрывающим тегом body. Токен берется в кабинете на странице добавления виджета.

Создайте виджет

В кабинете откройте добавление виджета и скопируйте token.

Добавьте код

Вставьте конфигурацию и скрипт на страницы сайта, где нужен онлайн-чат.

Проверьте домен

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

<!-- Вставьте перед </body> -->
<script>
  window.EasyChatWidget = {
    token: 'YOUR_WIDGET_TOKEN',
    language: 'ru',
    visitor: {
      id: window.currentUser?.id,
      email: window.currentUser?.email
    }
  }
</script>
<script src="https://easychat.gg/widget.js" defer></script>

Конфигурация

Минимально нужен только token. Остальные параметры можно задать в кабинете или переопределить на странице.

ПолеНазначение

token

Обязательный токен виджета. По нему EasyChat понимает, к какому аккаунту и сайту относится чат.

language

Язык окна чата для посетителя: ru, ua или en.

visitor

Дополнительные данные пользователя с вашего сайта. На базовом тарифе можно передать до 2 полей, на профессиональном — до 24.

apiUrl

Адрес API, если виджет подключается не с того же домена, где работает backend.

socketUrl

Адрес WebSocket-сервера. Обычно задавать не нужно, виджет определяет его автоматически.

components.Widget

Позиция, тема, отступы и заголовок окна чата.

components.WidgetButton

Размер, радиус, цвет и hover-цвет стандартной плавающей кнопки.

<script>
  window.EasyChatWidget = {
    token: 'YOUR_WIDGET_TOKEN',
    language: 'ru',
    visitor: {
      id: window.currentUser?.id,
      plan: window.currentUser?.plan
    },
    components: {
      Widget: {
        position: 'bottom-right',
        theme: 'light',
        padding: 24,
        chat: {
          title: 'Поддержка сайта'
        }
      },
      WidgetButton: {
        size: 62,
        radius: 999
      }
    }
  }
</script>

Открытие чата по клику на ваш блок

Можно скрыть стандартную плавающую кнопку EasyChat и открывать окно чата по нажатию на любой блок сайта: баннер, кнопку, карточку тарифа или ссылку в меню.

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

Главная идея

api.hide() скрывает стандартную кнопку запуска, а api.open() открывает окно чата из вашего элемента.

<div class="support-card" data-easychat-open>
  Нужна помощь? Напишите нам
</div>

<script>
  const connectEasyChat = (api) => {
    api.hide()

    document
      .querySelectorAll('[data-easychat-open]')
      .forEach((block) => {
        block.addEventListener('click', () => api.open())
      })
  }

  if (window.EasyChatWidgetAPI) {
    connectEasyChat(window.EasyChatWidgetAPI)
  }

  window.addEventListener('easychat:ready', (event) => {
    connectEasyChat(event.detail.api)
  })
</script>

JavaScript API

После загрузки виджета объект доступен как window.EasyChatWidgetAPI. Если скрипт еще грузится, используйте событие easychat:ready.

open()

Открывает окно чата. Если сессия еще не готова, виджет сначала инициализируется.

close()

Закрывает окно чата и оставляет стандартную кнопку запуска на странице.

toggle()

Переключает состояние окна: открывает закрытое или закрывает открытое.

hide()

Скрывает стандартную плавающую кнопку. Сам чат можно открыть через open().

show()

Возвращает стандартную плавающую кнопку после hide().

updateConfig(config)

Обновляет конфигурацию на странице без перезагрузки виджета.

on(event, callback)

Подписывает callback на событие виджета и возвращает функцию отписки.

События

События можно слушать через API или обычные события браузера с префиксом easychat.

window.addEventListener('easychat:ready', (event) => {
  const api = event.detail.api

  api.on('open', () => console.log('Окно чата открыто'))
  api.on('close', () => console.log('Окно чата закрыто'))
  api.on('hide', () => console.log('Стандартная кнопка скрыта'))
  api.on('show', () => console.log('Стандартная кнопка снова видна'))
})

window.addEventListener('easychat:open', () => {
  console.log('То же событие через browser event')
})

Безопасность и ограничения

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

Привязка к домену

Виджет открывается только с домена, указанного в настройках аккаунта. На профессиональном тарифе можно указать несколько доменов.

Файлы по тарифу

Вложения зависят от тарифа: бесплатный тариф не отправляет файлы, стартовый разрешает фото до 2 МБ, базовый разрешает фото и PDF, профессиональный также разрешает видео.

Публичный token

Token виджета можно видеть в коде страницы, поэтому критичные действия всегда проверяются на сервере.

Данные пользователя

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

Техническая документация