JavaScript API · v4.0

Управляйте чатом прямо из своего сайта

Открывайте чат по клику, синхронизируйте тему с сайтом, меняйте фирменные цвета и подключайте аналитику — без перезагрузки страницы.

Начать интеграцию Справочник API

Команды в очереди

Можно вызывать до загрузки

Темы на лету

Изменения без перезагрузки

Изолированный iframe

Стили сайта не конфликтуют

Установка

Одна строка перед закрывающим тегом body. Персональную ссылку скопируйте в разделе «Виджет для сайта». Скрипт асинхронный и не блокирует загрузку страницы.

HTML

<script
  src="https://widget.poymai.ru/YOUR_ORG_ID.js"
  async
></script>

Важно

Замените YOUR_ORG_ID на ID из настроек. Не используйте один ID для разных организаций.

Проверка установки

JavaScript

// Команды можно вызывать сразу — даже до загрузки виджета
PoymaiWidget.open();

// Контакты посетителя с вашего сайта: чат не будет спрашивать их сам
PoymaiWidget.identify({ name: "Анна", phone: "+79991234567", email: "anna@example.com" });

// Автосообщение с условием «Событие с сайта»
PoymaiWidget.track("cart_abandoned");

PoymaiWidget.setColors({
  primary: "#6D5EF5",
  secondary: "#A855F7"
});

Методы API

Все управляющие методы, кроме чтения состояния и destroy, возвращают экземпляр API — команды можно объединять в цепочки.

PoymaiWidget.open()

Открывает окно чата. Безопасно вызывать до загрузки.

PoymaiWidget.close()

Закрывает окно чата, сохраняя текущую сессию.

PoymaiWidget.toggle()

Переключает открытое и закрытое состояние.

PoymaiWidget.show() / hide()

Показывает или полностью скрывает виджет на странице.

PoymaiWidget.setTheme(theme)

Меняет тему: light, dark или auto.

PoymaiWidget.setColors(colors)

Обновляет палитру на лету, без перезагрузки чата.

PoymaiWidget.configure(options)

Применяет любые разрешённые настройки во время работы.

PoymaiWidget.identify(visitor)

Передаёт имя, телефон и email посетителя — чат не будет спрашивать их сам.

PoymaiWidget.track(eventName)

Запускает автосообщения с условием «Событие с сайта».

PoymaiWidget.getState()

Возвращает снимок состояния, геометрию и runtime-настройки.

PoymaiWidget.on() / off() / once()

Подписывает на события жизненного цикла виджета.

PoymaiWidget.destroy()

Удаляет кнопку, окно чата и обработчики со страницы.

JavaScript

// Открыть чат по вашей кнопке
document.querySelector("#help")
  .addEventListener("click", () => {
    PoymaiWidget.open();
  });

JavaScript

// Дождаться полной готовности
await PoymaiWidget.ready;

const state = PoymaiWidget.getState();
console.log(state.isOpen);

Темы и цвета

Передавайте только изменяемые значения — остальная конфигурация сохранится.

Готовая тема

Режим auto следует системной теме посетителя.

PoymaiWidget.setTheme("auto")

Палитра бренда

Цвета принимаются в строгом шестизначном HEX.

JavaScript

PoymaiWidget
  .setTheme("dark")
  .setColors({
    primary: "#6D5EF5",
    secondary: "#A855F7",
    background: "#111827",
    userText: "#FFFFFF",
    agentBackground: "#1F2937",
    agentText: "#F8FAFC"
  });

Настройки до загрузки скрипта

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

HTML

<script>
  window.PoymaiWidgetConfig = {
    theme: "dark",
    position: "right",
    colors: {
      primary: "#6D5EF5",
      secondary: "#A855F7"
    },
    launcherLabel: "Напишите нам",
    showLauncherLabel: true
  };
</script>
<script src="https://widget.poymai.ru/YOUR_ORG_ID.js" async></script>

Настройки из кода действуют до перезагрузки страницы и не меняют сохранённую конфигурацию организации в Poymai.

Конфигурация

Значения проверяются внутри виджета. Неизвестные поля игнорируются, некорректные заменяются безопасными значениями.

Параметр	По умолчанию	Допустимо	Назначение
`theme / widgetTheme`	`"auto"`	light · dark · auto	Цветовая тема
`primaryColor`	`"#3b82f6"`	HEX	Основной цвет и сообщения клиента
`secondaryColor`	`"#8b5cf6"`	HEX	Второй цвет градиента
`position`	`"right"`	left · right	Сторона экрана
`offsetX / offsetY`	`20`	8–80	Отступы от краёв, px
`chatWidth`	`380`	320–480	Ширина окна, px
`chatHeight`	`560`	420–720	Высота окна, px
`buttonSize`	`60`	44–80	Размер кнопки запуска, px
`launcherStyle`	`"circle"`	circle · square · pill	Форма кнопки; pill — с текстом
`stylePreset`	`"glass"`	glass · minimal · vivid · dark · corporate	Стиль окна чата
`borderRadius`	`22`	0–32	Скругление окна, px
`headerTitle`	`"PoymAI"`	до 80	Заголовок чата
`headerSubtitle`	`"Онлайн"`	до 120	Подзаголовок
`launcherLabel`	`"Есть вопрос?"`	до 100	Подпись около кнопки
`showLauncherLabel`	`false`	boolean	Показывать подпись
`launcherPulse`	`true`	boolean	Мягкая анимация кнопки
`autoOpenDelay`	`0`	0–120	Автооткрытие через N секунд
`widgetLanguage`	`"auto"`	auto · ru · en	Язык интерфейса
`showMessageTime`	`true`	boolean	Время сообщений
`allowAttachments`	`true`	boolean	Загрузка файлов
`enableSound`	`true`	boolean	Звук новых сообщений
`enableMarkdown`	`true`	boolean	Списки, жирный текст и ссылки в ответах
`enableEmoji`	`true`	boolean	Выбор эмодзи
`hideOnMobile`	`false`	boolean	Не показывать на экранах уже 640 px
`responseTimeText`	`""`	до 80	«Отвечаем за 5 минут» рядом со статусом

JavaScript

PoymaiWidget.configure({
  position: "left",
  offsetX: 24,
  offsetY: 24,
  headerTitle: "Поддержка Acme",
  launcherLabel: "Поможем с выбором",
  showLauncherLabel: true,
  autoOpenDelay: 12
});

События

Подписка возвращает функцию отписки. Те же события доступны как DOM CustomEvent с префиксом poymai:widget:.

JavaScript

const unsubscribe = PoymaiWidget.on("open", (state) => {
  analytics.track("Support chat opened");
});

PoymaiWidget.on("unread", ({ unreadCount }) => {
  document.title = `(${unreadCount}) Новое сообщение`;
});

// Когда обработчик больше не нужен
unsubscribe();

ready

API и интерфейс полностью готовы; очередь команд выполнена.

open / close

Пользователь или API изменил состояние окна.

state

Изменилось состояние, размер, тема или подключение.

unread

Счётчик непрочитанных сообщений увеличился.

show / hide

Видимость виджета изменена через API.

trigger

Показано автосообщение; в деталях — id и тип условия.

load

Окно чата загрузилось (это происходит при первом наведении или открытии).

error

Окно чата не загрузилось за 12 секунд; при следующем открытии будет новая попытка.

DOM-вариант

window.addEventListener("poymai:widget:open", handler)

TypeScript

Добавьте декларацию в global.d.ts вашего проекта и дополните интерфейсы нужными полями из таблицы конфигурации.

TypeScript

type PoymaiTheme = "light" | "dark" | "auto";
type PoymaiEvent =
  | "ready" | "open" | "close" | "state" | "unread"
  | "show" | "hide" | "load" | "error" | "trigger";

interface VisitorIdentity {
  name?: string;
  phone?: string;
  email?: string;
}

interface WidgetColors {
  primary?: string;
  secondary?: string;
  background?: string;
  userText?: string;
  agentBackground?: string;
  agentText?: string;
}

interface WidgetOptions {
  theme?: PoymaiTheme;
  colors?: WidgetColors;
  position?: "left" | "right";
  primaryColor?: string;
  secondaryColor?: string;
  [key: string]: unknown;
}

interface WidgetState {
  ready: boolean;
  isOpen: boolean;
  visible: boolean;
  unreadCount: number;
  position: "left" | "right";
}

interface PoymaiWidgetApi {
  readonly version: string;
  readonly ready: Promise<PoymaiWidgetApi>;
  open(): this;
  close(): this;
  toggle(): this;
  show(): this;
  hide(): this;
  setTheme(theme: PoymaiTheme): this;
  setColors(colors: WidgetColors): this;
  configure(options: WidgetOptions): this;
  identify(visitor: VisitorIdentity): this;
  track(eventName: string): this;
  getState(): WidgetState;
  isReady(): boolean;
  isOpen(): boolean;
  on(event: PoymaiEvent, handler: (state: WidgetState) => void): () => void;
  off(event: PoymaiEvent, handler: (state: WidgetState) => void): this;
  once(event: PoymaiEvent, handler: (state: WidgetState) => void): () => void;
  destroy(): void;
}

declare const PoymaiWidget: PoymaiWidgetApi;

Безопасность

Виджет изолирован от страницы и принимает команды только от ожидаемого окна и домена.

Проверка origin

Сообщения между страницей и iframe валидируются по источнику и домену.

Строгая конфигурация

Цвета, размеры, тексты и перечисления нормализуются перед отображением.

Очередь команд

Вызовы до готовности сохраняются и выполняются в исходном порядке.

Без блокировки сайта

Асинхронный загрузчик и отдельный iframe не мешают основному интерфейсу.

Готовы подключить виджет?

Скопируйте персональный код и настройте внешний вид в панели Poymai.

Открыть настройки