Convrs Web Chat API

Use the Convrs Web Chat API to dynamically control the chat widget on your website. Configure appearance, manage visibility, set language, and identify users — all through JavaScript.

Settings for the Web Chat widget are typically configured within the Convrs UI, but the API allows you to override or set certain options dynamically at runtime. The widget loads via a CDN-hosted script and should never be saved locally, ensuring you always receive the latest bug fixes, security patches, and features automatically.

Getting Started

The Web Chat widget is loaded by adding a script tag to your page. Configuration is set before the script loads using the ConvrsChat.options object, or dynamically at runtime using the ConvrsChat.Settings() method.

Add the widget script to your HTML page. The script is provided by Convrs and served from the CDN.

Note

The widget script URL is unique to your organization and is generated by Convrs. Do not save the script file locally — always load it from the CDN so you receive automatic updates.

Warning

The widget initializes automatically when the script loads. If you need to set configuration options, they must be defined before the script tag (see below).

Steps:

Copy the script tag provided by Convrs into your page's <head> or before the closing </body> tag.
Ensure the defer attribute and id="convrs-webchat" are present on the script tag.

<script defer id="convrs-webchat"
  src="https://webchat.conv.rs/YOUR_WIDGET_ID.js">
</script>

Configuring with HTML Markup

You can pass settings directly on the script tag using the data-settings attribute.

Steps:

Add a data-settings attribute to the script tag containing a JSON string of settings.

<script defer id="convrs-webchat"
  data-settings='{"background": "#0073cc", "title": "Support Chat"}'
  src="https://webchat.conv.rs/YOUR_WIDGET_ID.js">
</script>

Configuring with JavaScript

Use the ConvrsChat.Settings() method to apply settings dynamically after the widget has loaded.

Note

Settings applied via JavaScript take effect immediately and override any previous values, including those set via data-settings.

Steps:

Call ConvrsChat.Settings() with a settings object after the widget script has loaded.

ConvrsChat.Settings({
  "background": "#0073cc",
  "title": "Support Chat",
  "offset": { "horizontal": 20, "vertical": 30 }
});

Available Settings

The following settings can be passed to ConvrsChat.Settings() or included in the data-settings attribute. These control the widget's appearance and behavior.

Settings Reference

A complete list of all available settings for the Web Chat widget.

Setting	Type	Default	Description
`background`	String (CSS color)	`#42a5f5`	Primary color used for the widget icon, chat header, and accent elements. Accepts any valid CSS color value.
`title`	String	`Web Chat`	The name displayed in the chat window header. Typically set to your company or bot name.
`botavatar`	String (URL)	—	URL to a square image used as the bot's avatar in the chat window. Must be served over HTTPS and be at least 6 characters long.
`offset`	Object	`{ horizontal: 10, vertical: 10 }`	Position of the widget from the corner of the screen, in pixels. See Offset Configuration below.
`direction`	String	`ltr`	Text direction. Set to `"rtl"` for right-to-left languages such as Arabic or Hebrew.
`disabletooltips`	Boolean	`false`	When `true`, hides the tooltip labels on channel icons (Messenger, Telegram, WhatsApp, etc.).
`lang`	String	—	Sets the widget language code. When set via `Settings()`, this calls `SetLang()` internally. See Language Configuration below.

Offset Configuration

Control the widget's position on the page by specifying horizontal and vertical offsets in pixels.

Note

Values can be passed as numbers or strings — they are parsed as integers internally.

Steps:

Pass an offset object with horizontal and/or vertical properties.

ConvrsChat.Settings({
  "offset": { "horizontal": 20, "vertical": 50 }
});

Property	Type	Default	Description
`horizontal`	Number or String	`10`	Distance in pixels from the right edge of the screen (or left edge in RTL mode).
`vertical`	Number or String	`10`	Distance in pixels from the bottom edge of the screen.

Custom Icon

Replace the default widget icon with a custom SVG image. This setting is applied at initialization only and cannot be changed at runtime.

Warning

The icon setting must be set in the initial configuration before the widget loads. It cannot be changed dynamically via ConvrsChat.Settings().

Steps:

Encode your SVG icon as a Base64 data URI.
Include the icon property in your initial widget configuration (inside ConvrsChat.options.settings).

ConvrsChat.options = {
  "settings": {
    "icon": "data:image/svg+xml;base64,PHN2Zy4uLg=="
  },
  ...
};

API Methods

The ConvrsChat object exposes several methods for controlling the widget programmatically. These can be called from your page's JavaScript after the widget script has loaded.

Control whether the chat window is open or closed.

Method	Description
`ConvrsChat.ShowWebChat()`	Opens the chat window. If the widget is already open, this has no additional effect.
`ConvrsChat.HideWebChat()`	Closes the chat window and returns to the floating icon state.
`ConvrsChat.ToggleWebChat()`	Toggles the chat window between open and closed states.

// Open the chat when a button is clicked
document.getElementById('help-btn').addEventListener('click', function() {
  ConvrsChat.ShowWebChat();
});

Channel Visibility

Control the channel selection menu that displays available messaging channels.

Method	Description
`ConvrsChat.ShowChannels()`	Shows the channel selection menu.
`ConvrsChat.HideChannels()`	Hides the channel selection menu.
`ConvrsChat.ToggleChannels()`	Toggles the channel selection menu. If only one channel (Web Chat) is configured, this opens the chat directly instead of showing the menu.

Settings Method

Apply or update widget settings at runtime.

Method	Description
`ConvrsChat.Settings(obj)`	Applies one or more settings from the provided object. See Available Settings for valid properties. Changes take effect immediately.

// Change multiple settings at once
ConvrsChat.Settings({
  "background": "#ff6600",
  "title": "Sales Chat",
  "disabletooltips": true
});

Alert Methods

Display temporary notification messages to the user above the chat widget.

Method	Parameters	Description
`ConvrsChat.showAlert(message, type, duration)`	`message` (String): The text to display. `type` (String, optional): `"info"` (default) or `"error"`. `duration` (Number, optional): Time in milliseconds before the alert auto-hides. Default is `5000` (5 seconds).	Shows a temporary notification above the widget icon. Info alerts display with a blue style, error alerts with red.
`ConvrsChat.alertError(message)`	`message` (String): The error text to display.	Shorthand for `showAlert(message, "error", 5000)`.

// Show an info notification for 3 seconds
ConvrsChat.showAlert("Your message has been sent!", "info", 3000);

// Show an error notification
ConvrsChat.showAlert("Connection lost. Retrying...", "error");

Language Configuration

The Web Chat widget supports multiple languages and can detect the user's language automatically or be set explicitly via the API.

Language Detection

By default, the widget reads the language from your page's HTML lang attribute.

Note

Once a user engages with the chatbot (sends a message), the language is fixed for that session. Changing the HTML lang attribute after engagement will not restart the conversation in a new language.

Steps:

Set the lang attribute on your <html> tag to the appropriate language code.

<html lang="es">

The widget checks this attribute when it initializes. If your page dynamically changes the lang attribute (for example, in a single-page app), the widget detects the change and updates accordingly.

SetLang Method

Set the widget language explicitly, overriding automatic detection.

Warning

Using SetLang with force = true clears the user's message history and restarts the conversation from the beginning. Use this only when the user explicitly requests a language change.

Method	Parameters	Description
`ConvrsChat.SetLang(lang)`	`lang` (String): Language code (e.g., `"en"`, `"es"`, `"fr"`).	Sets the widget language. If the user has not yet engaged, the conversation restarts in the new language. Disables automatic language detection from the HTML tag.
`ConvrsChat.SetLang(lang, true)`	`lang` (String): Language code. `force` (Boolean): `true` to force restart.	Forces the conversation to restart in the new language, even if the user has already engaged. Clears message history and reconnects.

// Set language to Spanish
ConvrsChat.SetLang("es");

// Force restart in French (clears history)
ConvrsChat.SetLang("fr", true);

Language-Specific Channels

Configure different messaging channels for different languages using the langchannel option.

Note

If no langchannel entry matches the current language, the default channel array is used.

Steps:

Define a langchannel object in your widget options, with language codes as keys and channel arrays as values.
When the widget detects or is set to a language that has an entry in langchannel, it switches to those channels automatically.

ConvrsChat.options = {
  "channel": [
    // Default channels (used when no language match)
    {"t": "w", "token": "DEFAULT-TOKEN"}
  ],
  "langchannel": {
    "es": [
      {"t": "wa", "u": "https://wa.me/34..."},
      {"t": "w", "token": "SPANISH-TOKEN"}
    ],
    "fr": [
      {"t": "w", "token": "FRENCH-TOKEN"}
    ]
  },
  "lang": {"rule": "html"}
};

Proactive Messaging (ReachOut)

The ReachOut feature displays a proactive popup message near the widget icon after a configurable delay, encouraging visitors to start a conversation. This is configured in the initial widget options.

Configuring ReachOut

Set up a proactive message that appears automatically after a delay.

Note

The popup only appears once per visitor. After the user closes it or interacts with the widget, it will not appear again on subsequent page loads. The ConvrsChat.ReachOut() method can be called to manually trigger the popup.

Steps:

Include a proact object in your widget options with the message, delay, and agent information.

ConvrsChat.options = {
  "proact": {
    "v": 1.1,
    "seconds": 5,
    "msg": {
      "en": "Hi there! Need help? Chat with us!",
      "es": "¡Hola! ¿Necesitas ayuda?"
    },
    "agent": {
      "en": "Support Team",
      "es": "Equipo de Soporte"
    },
    "avatar": "https://webchat.conv.rs/YOUR_AVATAR_ID"
  },
  ...
};

Property	Type	Description
`v`	Number	Version identifier. Use `1.1`.
`seconds`	Number	Delay in seconds before the popup appears. Set to empty string to disable.
`msg`	Object	Message text keyed by language code. The widget selects the message matching the current language.
`agent`	Object	Agent/team name keyed by language code, displayed above the message.
`avatar`	String (URL)	Avatar image displayed alongside the proactive message.

Embedded Mode

The widget can be embedded directly into a page layout rather than appearing as a floating icon. This is useful for dedicated "Contact Us" pages where you want the chat to be part of the page content.

Setting Up Embedded Mode

Embed the channel list directly into your page layout.

Note

In embedded mode, the floating widget icon is still displayed. The embedded container provides an additional way for users to access channels directly within the page.

Steps:

Add a <ul id="convrs-embedded" class="convrs-chat"></ul> element where you want the channel list to appear.
Optionally add an element with id="convrs-embedded-intro" for an introduction message.
Optionally add a <select id="convrs-embedded-lang"> for a language selector.
Load the widget script as normal — it will detect the embedded container and populate it.

<div id="convrs-embedded-main">
  <p id="convrs-embedded-intro">Choose your channel:</p>
  <select id="convrs-embedded-lang"></select>
  <ul id="convrs-embedded" class="convrs-chat"></ul>
</div>

Script Loading Patterns

The widget supports multiple ways of loading the script, including via tag managers like Google Tag Manager (GTM).

Standard Script Tag

The simplest and recommended approach — add the script tag directly to your HTML.

Steps:

Place the ConvrsChat.options configuration in a <script> block before the widget script tag.
Add the widget script tag with the defer attribute.

<script>
var ConvrsChat = {};
ConvrsChat.options = {
  "url": "wss://wcl.conv.rs/webchat",
  "channel": [
    {"t": "w", "token": "YOUR-TOKEN-HERE"}
  ],
  "settings": {
    "background": "#42a5f5",
    "title": "Support Chat"
  }
};
</script>
<script defer id="convrs-webchat"
  src="https://webchat.conv.rs/YOUR_WIDGET_ID.js">
</script>

Dynamic Script Injection

Load the widget script dynamically using JavaScript, for example via a tag manager.

Note

The widget handles late loading gracefully and will initialize properly even when injected after the page has fully loaded.

Steps:

Define ConvrsChat.options before injecting the script.
Create a <script> element and set its src to the widget URL.
Append it to the document.

var script = document.createElement('script');
script.src = 'https://webchat.conv.rs/YOUR_WIDGET_ID.js';
script.async = true;
document.head.appendChild(script);

Testing and Debugging

Tools and tips for testing your Web Chat widget integration during development.

Resetting Session Data

Clear all stored widget data to test a fresh user experience.

Steps:

Click into the chat text entry field so it has focus.
Hold Ctrl and press Z.

Result: The widget closes the WebSocket connection, deletes all cookies and localStorage entries for the widget, and clears the message history. The page will need to be refreshed to reinitialize the widget.

Tips

Use this during development to test the first-time user experience repeatedly.
This resets language preferences, message history, and all saved state.

Clearing Cached Scripts

After Convrs deploys widget updates, you may need to clear your browser cache to see the changes.

Note

Widget updates are deployed via the CDN and may take a few minutes to propagate. A hard refresh ensures you load the latest version.

Steps:

Press Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac) to perform a hard refresh.

Complete Example

A full working example showing widget configuration with multiple channels, language support, user identification, and proactive messaging.

Full Integration Example

A complete example page with all major features configured.

Steps:

Copy the following HTML into your page, replacing the placeholder values with your actual configuration.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My Website</title>

  <script>
  // Widget configuration
  var ConvrsChat = {};
  ConvrsChat.options = {
    "url": "wss://wcl.conv.rs/webchat",
    "width": 56,
    "height": 56,
    "allowimages": 1,
    "allowdocuments": 1,
    "allowaudio": 1,
    "allowdatalocal": 1,
    "lang": {"rule": "html"},
    "channel": [
      {"t": "wa", "u": "https://wa.me/44..."},
      {"t": "m", "u": "https://m.me/..."},
      {"t": "t", "u": "https://t.me/..."},
      {"t": "w", "token": "YOUR-WEBCHAT-TOKEN"}
    ],
    "langchannel": {
      "es": [{"t": "w", "token": "SPANISH-TOKEN"}],
      "fr": [{"t": "w", "token": "FRENCH-TOKEN"}]
    },
    "settings": {
      "background": "#0073cc",
      "title": "Support Chat",
      "botavatar": "https://webchat.conv.rs/YOUR_AVATAR",
      "offset": {"horizontal": "10", "vertical": "10"}
    },
    "proact": {
      "v": 1.1,
      "seconds": 5,
      "msg": {"en": "Need help? Chat with us!"},
      "agent": {"en": "Support Team"},
      "avatar": "https://webchat.conv.rs/YOUR_AVATAR"
    },
    "contact": {
      "dd": {"en": "English", "es": "Español"},
      "intro": {"en": "", "es": ""}
    }
  };
  </script>
  <script defer id="convrs-webchat"
    src="https://webchat.conv.rs/YOUR_WIDGET_ID.js">
  </script>
</head>
<body>
  <!-- Your page content -->
</body>
</html>

Convrs Web Chat API

Getting Started

Loading the Widget

Configuring with HTML Markup

Configuring with JavaScript

Available Settings

Settings Reference

Offset Configuration

Custom Icon

API Methods

Widget Visibility

Channel Visibility

Settings Method

Alert Methods

Language Configuration

Language Detection

SetLang Method

Language-Specific Channels

Proactive Messaging (ReachOut)

Configuring ReachOut

Embedded Mode

Setting Up Embedded Mode

Script Loading Patterns

Standard Script Tag

Dynamic Script Injection

Testing and Debugging

Resetting Session Data

Clearing Cached Scripts

Complete Example

Full Integration Example

Getting Started

Loading the Widget

Configuring with HTML Markup

Configuring with JavaScript

Available Settings

Settings Reference

Offset Configuration

Custom Icon

API Methods

Widget Visibility

Channel Visibility

Settings Method

Alert Methods

Language Configuration

Language Detection

SetLang Method

Language-Specific Channels

Proactive Messaging (ReachOut)

Configuring ReachOut

Embedded Mode

Setting Up Embedded Mode

Script Loading Patterns

Standard Script Tag

Dynamic Script Injection

Testing and Debugging

Resetting Session Data

Clearing Cached Scripts

Complete Example

Full Integration Example

Related Topics