Widget API

Callback functions

onWidgetReady()

onWidgetReady() lets you run code after the widget has fully loaded.

For example:

update the page interface;
send an event to analytics;
perform additional initialization.

Call onWidgetReady() before run().

Method	Signature	Description
`onWidgetReady:`	`(callback: () => void) => void`	Subscribe to window state changes

<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>

Important

onWidgetReady() must be called before run();
the callback is invoked once when the widget starts;
errors inside the callback may interrupt widget initialization.

onOpenStateChange()

onOpenStateChange() tracks the opening and closing of the chat window.

The callback receives:

true — the window is open;
false — the window is closed.

Method	Signature	Description
`onOpenStateChange:`	`(callback: OpenStateCallback) => Unsubscribe`	Subscribe to window state changes

/**
 * Callback function for tracking the state.
 */
type OpenStateCallback = (isOpen: boolean) => void;

/**
 * Function for unsubscribing from the event.
 */
type Unsubscribe = () => void;

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

Unsubscribing from the event

onOpenStateChange() returns an unsubscribe function.

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

unsubscribe();

Important

the callback is invoked when the window opens and closes;
onOpenStateChange() works both for the widget button and for vivo_api.open();
the callback is registered once and keeps working until the subscription is cancelled.

onUnreadCountChange()

onUnreadCountChange() tracks changes in the number of unread messages.

The callback receives:

count: number — the current number of unread messages.

Method	Signature	Description
`onUnreadCountChange:`	`(callback: UnreadCountCallback) => Unsubscribe`	Subscribe to changes in the number of unread messages

/**
 * Callback function for tracking the state.
 */
type UnreadCountCallback = (count: number) => void;

/**
 * Function for unsubscribing from the event.
 */
type Unsubscribe = () => void;

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

Unsubscribing from the event

onUnreadCountChange() returns an unsubscribe function.

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

unsubscribe();

Important

the callback is invoked when the number of unread messages changes;
the callback is invoked immediately after subscribing with the current value;
the counter is reset to 0 when the chat window is opened;
the callback keeps working until the subscription is cancelled.

onError()

onError() tracks widget errors.

Use onError() to log widget errors or pass them to a monitoring system.

The callback receives an error object:

message: string — the error description;
source: string — the error source.

Method	Signature	Description
`onError()`	`(callback: ErrorCallback) => Unsubscribe`	Subscribe to widget errors

/**
 * Error object
 */
type Error = {
  message: string,
  source: string,
}

/**
 * Callback function for tracking the state.
 */
type ErrorCallback = (error: Error) => void;

/**
 * Function for unsubscribing from the event.
 */
type Unsubscribe = () => void;

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

Unsubscribing from the event

onError() returns an unsubscribe function.

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

unsubscribe();

Important

the callback is invoked on connection and authorization errors;
errors do not stop the widget from working;
the callback keeps working until the subscription is cancelled.

onLoadCallback() `deprecated`

onLoadCallback() lets you run code after the widget has fully loaded.

For example:

update the page interface;
send an event to analytics;
perform additional initialization.

Call onLoadCallback() before run().

Method	Signature	Description
`onLoadCallback:`	`(callback: () => void) => void`	Subscribe to window state changes

<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>

Important

onLoadCallback() must be called before run();
the callback is invoked once when the widget starts,
errors inside the callback may interrupt widget initialization,

Methods

run()

run() launches the widget on the page.

Use run() after the widget script has loaded to display the widget on the site.

Method	Signature	Description
`run:`	`(props: Props) => void`	Launches the widget

/**
* Parameters for launching the widget
*/
type Props = {
  withIcon?: boolean; // true — shows the built-in widget button, false — hides it
}

Launching the widget with the built-in chat button.

<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>

If you need to hide the built-in widget button, pass withIcon: false.

In this case the chat can be opened via vivo_api.open().

vivo_api.run({ withIcon: false });

Important

run() must be called after the widget script has loaded;
before run() is called, Widget API methods are unavailable;
run() is called once after the page has loaded;
calling run() again may create a second widget instance;
after launch, the open(), close(), isOpen() and other methods become available.

open()

open() opens the chat window.

Use open() to open the chat from your own site button.

Method	Signature	Description
`open`	`() => Promise<void>`	Opens the chat window

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

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

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

  })();
</script>

Important

open() must be called after run();
open() works both with withIcon: true and with withIcon: false;
if the window is already open, calling open() again does not create a new chat instance;
the window state can be checked via vivo_api.isOpen().

close()

close() hides the chat window but does not remove the widget from the page.

Use close() when you need to close the chat

Method	Signature	Description
`close:`	`() => void`	Closes the chat window

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

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

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

Important

close() must be called after run();
the method hides the chat window but does not remove the widget from the page;
close() does not reset the session and does not delete the dialog history;
after close() the chat can be opened again via open();
the window state can be checked via vivo_api.isOpen();

isOpen()

isOpen() lets you check whether the chat window is open.

Method	Signature	Description
`isOpen()`	`() => boolean`	Returns `true` if the chat window is open

<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>

Important

isOpen() must be called after run();
isOpen() returns the current window state immediately, without waiting for events;
isOpen() returns:
true — the window is open;
false — the window is closed.

destroy()

destroy() completely removes the widget from the page.

Unlike close(), the method clears the widget state, closes the WebSocket connection and removes the widget’s DOM elements.

Use destroy() before relaunching the widget, when the user logs out of their account, or when switching users.

Method	Signature	Description
`destroy`	`() => void`	Completely removes the widget from the page

vivo_api.destroy();

Important

destroy() completely removes the widget from the page;
the method clears the widget state and closes the WebSocket connection;
after destroy() the Widget API methods become unavailable until the next run() call;
use destroy() before calling run() again;
close() hides the chat window but does not remove the widget from the page.

hasUnreadCount()

hasUnreadCount() returns the current number of unread messages.

Despite its name, the method returns the number of unread messages, not a boolean.

Use hasUnreadCount() when you need to get the current counter value right after the widget has been initialized.

Method	Signature	Description
`hasUnreadCount:`	`() => number`	Returns the number of unread messages

const count = vivo_api.hasUnreadCount();

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

Important

hasUnreadCount() must be called after run();
the method returns the current counter value synchronously;
the counter value is preserved across page reloads;
hasUnreadCount() returns the current counter state;
to update the counter in real time, use onUnreadCountChange();
the counter is reset to 0 after the chat window is opened.

setUserToken()

setUserToken() passes an identifier for the subsequent verification of your customer in VivoChat.

Use setUserToken() when you need to verify a customer, pass information about them to VivoChat, and display the conversation history. See more in the “Customer verification” section.

Method	Signature	Description
`setUserToken`	`(token: string) => void`	Passes the user token to the widget

How it works

setUserToken() stores the user identifier in the widget session.

The token can be any string:

a session token;
a user ID;
any other identifier of the user in your system.

VivoChat does not have access to your database and does not verify the token itself.

const USER_TOKEN = 'USER_TOKEN';

vivo_api.setUserToken(USER_TOKEN)

/* ... */

vivo_api.run()

Important

setUserToken() must be called before run();
the token is not verified on the VivoChat side;
if no token is passed, the widget works as an anonymous chat;
when the user logs out, it is recommended to call destroy() and relaunch the widget;
when switching users, you must call destroy() before calling run() again.

setContactInfo()

setContactInfo() passes the user’s contact details to VivoChat.

Use setContactInfo() when you need to:

show the operator the user’s name, phone or email.

Method	Signature	Description
`setContactInfo:`	`(info: Info) => void`	Passes the user’s contact details

/**
 * User contact details
 */
type Info = {
  name?: string, // User's name
  phone?: string, // User's phone
  email?: string, // User's email
}

How it works

setContactInfo() passes the user’s contact details to VivoChat.

After the data is passed, the operator will see the user’s name, phone and email in the “Contacts” section of the current dialog in VivoChat.

Unlike setUserToken(), the method is not involved in customer verification.

If you need to pass additional information about the user, use the chat_accepted event via webhook. The fields and structure of the transmitted data are entirely defined on your site’s side.

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

/* ... */

vivo_api.run();

Important

setContactInfo() is recommended to be called before run();
all method fields are optional;
setContactInfo() is not used for user verification;
to identify users and restore dialog history, use setUserToken() and client_check_token, described in detail in the “Customer verification” section.

setRegion()

setRegion() specifies the routing channel code for the widget.

Use setRegion() when you need to route conversations:

to different language channels;
to different support teams;
to different conversation categories.

Method	Signature	Description
`setRegion:`	`(region: string) => void`	Specifies the routing code for the widget

vivo_api.setRegion('en')

/*...*/

vivo_api.run()

How it works

setRegion() passes the routing code when the widget is launched. For routing to work, you must configure additional channels in advance in the VivoChat interface. A single shared Widget ID is used for all channels on the site.

If the routing code is not passed or is not found, conversations will go to the main channel. Routing configuration is described in more detail in the “Conversation routing” section.

Important

setRegion() must be called before run();
the routing code must exactly match the code in the VivoChat settings;
to change routing after the widget is launched, use destroy() → setRegion() → run().

onUnmount() `deprecated`

onUnmount() completely removes the widget from the page.

Unlike close();, the method clears the widget state, closes the WebSocket connection and removes the widget’s DOM elements.

Use onUnmount() before relaunching the widget, when the user logs out of their account, or when switching users.

Method	Signature	Description
`onUnmount:`	`() => void`	Completely removes the widget from the page

vivo_api.onUnmount();

Important

onUnmount() completely removes the widget from the page;
the method clears the widget state and closes the WebSocket connection;
after onUnmount() the Widget API methods become unavailable until the next run() call;
use onUnmount() before calling run() again;
close() hides the chat window but does not remove the widget from the page.

Widget API

Callback functions

onWidgetReady()

Important

onOpenStateChange()

Unsubscribing from the event

Important

onUnreadCountChange()

Unsubscribing from the event

Important

onError()

Unsubscribing from the event

Important

onLoadCallback() deprecated

Important

Methods

run()

Hidden widget launch

Important

open()

Important

close()

Important

isOpen()

Important

destroy()

Important

hasUnreadCount()

Important

setUserToken()

How it works

Important

setContactInfo()

How it works

Important

setRegion()

How it works

Important

onUnmount() deprecated

Important

onLoadCallback() `deprecated`

onUnmount() `deprecated`