TypeScript и React

Используйте официальные типы виджета, React-компонент и хуки из пакета @senlerio/widget.

Подключите пакет

Пакет @senlerio/widget содержит типы API, конфигурации и событий, а также загрузчик. Он не подключает UI-библиотеку и не требует React для обычного JavaScript или TypeScript:

npm install https://github.com/SenlerBot/senler-widget/archive/refs/tags/v2.2.0.tar.gz

Для работы SDK загрузчик и iframe должны поддерживать уведомления об успешной инициализации и ошибке (onReady и onError). Параметр surfaceVisible, выбор настроек через resolveRuntime / refreshRuntime и навигация pageElementActions.navigate требуют соответствующей поддержки в загрузчике и iframe. Установка пакета обновляет типы и код интеграции, но не размещённые скрипт-загрузчик и приложение виджета.

import { loadSenlerWidget, type SenlerWidgetInitConfig } from "@senlerio/widget";

const config = { channel_id: "CHANNEL_ID" } satisfies SenlerWidgetInitConfig;
const widget = await loadSenlerWidget({ src: "LOADER_URL_FROM_CABINET" });
widget.init(config);

Если скрипт уже подключён вручную, import "@senlerio/widget/global" добавит типы для window.SenlerWidget и событий окна. Для импорта только типов используйте import type. Загрузчик разделяет параллельные запросы, проверяет совместимость протокола и возвращает ошибку при таймауте.

Компонент React

Для React 18/19 используйте компонент из отдельного пути того же пакета:

import { useMemo } from "react";
import { SenlerWidget } from "@senlerio/widget/react";

export function Chat({ channelId }: { channelId: string }) {
  const config = useMemo(() => ({ channel_id: channelId }), [channelId]);
  return <SenlerWidget
    src="LOADER_URL_FROM_CABINET"
    config={config}
    containerProps={{ style: { height: 600 } }}
  />;
}

Компонент создаёт embedded-контейнер и освобождает экземпляр при размонтировании, включая React StrictMode. Для существующего контейнера используйте useSenlerWidgetController; SenlerWidgetProvider и useSenlerWidget дают дочерним компонентам доступ к API и статусу загрузки. Сохраняйте config через useMemo, чтобы обычный рендер не пересоздавал виджет. На странице одновременно может быть один экземпляр. Изменение retryKey повторяет загрузку после ошибки.

config={null} откладывает запуск, например до получения подписанных данных пользователя. Контроллер и useSenlerWidget возвращают { api, status, error }; status принимает idle, loading, ready или failed. ready означает готовность чата после инициализации и авторизации, а не только загрузку скрипта.

Для изменения приветствия, языка, темы, скругления, shell, видимости surfaceVisible, набора customActions, их языка, autoExecuteCustomActionNames или pageContextItems передайте runtime компоненту SenlerWidget или SenlerWidgetProvider. Это обновляет текущий экземпляр без нового init:

<SenlerWidget
  src="LOADER_URL_FROM_CABINET"
  config={config}
  runtime={{ lang: "ru", theme_mode: "dark", border_radius: 16 }}
  containerProps={{ style: { height: 600 } }}
/>

Разовые команды, включая отправку сообщения и выбор диалога, выполняйте через api.open(...), api.updateRuntime(...) или api.selectDialog(...) в обработчике действия пользователя. Они не входят в prop runtime, чтобы рендер компонента не повторял отправку. Самостоятельный useSenlerWidgetController не принимает runtime: обновляйте настройки через возвращённый api.