JS API
Управление виджетом из кода вашего сайта: открыть чат по своей кнопке, передать данные о клиенте, направить обращение в отдел, поменять вид.
Живая демонстрация
Справа — ваш настоящий виджет с текущими настройками в изолированной песочнице. Кнопки «Попробовать» вызывают методы прямо в нём, результат виден сразу.
Что происходит: Виджет боевой: сообщение, отправленное из демонстрации, придёт в «Диалоги» как обращение обычного посетителя.
На весь экран
Растягивает песочницу на весь экран — нужно, чтобы проверять методы, которые на узком блоке не срабатывают (например, «большой режим» окна). Возврат — кнопкой «Свернуть демо» или клавишей Esc.
window.SvyazioConfig
Объект настроек, который задаётся до загрузки скрипта. Обязателен только orgId. Остальное необязательно: skin (classic, aurora, soft), locale (ru, en, es, pt, de, fr, tr), groupID (ID отдела, в который направлять обращения), startHidden (не показывать кнопку чата при загрузке).
Что происходит: Значения из этого объекта перекрывают настройки из вкладки «Виджет» для того сайта, где стоит код. Вызовы Svyazio(…), сделанные до загрузки скрипта, не теряются — они встают в очередь и выполняются после инициализации.
Svyazio('openChat', true);
Открывает окно чата — так подключается собственная кнопка «Написать нам» на сайте. Аргумент true сразу ставит курсор в поле ввода.
Svyazio('closeChat');
Закрывает окно чата. Круглая кнопка виджета остаётся на месте, переписка не теряется.
Svyazio('expandWidget');
То же, что openChat, — метод оставлен для совместимости с кодом, написанным под Chatra. На мобильных устройствах вызов игнорируется.
Svyazio('setExpanded', true);
Разворачивает окно чата в «большой режим» — то же, что кнопка разворота в шапке окна. false возвращает обычный размер.
Что происходит: Работает только на экранах шире 600 px, на мобильных вызов молча игнорируется. Если чат закрыт, метод сначала откроет его. Выбранный режим запоминается в браузере посетителя.
Svyazio('hide');
Полностью убирает виджет со страницы — и окно, и круглую кнопку. Полезно на страницах, где чат не нужен (оформление заказа, страница оплаты).
Что происходит: Скрытие действует до вызова show() или до перезагрузки страницы. Уже начатый диалог не закрывается и не удаляется — при возврате история на месте.
Svyazio('show');
Возвращает скрытый виджет на страницу.
Svyazio('setSkin', 'aurora');
Меняет оформление виджета на лету: classic, aurora или soft. Незнакомое значение игнорируется.
Что происходит: Действует только в текущей вкладке посетителя и не меняет настройку в кабинете. Постоянное оформление задаётся в «Настройки → Виджет».
Svyazio('setButtonPosition', 'bl');
Переставляет круглую кнопку в одну из девяти позиций: bl, bc, br (низ слева, по центру, справа), lt, lm, lb (левый край), rt, rm, rb (правый край).
Svyazio('setButtonSize', 72);
Размер круглой кнопки в пикселях. По умолчанию 60.
Svyazio('setColors', { buttonBg: '#EA580C' });
Переопределяет цвета: buttonBg (фон кнопки), buttonText (иконка), clientBubbleBg (пузырь сообщения посетителя), agentBubbleBg (пузырь оператора). Передавать можно только нужные поля.
Svyazio('setZIndex', 99999);
Поднимает виджет над элементами сайта, если его что-то перекрывает — фиксированная шапка, всплывающее окно, баннер cookie.
Svyazio('setIntegrationData', { … });
Передаёт, кто сейчас на сайте: name, email, phone и любые свои поля (тариф клиента, номер заказа, ID в вашей системе). Оператор видит их в карточке посетителя — имя, почта и телефон отдельно, остальное в блоке «Данные».
Что происходит: Полностью перезаписывает ранее переданные данные. Общий объём произвольных полей ограничен 4 КБ — при превышении обновление отбрасывается целиком. Служебные ключи мессенджеров (например, telegramUserId) не принимаются: они определяют, чьи входящие сообщения куда попадают.
Svyazio('updateIntegrationData', { plan: null });
Обновляет данные посетителя частично: переданные поля заменяются, остальные остаются как были. Значение null удаляет поле.
Svyazio('setGroupId', '<departmentId>');
Направляет обращения с этой страницы в конкретный отдел — например, со страниц оплаты в бухгалтерию. ID отдела берётся в «Настройки → Команда → Отделы»; null сбрасывает маршрутизацию.
Что происходит: Влияет на диалоги, начатые после вызова: уже открытый диалог остаётся в своём отделе. Отделы доступны на тарифе «Про».
Svyazio('setLanguage', 'en');
Переключает язык встроенных строк виджета (плейсхолдер поля ввода, подписи кнопок, «Работает на»). Доступны ru, en, es, pt, de, fr, tr.
Что происходит: Применяется к уже открытому окну сразу. Тексты, заданные в настройках виджета — заголовок, приветствие, сообщение об офлайне — этим методом не переводятся: они одни на всех языках.
Svyazio('setLocale', { … });
Точечно переопределяет отдельные строки интерфейса виджета своим текстом. Если передать строкой код языка, работает как setLanguage.
onNewMessage
Функция в объекте настроек, которую виджет вызывает на каждое новое сообщение в чате: { id, text, createdAt, type }, где type — agent, client или bot. Типичное применение — свой счётчик непрочитанных в заголовке вкладки.
Полное описание команд, параметров и событий — в документации JS API: там те же методы разобраны по одному, с примерами кода, которые можно выполнить прямо на странице.