Skip to main content

JS API

After the widget loads, its methods are available on window.EvercomWidget.

What it does​

The JavaScript API lets your website control the widget from custom UI and pass configuration before the widget script loads.

When to use it​

Use the JS API when you want to open Chat from your own button, identify signed-in users, change the language or position, disable broadcasts on selected pages, or run code after the widget is ready.

How it works​

Define window.EvercomWidget before loading the widget script when you need custom configuration. With the short install script only, the widget creates the object during bootstrap, then adds runtime methods such as open(), close(), and toggle() to it.

Where to configure it​

Add the configuration object directly on your website before the widget script tag. Workspace-level options are configured in Settings -> Widget.

The JS API works with Widget Installation, Contacts, Conversations, Broadcasts, Lead Forms, User Verification, and Realtime.

onReady​

Use onReady when you need to call a method as soon as the widget has loaded.

<script>
  window.EvercomWidget = {
    onReady: function () {
      window.EvercomWidget.open()
    }
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

Methods​

MethodDescription
open()Opens the chat window.
close()Closes the chat window.
toggle()Toggles the chat window.

Conversation history​

When the dialogues list is loaded, the widget API uses the standard include=messages expansion to include a small first page of messages with each conversation. Opening a dialogue can render that warmed history immediately while the full message snapshot refreshes in the background.

Open the chat after 10 seconds​

<script>
  window.EvercomWidget = {
    onReady: function () {
      setTimeout(function () {
        window.EvercomWidget.open()
      }, 10000)
    }
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

Control the widget from your own UI​

<button onclick="window.EvercomWidget.open()">Open chat</button>
<button onclick="window.EvercomWidget.close()">Close chat</button>
<button onclick="window.EvercomWidget.toggle()">Toggle chat</button>

TypeScript​

type EvercomWidget = {
  locale?: 'en' | 'ru' | 'zh'
  position?: 'bottom-right' | 'bottom-left'
  button_selector?: string
  user?: {
    id: string
    email?: string
    name?: string
  }
  user_token?: string
  onReady?: () => void
  open?: () => void
  close?: () => void
  toggle?: () => void
}