Widget API

Callback-функции

onWidgetReady()

onWidgetReady() позволяет выполнить код после полной загрузки виджета.

Например:

обновить интерфейс страницы;
отправить событие в аналитику;
выполнить дополнительную инициализацию.

Вызывайте onWidgetReady() до run().

Метод	Сигнатура	Описание
`onWidgetReady:`	`(callback: () => void) => void`	Подписка на изменение состояния окна

<script defer>
 (() => {
   const loadScript = (callback) => {
     const widgetId = 'YOUR_WIDGET_ID' // Replace with YOUR_WIDGET_ID

     const script = document.createElement('script');
     script.type = 'text/javascript';
     script.async = true;
     script.src = `//widget.vivochat.ai/script/widget/${widgetId}`;
     script.onload = callback;

     const sourceScript = document.getElementsByTagName('script')[0];
     sourceScript.parentNode.insertBefore(script, sourceScript);
   }

   const initWidget = () => {
     const withIcon = true;

     vivo_api.onWidgetReady(() => {
       console.log('VivoChat widget loaded');
     });

     vivo_api.run({withIcon});
   }

   loadScript(initWidget)
 })();
</script>

Важно

onWidgetReady() необходимо вызывать до run();
callback вызывается один раз при запуске виджета;
ошибки внутри callback могут прервать инициализацию виджета.

onOpenStateChange()

onOpenStateChange() отслеживает открытие и закрытие окна чата.

Callback получает:

true — окно открыто;
false — окно закрыто.

Метод	Сигнатура	Описание
`onOpenStateChange:`	`(callback: OpenStateCallback) => Unsubscribe`	Подписка на изменение состояния окна

/**
 * Функция обратного вызова для отслеживания состояния.
 */
type OpenStateCallback = (isOpen: boolean) => void;

/**
 * Функция отписки от события.
 */
type Unsubscribe = () => void;

vivo_api.onOpenStateChange((isOpen) => {
  if (isOpen) {
    console.log('widget opened')
  } else {
    console.log('widget closed')
  }
})

Отписка от события

onOpenStateChange() возвращает функцию отмены подписки.

const unsubscribe = vivo_api.onOpenStateChange((isOpen) => {
    console.log(isOpen);
});

unsubscribe();

Важно

callback вызывается при открытии и закрытии окна;
onOpenStateChange() работает как для кнопки виджета, так и для vivo_api.open();
callback регистрируется один раз и продолжает работать до отмены подписки.

onUnreadCountChange()

onUnreadCountChange() отслеживает изменение количества непрочитанных сообщений.

Callback получает:

count: number — текущее количество непрочитанных сообщений.

Метод	Сигнатура	Описание
`onUnreadCountChange:`	`(callback: UnreadCountCallback) => Unsubscribe`	Подписка на изменение количества непрочитанных сообщений

/**
 * Функция обратного вызова для отслеживания состояния.
 */
type UnreadCountCallback = (count: number) => void;

/**
 * Функция отписки от события.
 */
type Unsubscribe = () => void;

vivo_api.onUnreadCountChange((count) => {
  console.log(count)
})

Отписка от события

onUnreadCountChange() возвращает функцию отмены подписки.

const unsubscribe = vivo_api.onUnreadCountChange((count) => {
  console.log(count);
});

unsubscribe();

Важно

callback вызывается при изменении количества непрочитанных сообщений;
callback вызывается сразу после подписки с текущим значением;
счётчик сбрасывается в 0 при открытии окна чата;
callback продолжает работать до отмены подписки.

onError()

onError() отслеживает ошибки виджета.

Используйте onError(), чтобы логировать ошибки виджета или передавать их в систему мониторинга.

Callback получает объект ошибки:

message: string — описание ошибки;
source: string — источник ошибки.

Метод	Сигнатура	Описание
`onError()`	`(callback: ErrorCallback) => Unsubscribe`	Подписка на ошибки виджета

/**
 * Объект ошибки
 */
type Error = {
  message: string,
  source: string,
}

/**
 * Функция обратного вызова для отслеживания состояния.
 */
type ErrorCallback = (error: Error) => void;

/**
 * Функция отписки от события.
 */
type Unsubscribe = () => void;

vivo_api.onError(({ message, source }) => {
  console.error(`[VivoChat error] ${source}: ${message}`);
});

Отписка от события

onError() возвращает функцию отмены подписки.

const unsubscribe = vivo_api.onError((error) => {
  console.log(error);
});

unsubscribe();

Важно

callback вызывается при ошибках соединения и авторизации;
ошибки не останавливают работу виджета;
callback продолжает работать до отмены подписки.

onLoadCallback() `deprecated`

onLoadCallback() позволяет выполнить код после полной загрузки виджета.

Например:

обновить интерфейс страницы;
отправить событие в аналитику;
выполнить дополнительную инициализацию.

Вызывайте onLoadCallback() до run().

Метод	Сигнатура	Описание
`onLoadCallback:`	`(callback: () => void) => void`	Подписка на изменение состояния окна

<script defer>
 (() => {
   const loadScript = (callback) => {
     const widgetId = 'YOUR_WIDGET_ID' // Replace with YOUR_WIDGET_ID

     const script = document.createElement('script');
     script.type = 'text/javascript';
     script.async = true;
     script.src = `//widget.vivochat.ai/script/widget/${widgetId}`;
     script.onload = callback;

     const sourceScript = document.getElementsByTagName('script')[0];
     sourceScript.parentNode.insertBefore(script, sourceScript);
   }

   const initWidget = () => {
     const withIcon = true;

     vivo_api.onLoadCallback(() => {
       console.log('VivoChat widget loaded');
     });

     vivo_api.run({withIcon});
   }

   loadScript(initWidget)
 })();
</script>

Важно

onLoadCallback() необходимо вызывать до run();
callback вызывается один раз при запуске виджета,
ошибки внутри callback могут прервать инициализацию виджета,

Методы

run()

run() запускает виджет на странице.

Используйте run() после загрузки скрипта виджета, чтобы отобразить виджет на сайте.

Метод	Сигнатура	Описание
`run:`	`(props: Props) => void`	Запускает виджет

/**
* Параметры для запуска виджета
*/
type Props = {
  withIcon?: boolean; // true — показывает встроенную кнопку виджета, false — скрывает её
}

Запуск виджета со встроенной кнопкой чата.

<script defer>
  (() => {
    const loadScript = (callback) => {
      const script = document.createElement('script');

      script.type = 'text/javascript';
      script.async = true; // Loads the widget asynchronously
      script.src = '//widget.vivochat.ai/script/widget/YOUR_WIDGET_ID'; // Replace with your Widget ID
      script.onload = callback; // Runs callback after the widget script is loaded

      const ss = document.getElementsByTagName('script')[0];
      ss.parentNode.insertBefore(script, ss); // Inserts the widget script into the page
    }

    const initWidget = () => {
      // Starts the widget with the default chat icon
      vivo_api.run({ withIcon: true });
    }

    loadScript(initWidget)
  })();
</script>

Скрытый запуск виджета

Если необходимо скрыть встроенную кнопку виджета, передайте withIcon: false.

В этом случае чат можно открыть через vivo_api.open().

vivo_api.run({ withIcon: false });

Важно

run() необходимо вызывать после загрузки скрипта виджета;
до вызова run() методы Widget API недоступны;
run() вызывается один раз после загрузки страницы;
повторный вызов run() может создать второй экземпляр виджета;
после запуска становятся доступны методы open(), close(), isOpen() и другие.

open()

open() открывает окно чата.

Используйте open(), чтобы открывать чат через собственную кнопку сайта.

Метод	Сигнатура	Описание
`open`	`() => Promise<void>`	Открывает окно чата

<button id="open-chat">
    open widget
</button>

<script defer>
  (() => {
    const button = document.getElementById('open-chat');

    button.addEventListener('click', () => {
      vivo_api.open();
    });

  })();
</script>

Важно

open() необходимо вызывать после run();
open() работает как с withIcon: true, так и с withIcon: false;
если окно уже открыто, повторный вызов open() не создаёт новый экземпляр чата;
состояние окна можно проверить через vivo_api.isOpen().

close()

close() скрывает окно чата, но не удаляет виджет со страницы.

Используйте close(), если нужно закрыть чат

Метод	Сигнатура	Описание
`close:`	`() => void`	Закрывает окно чата

<button id="close-chat">
    Close chat
</button>

<script defer>
  (() => {
    const closeButton = document.getElementById('close-chat');

    closeButton.addEventListener('click', () => {
      vivo_api.close();
    })
  })();
</script>

Важно

close() необходимо вызывать после run();
метод скрывает окно чата, но не удаляет виджет со страницы;
close() не сбрасывает сессию и не удаляет историю диалога;
после close() чат можно снова открыть через open();
состояние окна можно проверить через vivo_api.isOpen();

isOpen()

isOpen() позволяет проверить, открыто ли окно чата.

Метод	Сигнатура	Описание
`isOpen()`	`() => boolean`	Возвращает `true`, если окно чата открыто

<button id="toggle-chat">
    Open chat
</button>

<script defer>
  (() => {
    const button = document.getElementById('toggle-chat');

    button.addEventListener('click', async () => {
      if (vivo_api.isOpen()) {
        vivo_api.close();
        button.textContent = 'Open chat';

        return;
      }

      await vivo_api.open();
      button.textContent = 'Close chat';
    });
  })();
</script>

Важно

isOpen() необходимо вызывать после run();
isOpen() возвращает текущее состояние окна сразу, без ожидания событий;
isOpen() возвращает:
true — окно открыто;
false — окно закрыто.

destroy()

destroy() полностью удаляет виджет со страницы.

В отличие от close(), метод очищает состояние виджета, закрывает WebSocket-соединение и удаляет DOM-элементы виджета.

Используйте destroy() перед повторным запуском виджета, выходом пользователя из аккаунта или сменой пользователя.

Метод	Сигнатура	Описание
`destroy`	`() => void`	Полностью удаляет виджет со страницы

vivo_api.destroy();

Важно

destroy() полностью удаляет виджет со страницы;
метод очищает состояние виджета и закрывает WebSocket-соединение;
после destroy() методы Widget API становятся недоступны до следующего вызова run();
используйте destroy() перед повторным вызовом run();
close() скрывает окно чата, но не удаляет виджет со страницы.

hasUnreadCount()

hasUnreadCount() возвращает текущее количество непрочитанных сообщений.

Несмотря на название, метод возвращает число непрочитанных сообщений, а не boolean.

Используйте hasUnreadCount(), если необходимо получить текущее значение счётчика сразу после инициализации виджета.

Метод	Сигнатура	Описание
`hasUnreadCount:`	`() => number`	Возвращает количество непрочитанных сообщений

const count = vivo_api.hasUnreadCount();

console.log(`unread message count: ${count}`)

Важно

hasUnreadCount() необходимо вызывать после run();
метод возвращает текущее значение счётчика синхронно;
значение счётчика сохраняется между перезагрузками страницы;
hasUnreadCount() возвращает текущее состояние счётчика;
для обновления счётчика в реальном времени используйте onUnreadCountChange();
счётчик сбрасывается в 0 после открытия окна чата.

setUserToken()

setUserToken() передает идентификатор для последующей верификации вашего клиента в VivoChat.

Используйте setUserToken(), если необходимо проводить верификацию клиента и передавать информацию о нем в VivoChat и отображать историю переписки. Подробнее в разделе «Верификация клиентов».

Метод	Сигнатура	Описание
`setUserToken`	`(token: string) => void`	Передаёт токен пользователя в виджет

Как это работает

setUserToken() сохраняет идентификатор пользователя в сессии виджета.

Токен может быть любой строкой:

session token;
ID пользователя;
любой другой идентификатор пользователя в вашей системе.

VivoChat не имеет доступа к вашей базе данных и не проверяет токен самостоятельно.

const USER_TOKEN = 'USER_TOKEN';

vivo_api.setUserToken(USER_TOKEN)

/* ... */

vivo_api.run()

Важно

setUserToken() необходимо вызывать до run();
токен не проверяется на стороне VivoChat;
если не передать токен, виджет работает как анонимный чат;
при выходе пользователя рекомендуется вызвать destroy() и повторно запустить виджет;
при смене пользователя необходимо вызвать destroy() перед повторным run().

setContactInfo()

setContactInfo() передаёт контактные данные пользователя в VivoChat.

Используйте setContactInfo(), если необходимо:

показать оператору имя, телефон или email пользователя.

Метод	Сигнатура	Описание
`setContactInfo:`	`(info: Info) => void`	Передаёт контактные данные пользователя

/**
 * Контактные данные пользователя
 */
type Info = {
  name?: string, // Имя пользователя
  phone?: string, // Телефон пользователя
  email?: string, // Email пользователя
}

Как это работает

setContactInfo() передаёт контактные данные пользователя в VivoChat.

После передачи данных оператор увидит имя, телефон и email пользователя в разделе «Контакты» в текущем диалоге в VivoChat.

В отличие от setUserToken(), метод не участвует в верификации клиента.

Если необходимо передать дополнительную информацию о пользователе, используйте событие chat_accepted через webhook. Поля и структура передаваемых данных полностью определяются на стороне вашего сайта.

vivo_api.setContactInfo({
  name: 'John Smith',
  phone: '+1 555 123 4567',
  email: '[email protected]'
});

/* ... */

vivo_api.run();

Важно

setContactInfo() рекомендуется вызывать до run();
все поля метода опциональны;
setContactInfo() не используется для верификации пользователя;
для идентификации и восстановления истории диалогов используйте setUserToken() и client_check_token, подробно описано в разделе «Верификация клиентов».

setRegion()

setRegion() указывает код канала маршрутизации для виджета.

Используйте setRegion(), если необходимо направлять обращения:

в разные языковые каналы;
в разные команды поддержки;
в разные категории обращений.

Метод	Сигнатура	Описание
`setRegion:`	`(region: string) => void`	Указывает код маршрутизации для виджета

vivo_api.setRegion('en')

/*...*/

vivo_api.run()

Как это работает

setRegion() передаёт код маршрутизации при запуске виджета. Для маршрутизации необходимо заранее настроить дополнительные каналы в интерфейсе VivoChat. Для всех каналов используется один общий Widget ID на сайте.

Если код маршрутизации не передан или не найден, обращения попадут в основной канал. Подробнее настройка маршрутизации описана в разделе «Маршрутизация обращений».

Важно

setRegion() необходимо вызывать до run();
код маршрутизации должен полностью совпадать с кодом в настройках VivoChat;
для смены маршрутизации после запуска виджета используйте destroy() → setRegion() → run().

onUnmount() `deprecated`

onUnmount() полностью удаляет виджет со страницы.

В отличие от close();, метод очищает состояние виджета, закрывает WebSocket-соединение и удаляет DOM-элементы виджета.

Используйте onUnmount() перед повторным запуском виджета, выходом пользователя из аккаунта или сменой пользователя.

Метод	Сигнатура	Описание
`onUnmount:`	`() => void`	Полностью удаляет виджет со страницы

vivo_api.onUnmount();

Важно

onUnmount() полностью удаляет виджет со страницы;
метод очищает состояние виджета и закрывает WebSocket-соединение;
после onUnmount() методы Widget API становятся недоступны до следующего вызова run();
используйте onUnmount() перед повторным вызовом run();
close() скрывает окно чата, но не удаляет виджет со страницы.

Widget API

Callback-функции

onWidgetReady()

Важно

onOpenStateChange()

Отписка от события

Важно

onUnreadCountChange()

Отписка от события

Важно

onError()

Отписка от события

Важно

onLoadCallback() deprecated

Важно

Методы

run()

Скрытый запуск виджета

Важно

open()

Важно

close()

Важно

isOpen()

Важно

destroy()

Важно

hasUnreadCount()

Важно

setUserToken()

Как это работает

Важно

setContactInfo()

Как это работает

Важно

setRegion()

Как это работает

Важно

onUnmount() deprecated

Важно

onLoadCallback() `deprecated`

onUnmount() `deprecated`