Онлайн-чат в BotMan: JS API и частые ошибки 🧩

Что такое JS API¶

JS API — это набор JavaScript-методов для управления виджетом. Он нужен, если вы хотите открывать чат по кнопке на сайте, передавать данные авторизованного пользователя или отслеживать события.

• открывать и закрывать чат;

• передавать имя, email и телефон посетителя;

• авторизовывать пользователя через внешний ID;

• отправлять сообщение программно;

• подписываться на события виджета.

Основные методы JS API¶

→ connect() — подключение к виджету, если не используется data-webchat-id в HTML.
→ auth() — передача внешнего ID пользователя и подписи для безопасной идентификации.
→ identify() — передача имени, email, телефона и других данных.
→ open() и close() — управление окном чата.
→ sendMessage() — программная отправка сообщения.
→ track() — отправка пользовательского события.
→ onReady() — колбэк после готовности виджета.
→ addCallback() и removeCallback() — работа с событиями виджета.
→ destroy() — полная очистка виджета.

Примеры методов¶

BotmanWebChat.open() ;
BotmanWebChat.close() ;
BotmanWebChat.identify({ $name: 'Иван', $email: 'ivan@example.com' }) ;
BotmanWebChat.auth('external-user-id', 'hmacHash') ;

📍Важно: если вам нужна просто стандартная установка чата, JS API не обязателен. В большинстве случаев хватает обычного кода виджета и настроек в кабинете.

События, на которые можно подписаться¶

• conversation_opened — чат был открыт.
• conversation_closed — чат был закрыт.
• message_sent — посетитель отправил сообщение.
• message_received — бот или оператор отправили ответ.

Частые проблемы¶

1. Чат не появляется на сайте

• проверьте, вставлен ли код виджета;

• убедитесь, что код стоит на нужном сайте;

• проверьте правильность webchat ID;

• если указаны разрешённые домены, проверьте, входит ли сайт в список.

2. Сообщения не отправляются

• убедитесь, что поле ввода включено;

• проверьте, не мешает ли форма согласия;

• проверьте, нет ли проблем с соединением.

3. Файл не загружается

• проверьте формат файла;

• убедитесь, что размер файла не больше 20 МБ;

• повторите попытку позже.

4. История не сохраняется

• проверьте, не открыт ли сайт в режиме инкогнито;

• убедитесь, что браузер не очищает localStorage;

• если нужна сквозная история между устройствами, обсудите с разработчиком идентификацию.

5. Виджет перекрывает элементы сайта

• измените позицию во вкладке «Внешний вид»;

• отрегулируйте отступы X и Y;

• для мобильных включите отдельные настройки.

Финальная проверка перед запуском

• канал создан;

• скрипт вставлен на сайт;

• виджет появился;

• заголовки, тексты и цвета настроены;

• форма перед чатом включена или выключена по вашей логике;

• безопасность и согласие настроены при необходимости;

• тестовое сообщение отправляется.

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