Skip to content
chatyol

Docs / Widget

JavaScript API

Open, close and toggle the chat, identify visitors, listen for messages and unread counts, and queue calls before widget.js loads.

window.Chatyol

Once widget.js has loaded, it creates one global, window.Chatyol. Use optional chaining (window.Chatyol?.open()) when you're not sure it has loaded yet, or add the queue stub below.

Call What it does
Chatyol.open() Opens the chat panel
Chatyol.close() Closes it
Chatyol.toggle() Opens it if closed, closes it if open
Chatyol.identify({ name, email, phone, extId, sig }) Tells Chatyol who the visitor is. See Identify signed-in visitors
Chatyol.on(event, callback) Listens for an event. Returns a function that stops listening
Chatyol.off(event, callback) Stops listening
Chatyol.destroy() Removes the widget, closes its connection and every listener
Chatyol.version The API version, "1"

Events

Event Callback gets When
ready nothing The widget has loaded its settings
open nothing The panel opened
close nothing The panel closed
message { id, body, createdAt, from, attachments } A new message from the team arrived while the panel was closed or the tab hidden. from is agent or bot; each attachment has name and mime
unread a number Unread messages from the team; 0 once the visitor reads them

A callback that throws never breaks the widget or the other callbacks.

Examples

Open the chat from your own button:

html
<button type="button" onclick="window.Chatyol?.open()">Chat with us</button>

Show the unread count in your own header:

js
const stop = window.Chatyol.on('unread', (count) => {
  document.querySelector('#chat-count').textContent = count || '';
});
// Later: stop();

Call it before widget.js loads

Put this above the snippet. Calls like Chatyol.open() then queue up and run, in order, once the widget loads.

html
<script>
  window.Chatyol = window.Chatyol || { q: [] };
  ['open', 'close', 'toggle', 'identify', 'on'].forEach(function (m) {
    Chatyol[m] = Chatyol[m] || function () { Chatyol.q.push([m].concat([].slice.call(arguments))); };
  });
</script>
<script src="https://cdn.chatyol.com/widget.js" data-key="pk_your_key" async></script>

Single-page apps

Load the script once in your HTML shell, never in a component. Route changes keep the chat as it is. If you need to remove it, for example on sign-out pages, call Chatyol.destroy().

Something unclear or out of date? Email support@chatyol.com.