Изменение настроек во время работы
Сначала инициализируйте виджет. Для выбора настроек по условиям сайта используйте resolveRuntime, а для временного изменения текущего экземпляра — методы ниже.
Runtime-параметры
Runtime-параметры — это временное состояние текущего экземпляра. Они не сохраняются в настройках канала и сбрасываются после destroy() или повторного init. open(config?) и updateRuntime(config) принимают одинаковую конфигурацию:
| Параметр | Тип | Что меняет |
|---|---|---|
welcome | object | null | Выбор приветствия: { mode: "centered_text" } или { mode: "automation_message", automation_id, node_id } из сообщений, разрешённых в настройках канала. null возвращает приветствие из настроек канала. История начатого диалога сохраняется; выбор действует для следующего нового диалога. |
lang | "ru" | "en" | "auto" | Язык интерфейса. |
display_mode | "popup" | "embedded" | Режим размещения. Контейнер для embedded должен быть передан ещё при init. |
surfaceVisible | boolean | Сообщает, виден ли контейнер посетителю. false приостанавливает отметку прочтения, но не скрывает контейнер и не останавливает запросы. Пример скрываемой панели. |
theme_mode | "light" | "dark" | "auto" | Тему текущего экземпляра. |
border_radius | number | Скругление текущего экземпляра от 0 до 50. |
shell | object | collapse_button и mobile_edge_swipe. |
customActions | object | Полный набор доступных действий сайта и их обработчики handler в браузере. returnsResult: true у действия разрешает вызов агентом с возвратом результата. |
customActionsLanguage | "ru" | "en" | Язык описаний действий. |
autoExecuteCustomActionNames | string[] | Имена действий, которые разрешено автоматически выполнить в текущем сценарии. |
dialogId | string | Существующий диалог, который нужно выбрать. |
startNewDialog | boolean | При true создаёт новый пустой диалог. |
focusInput | boolean | При true ставит фокус в поле ввода. |
pageContextItems | array | Заменяет постоянный контекст страницы. Для навигации понятнее setPageContext(items). |
contextItems | array | Передаёт одноразовый контекст следующего сообщения. |
message | object | Подготавливает или автоматически отправляет сообщение. |
Ограничения параметров
Если передан dialogId, виджет выбирает этот диалог; ID должен быть непустой строкой длиной до 200 символов. startNewDialog: true создаёт пустой диалог, а message.startNewDialog: true отправляет сообщение без текущего dialog_id. Если вместе передать dialogId и любой вариант startNewDialog: true, приоритет получает новый диалог, поэтому не объединяйте эти намерения в одном вызове. Не считайте autoExecuteCustomActionNames постоянным разрешением: передавайте список заново в каждом сценарии, где нужен автоматический запуск. Подходящие кнопки скрываются; из одного ответа виджет автоматически выполняет только первое совпавшее действие.
В autoExecuteCustomActionNames можно передать не более 20 уникальных имён. Каждое имя должно соответствовать тем же правилам, что и имя custom action: от 1 до 120 символов, первая буква — латинская, далее допустимы латинские буквы, цифры, _, ., : и -. Повторяющееся имя делает конфигурацию недопустимой. Указывайте только объявленные действия: имя без соответствующего customActions не сможет вызвать обработчик сайта.
message принимает { text, requestId?, startNewDialog?, autoSend? }. Текст должен быть непустой строкой до 10 000 символов, requestId — непустой строкой до 200 символов. autoSend: true отправляет сообщение после готовности виджета; false или отсутствие параметра только подставляет текст в поле ввода. Для такого черновика не передавайте requestId: события результата предназначены для автоматической отправки, а скрипт-загрузчик будет ждать начало запроса и сообщит об ошибке, если пользователь не отправит его в течение 10 секунд.
Неизвестный временный ключ, неверный тип или значение вне допустимого диапазона приводят к синхронной ошибке вызова. В рабочем коде передавайте только поля из этой таблицы и перехватывайте ошибки вокруг динамически собранной конфигурации.
В SPA не вызывайте destroy() и повторный init() при каждом переходе. Обновляйте страницу через setPageContext(items), а для точечного сценария используйте open({ contextItems, message }).
Полный пример отправки и обработки ошибок приведён в статье «Отправка сообщений с сайта». Обработчики готовности и запуска описаны в «Событиях виджета».