Copilot JavaScript API and events | Estatebud Help Center

Your website can control the Copilot chat widget programmatically using Copilot's JavaScript API, for example to open the chat from your own button, show a greeting on certain pages, or send chat activity to your analytics. This article describes the commands and events that make this possible.

The widget must already be installed. See Installing and configuring the Copilot widget.

Commands

When embed.js has loaded, it adds a global function window.Copilot(command, argument) that lets your website control the chat.

Command	Argument	Returns	Description
`open`	none	nothing	Opens the chat window.
`close`	none	nothing	Closes the chat window.
`toggle`	none	nothing	Opens the chat if it is closed, closes it if it is open.
`inviteMessage`	`{ text, delay }`	nothing	Shows an invite message: a greeting bubble next to the chat button. `delay` is in milliseconds. It is only shown when the visitor has no open conversation and the chat is closed.
`isReady`	none	`true` / `false`	Whether the widget has finished loading.
`isOpen`	none	`true` / `false`	Whether the chat window is open.
`onReady`	function	nothing	Calls your function when the widget has loaded.
`onOpen`	function	nothing	Calls your function every time the chat opens.
`onClose`	function	nothing	Calls your function every time the chat closes.
`onMessage`	function	nothing	Calls your function for every new message from the assistant.

open, close, toggle and inviteMessage do nothing until the widget is ready, so call them from onReady or after checking isReady.

Examples

Open the chat from your own button:

<button onclick="window.Copilot && window.Copilot('open')">Chat with us</button>

Show an invite on property pages after 10 seconds:

window.Copilot('onReady', function () {
  if (location.pathname.indexOf('/property') === 0) {
    window.Copilot('inviteMessage', {
      text: 'Questions about this property? Ask me anything 😊',
      delay: 10000
    });
  }
});

Open the chat when the visitor clicks any link pointing to #chat:

document.addEventListener('click', function (event) {
  var link = event.target.closest('a[href="#chat"]');
  if (!link || !window.Copilot) return;
  event.preventDefault();
  window.Copilot('open');
});

Events

The widget sends four events. You can listen to them in two ways:

With the API: window.Copilot('onReady', fn), onOpen, onClose and onMessage. Your function receives the event details as its argument.
The details are in event.detail. This also works in code that runs before embed.js has loaded.

Event	When	Details
`ready`	The widget has loaded and the API commands work.	`{ token }`
`open`	The chat window opens, by the visitor or through the API.	`{}`
`close`	The chat window closes.	`{}`
`message`	A new message from the assistant arrives.	`{ text, messageId, timestamp }`

The browser event names have no separator between Estatebud_Copilot and the event name: it is Estatebud_Copilotopen, not Estatebud_Copilot_open.

Details of the message event

Field	Type	Description
`text`	string	The message text (may contain Markdown, e.g. `bold` and lists).
`messageId`	string	Unique id of the message.
`timestamp`	number	Time the message was sent, unix format.

Messages shown again when the visitor reloads a page do not fire message; only new ones do.

Example: send events to Google Analytics

window.Copilot('onOpen', function () {
  gtag('event', 'copilot_open');
});
window.Copilot('onClose', function () {
  gtag('event', 'copilot_close');
});
window.Copilot('onMessage', function (data) {
  gtag('event', 'copilot_reply', { message_id: data.messageId });
});

The same works with any other analytics or tag manager, e.g. by pushing to dataLayer:

window.Copilot('onOpen', function () {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ event: 'copilot_open' });
});

Troubleshooting

Problem	Solution
`window.Copilot` is undefined.	`embed.js` has not run yet.
`Copilot('open')` does nothing.	The widget is not ready yet. Call it inside `Copilot('onReady')`.
`message` does not fire for old messages.	That is expected: it only fires for new assistant messages, not for messages shown again after a page reload.
`Copilot('inviteMessage', …)` shows nothing.	The invite is only shown when the visitor has no open conversation and the chat is closed. Check that `text` is not empty and that `delay` is in milliseconds.