Web Widget

The Convrs Web Widget is an omnichannel chat component that you embed on your website to provide instant, real-time communication between your visitors and your team. Appearing as a customisable floating button in the corner of your web pages, it expands into a full messaging interface where customers can start a live chat conversation, connect with AI-powered chatbots, or reach you through their preferred messaging channel—all from a single, unified entry point.

Unlike basic live chat plugins that only support website messaging, the Convrs Web Widget acts as a true omnichannel widget, bringing together webchat, WhatsApp, Facebook Messenger, Telegram, LINE, Viber, and Instagram into one place. Visitors choose the channel that suits them best, and every conversation flows into your team's unified inbox for seamless agent handling.

Key advantages of the Convrs Web Widget include:

  • Omnichannel engagement — Consolidate all your messaging channels behind a single widget so customers can reach you however they prefer.
  • Chatbot and live agent hybrid — Route conversations through an AI chatbot first and hand off to a human agent when needed, reducing response times and agent workload.
  • Proactive messaging — Automatically invite visitors to chat after a configurable delay, increasing engagement and conversion rates.
  • Multi-language support — Serve international audiences by mapping different language codes to different channels and chatbot flows.
  • Rich media — Let customers send images, documents, and voice messages directly in the chat window.
  • Fully brandable — Match your brand colours, choose from a library of launcher icons, and set custom bot avatars.
  • Simple deployment — A single script tag is all you need to add the widget to any page on your website.

Creating and Managing Web Widgets

Web Widgets are created and managed from the Web Widget page in Convrs. Each widget produces a unique script tag that you add to your website. You can create multiple widgets for different websites, brands, or departments.

Create a New Web Widget

Create a new web widget and configure its channels, appearance, and behaviour.

Steps:

  1. Navigate to the Web Widget page.
  2. Click the Create New Web Widget button.
  3. Fill in the widget settings described in the sections below.
  4. Click the Create New Web Widget button at the bottom of the form.

Result: A new web widget is created and a script tag is generated for embedding on your website.

Edit a Web Widget

Modify the configuration of an existing web widget.

Steps:

  1. Navigate to the Web Widget page. Each existing widget is shown as a card displaying its name, active channels, and embed code.
  2. Click the Edit button on the widget you wish to modify.
  3. Update the settings as needed.
  4. Click the Update Web Widget button to save your changes.

Delete a Web Widget

Permanently remove a web widget.

Warning
Deleting a web widget is permanent and cannot be undone. The widget will immediately stop working on any pages where the script tag is installed.

Steps:

  1. Navigate to the Web Widget page.
  2. Click the Delete button on the widget you wish to remove.
  3. Confirm the deletion in the dialog that appears.

Deploy the Widget on Your Website

Add the widget to your website using the generated script tag.

Steps:

  1. On the Web Widget page, locate the script tag shown for your widget.
  2. Click the Copy icon next to the script tag to copy it to your clipboard.
  3. Paste the script tag into the HTML of every page where you want the widget to appear. Placing it just before the closing </body> tag is recommended.
Tips
  • If you use a CMS or tag manager, you can add the script globally so it appears on all pages automatically.
  • The widget also generates a standalone Contact Page link that can be used in email signatures or shared directly.

General Settings

These settings control the basic identity and behaviour of the web widget.

Widget Name and Title

Configure the internal name and the visitor-facing title of the widget.

FieldDescription
Widget Name An internal label used to identify this widget within Convrs. Not visible to website visitors.
Web Widget Title The title displayed in the header of the chat window when a visitor opens the widget. For example, "Support Chat" or "Chat with us". Defaults to "Web Chat" if left blank.

Website Domain Name

Specify the domain where the widget will be deployed.

FieldDescription
Website Domain Name The root domain of the website where this widget will be installed. If the widget needs to run across multiple subdomains (e.g. www.example.com and app.example.com), enter the root domain only (e.g. example.com).

Media and Data Settings

Control what types of content visitors are allowed to send through the widget, and whether conversation data is persisted on the visitor's device.

File and Media Uploads

Enable or disable the ability for visitors to upload files and media during a chat.

Note
These upload options only apply during live webchat sessions. They do not affect external channels such as WhatsApp or Telegram, which have their own media capabilities.
Automatic Malware Scanning

All files uploaded through the widget are automatically subjected to real-time malware analysis before they are delivered to an agent. Each file is scanned for viruses, trojans, ransomware, and other known threats. Files that fail the security scan are quarantined and rejected, ensuring that malicious payloads never reach your agents or internal systems. A progress indicator is shown to the visitor while the scan is in progress.

SettingDescription
Allow User to Upload Images When enabled, visitors can send image files (e.g. screenshots, photos) during a conversation. On mobile devices, this also allows taking photos with the camera.
Allow User to Upload Documents When enabled, visitors can attach document files (e.g. PDFs, Word documents) to their messages.
Allow User to Upload Voice Messages When enabled, visitors can record and send audio voice messages using their device's microphone.

Local Data Storage

Control whether conversation data is stored on the visitor's device.

Warning
Enabling local storage provides a better user experience, but stored conversation data can be accessed by anyone who uses the same browser on that device. Disable this setting if conversations may contain sensitive information.
SettingDescription
Allow the chat to be stored on users machine When enabled, conversation history is saved in the visitor's browser local storage. This means returning visitors can see their previous messages and continue where they left off without restarting the chatbot flow. When disabled, every visit starts a fresh conversation.

Multi-Language Support

The web widget can detect the language of the page it is embedded on and automatically switch channels, chatbot flows, proactive messages, and contact page text to match that language.

Enable Multiple Languages

Set up the widget to serve visitors in different languages based on the page language.

Steps:

  1. Enable the Support Multiple Languages toggle.
  2. The language management panel appears. The default language (en) is always present and cannot be removed.
  3. To add a language, enter the language code (e.g. fr, es, zh) in the text field and click Add Code.
  4. Select a language code from the Language Code dropdown to configure its channels, proactive message, and contact page text.
  5. Configure the channel URLs, chatbot, proactive message, and contact page fields for the selected language. Each language can have entirely different channels and settings.
  6. To remove a language, enter its code in the text field and click Delete Code.
Tips
  • Language detection reads the lang attribute on the page's <html> tag. Ensure your website sets this attribute correctly (e.g. <html lang="fr">).
  • If no matching language code is found, the widget falls back to the Default (en) configuration.
  • Fields that support per-language values are marked with a language badge showing the currently selected language code.

Channel Configuration

Each web widget can present multiple messaging channels to your visitors. When a visitor opens the widget, they see icons for every configured channel and can choose how they want to communicate. At least one channel should be configured for the widget to be useful.

When multi-language support is enabled, each language code can have its own set of channel URLs and chatbot assignments, allowing you to route visitors to language-specific bots and channels.

Configure Channels

Set up the messaging channels that appear in the widget.

Note
Leave a channel field empty or set to None to exclude that channel from the widget. Only channels with a value configured will appear as icons in the widget.
ChannelDescription
Web Chat Select a chatbot from the dropdown to enable the built-in webchat channel. The webchat opens directly inside the widget window, providing a native messaging experience without leaving your site. Select None to disable webchat.
Telegram Bot Enter the URL of your Telegram bot (e.g. https://t.me/yourbotname). Clicking the Telegram icon in the widget opens this link, directing the visitor to your bot on Telegram.
Messenger Bot Enter the URL of your Facebook Messenger page (e.g. https://m.me/yourpagename). Clicking the Messenger icon opens a conversation with your Facebook page.
WhatsApp Bot Enter a WhatsApp click-to-chat URL (e.g. https://wa.me/1234567890). Clicking the WhatsApp icon opens a chat with the specified phone number on WhatsApp.
Line Bot Enter the URL of your LINE official account. Clicking the LINE icon directs the visitor to chat with your account on the LINE app.
Viber Bot Enter the URI of your Viber public account. Clicking the Viber icon opens a conversation with your Viber bot.
QQ Web Link Enter the URL or identifier for your QQ chat. Clicking the QQ icon directs the visitor to your QQ contact page.
Instagram Bot Select an Instagram account from the dropdown. Clicking the Instagram icon in the widget opens a direct message conversation with the selected account.

Appearance Settings

Customise the visual appearance of the widget to match your website's branding.

Custom Bot Avatar

Set a custom avatar image that appears next to bot messages in the webchat.

Steps:

  1. Drag and drop an image file onto the Custom Bot Avatar field.
  2. A circular preview of the avatar appears beside the field.
Tips
  • Square images work best as the avatar is displayed in a circle.
  • If no custom avatar is set, the default Convrs avatar is used.

Webchat Main Icon

Choose the icon displayed on the floating launcher button.

Note
The launcher icon is displayed using the widget's background colour. Change the background colour to see how the icon will look on your site.

Steps:

  1. Click the icon dropdown to see the library of available icons.
  2. Click an icon to select it. The preview updates immediately.

Widget and Background Colour

Set the primary colour used for the widget launcher button, header bar, and accent elements.

Steps:

  1. Click the Widget and Background Color field to open the colour picker.
  2. Select a colour using the hue slider and colour area, or type a hex value directly (e.g. #42a5f5).
Tips
  • Choose a colour that contrasts well with your website background so the launcher button is clearly visible.
  • The default colour is #42a5f5 (a medium blue).

Widget Position Offset

Adjust where the widget launcher button is positioned on the page.

FieldDescription
Pixel Offset Horizontal The number of pixels from the right edge of the page (or left edge for RTL languages). Increase this value to move the widget further from the edge. Default is 10.
Pixel Offset Vertical The number of pixels from the bottom edge of the page. Increase this value to move the widget higher up the page. Default is 10.
Tips
  • Adjust the offsets to avoid overlapping with other fixed-position elements on your website such as cookie banners or scroll-to-top buttons.

Proactive Reach Out

Proactive messaging allows the widget to automatically display a chat invitation to new visitors after they have been on the page for a specified number of seconds. This is a proven technique for increasing engagement—visitors who receive a proactive chat invitation are significantly more likely to start a conversation than those who do not.

Configure Proactive Messaging

Set up an automated message that invites visitors to chat.

Steps:

  1. Enable the Proactive reachout for new visitors toggle.
  2. Fill in the fields described below.
FieldDescription
Agent Name The name displayed as the sender of the proactive message. For example, "Support Team" or "Sales Assistant". This field supports per-language values when multi-language is enabled.
Seconds to wait The number of seconds after the page loads before the proactive message appears. A value between 5 and 30 seconds is typical. Too short may feel intrusive; too long may miss visitors who leave quickly.
Message To Display The text of the proactive message. Keep it short, friendly, and action-oriented. For example, "Hi! Need help finding what you're looking for?" This field supports per-language values when multi-language is enabled.
Avatar Image An optional avatar image displayed alongside the proactive message. Drag and drop an image onto the field to set it. Using a photo of a real person or a friendly character can make the message feel more personal.
Tips
  • Test different messages and timing to find what works best for your audience.
  • The proactive message only appears once per visit and only for new visitors who have not yet opened the widget.

Contact Page

In addition to the embeddable widget, Convrs generates a standalone Contact Page URL for each web widget. This page displays your configured messaging channels as clickable icons, allowing users to choose their preferred channel to contact you. The Contact Page link is ideal for use in email signatures, social media bios, QR codes, or anywhere a full widget embed is not practical.

Configure the Contact Page

Customise the text that appears on the standalone Contact Page.

FieldDescription
The description for this Language code A short label for the language selector on the Contact Page. When multi-language is enabled, each language code has its own label (e.g. "English", "Français"). This helps visitors identify and select their preferred language.
An Optional Introduction Introductory text displayed at the top of the Contact Page. Use this to greet visitors or provide instructions, for example "Contact us through your preferred messaging channel". This field supports per-language values when multi-language is enabled.
Tips
  • The Contact Page link is shown on the widget card on the Web Widget management page. Click the copy icon to copy it to your clipboard.
  • The Contact Page automatically displays all channels configured for the widget, including the webchat.

Advanced Widget Features

The deployed web widget includes several advanced features that are automatically available to visitors without additional configuration.

RTL Language Support

The widget automatically detects right-to-left languages.

Note
RTL detection is automatic. Arabic, Hebrew, and Persian pages are supported out of the box when the HTML direction attribute is set.

Steps:

  1. Set the dir="rtl" attribute on your page's <html> tag.
  2. The widget automatically mirrors its layout, placing the launcher on the left side and aligning text right-to-left.

Responsive and Mobile Behaviour

The widget adapts to mobile devices automatically.

Steps:

  1. On mobile devices, the chat window expands to fill the entire screen for the best typing and reading experience.
  2. The widget handles viewport changes, keyboard appearance, and app backgrounding gracefully.
  3. Reconnection is optimised for mobile networks, with shorter timeouts to recover quickly from signal loss.

Style Isolation

The widget uses Shadow DOM to prevent style conflicts with your website.

Note
No special configuration is needed. Style isolation is handled automatically.

Steps:

  1. The widget's CSS is fully encapsulated inside a Shadow DOM container.
  2. Your website's styles will not affect the widget, and the widget's styles will not leak into your page.

JavaScript API

Control the widget programmatically from your website's JavaScript.

Note
For full API documentation see Convrs Web Chat API. To pass verified user identity to the widget using JWT tokens, see Secure User Identity for Web Chat (JWT).
MethodDescription
ConvrsChat.ShowWebChat() Opens the chat window programmatically.
ConvrsChat.HideWebChat() Closes the chat window.
ConvrsChat.ToggleWebChat() Toggles the chat window open or closed.
ConvrsChat.ShowChannels() Shows the channel selection icons.
ConvrsChat.HideChannels() Hides the channel selection icons.
ConvrsChat.ToggleChannels() Toggles the channel icons visible or hidden.
ConvrsChat.SetLang(code) Switches the widget to the specified language code (e.g. "fr"). Only effective when multi-language is enabled.
ConvrsChat.UserMessage(text) Sends a message on behalf of the visitor. Useful for triggering specific chatbot flows from button clicks on your page.
ConvrsChat.Settings(obj) Dynamically updates widget settings such as title, background, offset, direction, and botavatar.
SMS WhatsApp Business Platform
In this article