enВойти в Senler

Методы Public API виджета

Когда нужен Public API

Обычное подключение и настройка канала выполняются по инструкции «Виджет на сайте». Public API нужен после установки кода, если сайт должен сам открывать чат, менять контекст, выбирать диалог, отправлять подготовленный вопрос или реагировать на события виджета.

Отдельно включать Public API в кабинете не нужно: методы появляются в window.SenlerWidget после загрузки кода канала. Настройки, для которых нужен интерфейс кабинета, показаны со скриншотами в связанной инструкции; на этой странице приведены только действия, выполняемые из кода сайта.

Инициализация

Примеры рассчитаны на SDK v3. На основном сервере используйте загрузчик https://widget.senler.io/v3/widget-loader.js; для локального или тестового окружения — его адрес /v3/widget-loader.js. Загрузчик и iframe должны поддерживать протокол 10, а API — v3.

Для обычного JavaScript достаточно подключить загрузчик через <script>: он предоставляет window.SenlerWidget, установка пакета не требуется. Для импортов TypeScript или React установите стабильный пакет @senlerio/widget@3.0.0. Оба способа используют тот же API виджета. Установка пакета не обновляет серверы.

Создайте канал по инструкции со скриншотами, затем скопируйте скрипт-загрузчик и channel_id из раздела «Код для встраивания». На одной странице один раз вызовите SenlerWidget.init(config):

<script src="URL_ИЗ_ГОТОВОГО_КОДА" crossorigin="anonymous"></script>
<script>
  SenlerWidget.init({
    channel_id: "xxx",
  });
</script>

Замените оба плейсхолдера значениями из кабинета; не подставляйте адрес скрипта-загрузчика из примера другого проекта или окружения. Параметры init, режимы размещения, пользователь и тема описаны в «Параметрах инициализации». Инициализация создаёт один экземпляр. Успешный повторный init заменяет текущий экземпляр новым, поэтому после запуска управляйте им методами SenlerWidget, не пересоздавая iframe и не теряя состояние диалога.

Методы

МетодВозвращаетРезультат
SenlerWidget.open()undefinedПоказывает виджет без отправки сообщения или изменения настроек.
SenlerWidget.close()undefinedСкрывает виджет, сохраняя iframe и состояние диалога.
SenlerWidget.toggle()undefinedПереключает видимость.
SenlerWidget.isOpen()booleanПоказывает, открыт ли виджет.
SenlerWidget.selectDialog(dialogId)undefinedВыбирает существующий диалог без отправки сообщения и без автоматического открытия скрытого виджета.
SenlerWidget.setPageContext(items)undefinedЗаменяет постоянный контекст страницы.
SenlerWidget.configure(settings)undefinedМеняет настройки текущего экземпляра, не сохраняя их в настройках канала.
SenlerWidget.refreshRuntime()undefinedПовторно вычисляет настройки через resolveRuntime, например после перехода на другую страницу сайта. Пример.
SenlerWidget.createTextEdit(config)контроллерЗапрашивает и применяет правки текста после подтверждения.
SenlerWidget.create(config)экземплярСоздаёт независимый виджет; несколько embedded-экземпляров требуют разных контейнеров.
SenlerWidget.uploadFile(file, options)Promise вложенияЗагружает файл в указанный диалог, не отправляя сообщение.
SenlerWidget.updateLead(profile)PromiseСохраняет контактные данные текущего лида без повторной инициализации.
SenlerWidget.setDraft(options)PromiseЗаполняет поле ввода без отправки; по умолчанию защищает уже введённый текст.
SenlerWidget.resetSession()PromiseОчищает авторизацию и уничтожает экземпляр, сохраняя историю на сервере.
SenlerWidget.ask(options)Promise результатаОтправляет вопрос и возвращает ответы и статусы.
SenlerWidget.getOrCreateDialog(options)Promise диалогаНаходит или создаёт диалог посетителя по ref.
SenlerWidget.startNewDialog(options?)Promise IDСоздаёт и выбирает пустой диалог без сообщения.
SenlerWidget.setContext(context)undefinedЗаменяет JSON-контекст сайта; каждый ask получает его снимок.
SenlerWidget.setAnalytics(analytics)PromiseПередаёт идентификаторы аналитики и данные визита.
SenlerWidget.registerAction(name, definition)функция удаленияДобавляет действие сайта без замены остальных.
SenlerWidget.on(event, handler)функция отпискиПодписывает на события экземпляра.
SenlerWidget.destroy()undefinedПолностью удаляет iframe, кнопку и обработчики. Переданный сайтом embedded-контейнер остаётся на странице.

Для обычного скрытия используйте close(), а не destroy(). После close() достаточно вызвать open(); после destroy() нужен новый SenlerWidget.init(...).

До готовности экземпляра isOpen() возвращает false. В режимах button_only и headless методы открытия и закрытия ничего не показывают; подробности приведены в настройках.

После загрузки скрипта-загрузчика в SenlerWidget.runtimeProtocolVersion доступен номер текущего протокола (number). Это диагностическое значение для проверки совместимости; не связывайте с конкретным номером бизнес-логику сайта.

Данные для собственного чата

Эти методы доступны у готового экземпляра с обычным интерфейсом и с headless: true. В таблице options означает объект параметров; ? обозначает необязательное поле. Последовательный пример показывает выбор диалога, историю, отправку и подписку.

МетодВозвращаетПараметры и результат
SenlerWidget.getSettings(options?)Promise настроекФункции чата, доступность агента и кредитов, приветствие и начальные вопросы.
SenlerWidget.getDialogs(options?)Promise страницыlimit?, before?, query?, offset?: список видимых диалогов посетителя.
SenlerWidget.getMessages(options)Promise страницыdialogId, limit?, before? или after?: сообщения от старых к новым.
SenlerWidget.getDialogState(options)Promise состоянияdialogId, ref?: непрочитанные, набор ответа, очередь вопросов и причина паузы.
SenlerWidget.getWelcome(options?)Promise приветствияПредпросмотр приветствия без создания диалога.
SenlerWidget.subscribeDialog(options)функция отпискиdialogId, ref?, limit?, onUpdate, onError: начальная история и дальнейшие изменения диалога.
SenlerWidget.markRead(options)Promise<void>dialogId: отмечает текущие сообщения прочитанными, когда сайт действительно показывает их посетителю.
SenlerWidget.setTyping(options)Promise<void>dialogId, typing: начало или окончание набора сообщения.
SenlerWidget.clickButton(options)Promise<void>dialogId, eventId, button, pollSelectedInstanceIds?: выполняет действие возвращённой сервером кнопки.
SenlerWidget.updateQueuedQuestion(options)Promise<void>dialogId, questionId, revision, text: изменяет ожидающий вопрос с проверкой его версии.
SenlerWidget.cancelQueuedQuestion(options)Promise<void>dialogId, questionId: удаляет ещё не отправленный вопрос из очереди.
SenlerWidget.sendQueuedQuestion(options)Promise<void>dialogId, questionId: выполняет команду «Отправить сейчас» для вопроса в очереди.
SenlerWidget.getScheduledActions(options)Promise страницыdialogId, cursor?: доступные посетителю отложенные действия.
SenlerWidget.cancelScheduledAction(options)Promise<void>dialogId, actionId: отменяет ожидающее отложенное действие, если сервер разрешает отмену.

Все методы этой таблицы принимают signal для отмены ожидания и timeoutMs: по умолчанию 30 000 мс, максимум 300 000 мс. Для subscribeDialog тайм-аут действует до начальной синхронизации; далее подписка работает до отписки, отмены, сброса сессии или уничтожения экземпляра. Остановка ожидания не гарантирует отмену уже принятого сервером действия. Тайм-аут ожидания ответов ask описан отдельно.

Настройки и события

Связанные страницы

Предыдущая
Inline-правки
Далее
Runtime-настройки