Widget Installation

The widget is loaded with a single JavaScript file. You can find the installation code in the Chat dashboard under widget settings.

What it does

The widget adds Chat to your website. Visitors can start conversations, continue previous dialogs, upload files, read knowledge articles, create public tickets, see broadcasts, submit lead details, and rate answers when those features are enabled for the workspace.

When to use it

Install the widget on any page where visitors should be able to contact your team or find self-service help. If your website has logged-in users, pass their user data to keep conversations attached to the same contact record.

How it works

The script code identifies the workspace. The widget loads settings from Chat, connects to realtime presence, and uses the widget API to create contacts, conversations, messages, files, tickets, ratings, and knowledge views. Optional user verification protects logged-in customer conversations with a server-generated HMAC token.

Where to configure it

Open Settings -> Widget in the Chat dashboard. Related settings live in Knowledge, Tickets, Broadcasts, Settings -> Rating, Settings -> Business hours, and Settings -> Channels.

Related modules

Widget installation works with Conversations, Contacts, Online Visitors, Knowledge Base, Tickets, Broadcasts, Ratings, Lead Forms, Files, and Realtime.

Before you start: create a workspace API token

If your integration also calls the Public API from your server, create a workspace access token first:

1. Open the Chat dashboard.
2. Switch to the workspace where the widget will be installed.
3. Go to Settings → Development → Access tokens.
4. Enter a token name, click Create, and copy the token shown on the screen.

Only workspace owners and admins can create access tokens. The full token is shown only once, so store it securely on your server and do not expose it in browser JavaScript.

Use the token in server-side API requests as a Bearer token:

Authorization: Bearer wk_...

1. Copy the installation code

Open the widget settings in your dashboard and copy the ready-to-use code snippet. It looks like this:

<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

a3f2b1c9 is the public code of your widget. Each account has its own value.

2. Add the code to your site

Add the script before the closing </body> tag on every page where the chat should appear:

<!-- Chat widget -->
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

After the script loads, the chat button will appear on the page.

3. Check the widget

Open your site in a browser and make sure the chat button appears in the lower corner of the page. Click it and send a test message.

If realtime temporarily disconnects, the widget shows a reconnecting status inside the chat window and keeps retrying. Chat sessions are created through the widget HTTP API, so a websocket-only outage does not by itself prevent the first conversation from being created. If the widget cannot create a session or cannot verify a configured site user, it shows an inline error or guest-mode warning in the widget.

Additional Setup

If you need to change the language, button position, or use your own element to open the chat, add settings before the script:

<script>
  window.EvercomWidget = {
    locale: 'en',
    position: 'bottom-right',
    button_selector: '#open-chat'
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

Available options:

Option	Value	Description
locale	en, ru, zh	Widget interface language.
position	bottom-right, bottom-left	Default button position.
button_selector	CSS selector	Your own element that opens the chat. The default button will be hidden.
user	object	Current site user data.
user_token	string	User token, if user verification is enabled for your account.

Example with user data:

<script>
  window.EvercomWidget = {
    user: {
      id: '12345',
      email: 'client@example.com',
      name: 'Anna'
    },
    user_token: 'USER_TOKEN'
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

Button Position

By default, the button appears in the lower-right corner. To move it to the left, pass position:

<script>
  window.EvercomWidget = {
    position: 'bottom-left'
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

Custom Open Button

If you already have a button or menu item for chat, pass its CSS selector in button_selector. The built-in widget button will be hidden, and the selected element will open the chat.

<button id="my-chat-button">Message us</button>

<script>
  window.EvercomWidget = {
    button_selector: '#my-chat-button'
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

User Identification

If a visitor is already signed in on your site, you can pass their data to the widget. Chat will automatically populate the contact.

<script>
  window.EvercomWidget = {
    user: {
      id: 'user-123',
      email: 'user@example.com',
      name: 'John Doe'
    }
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

id must be your internal user ID. Do not use a random value if you want the same user to return to the same conversation.

User Verification

To protect conversations, you can pass user_token. Generate this token only on your server by calculating an HMAC-SHA256 of user.id with the secret key from widget settings.

Never send the secret key to the browser or store it in client-side JavaScript.

Generate the token on your server

Node.js:

const crypto = require('crypto')

const token = crypto
  .createHmac('sha256', SECRET)
  .update(userId)
  .digest('hex')

Python:

import hmac
import hashlib

token = hmac.new(
    SECRET.encode(),
    user_id.encode(),
    hashlib.sha256
).hexdigest()

PHP:

$token = hash_hmac('sha256', $userId, $SECRET);

Pass the token to the widget

<script>
  window.EvercomWidget = {
    user_token: 'TOKEN_FROM_YOUR_SERVER',
    user: {
      id: 'user-123',
      email: 'user@example.com',
      name: 'John Doe'
    }
  }
</script>
<script src="https://widget.evercom.app/a3f2b1c9.js" async></script>

The user.id value used to generate the HMAC must match the user.id passed to the widget.