Website chat widget

The website chat widget puts a chat button on your website. Visitors' messages arrive in the HyoNova Support inbox, and your agents' replies appear in the chat. It works without any outside service: nothing needs to be set up by HyoNova first.

A widget gives you three ways to offer chat:

What visitors see#

The chat has up to four views. You choose which ones a widget offers in its Experience step.

• Home, Conversations and Help are tabs at the bottom of the chat. They are part of the home screen: with Home screen off, the chat opens straight on the conversation and the other two views are not offered.
• A visitor who already has a running conversation lands in it when they open the chat; everyone else starts on Home.
• An earlier conversation opens for reading. A closed one offers Start a new conversation.
• A visitor only ever sees their own conversations, from the same browser. See Privacy.

Who answers#

The top of the chat and a status line always say who handles the conversation. The chat never shows a guessed waiting time.

While a conversation runs:

• Read receipts. Each message the visitor sent shows Sending…, then Sent, then Read once a team member who can reply has opened the conversation or replied. A message that could not be sent shows Not sent with Retry.
• Typing. With the typing indicator on, the visitor sees when an agent is writing a reply, and the agent sees Customer is typing…. See Typing indicator and typing preview.
• Only from people who can reply. A colleague who can read a conversation but not reply to it never causes Read or a typing signal in the chat.
• New messages. A visitor who scrolled up to read is never pulled down when a reply arrives; a New messages button takes them to it.
• Earlier messages. The chat loads the latest 50 messages; Show earlier messages loads the ones before them.
• Unread replies. The chat button shows the number of replies the visitor has not read yet — 9+ above nine — and nothing else.

Buttons and cards in a reply#

A reply from your team can carry one of these under its text. The text is always there too, so nothing is lost where a button cannot be shown.

Agents add quick replies, article cards and link buttons with Add to reply. The invitation card is sent when an agent starts live support and invites the customer. See Add to reply and Live support from a ticket.

On phones#

On a narrow screen (under 520 pixels wide) the open chat fills the screen. It is sized to the part of the screen that stays visible above the on-screen keyboard, so the message field is never hidden behind it. The page behind the chat does not scroll while the chat is open, and the chat button keeps clear of the phone's bottom edge. You can give the button a different shape, size and distance on phones. See Launcher button.

Create a widget#

You need Support administration. By default, Owners and Admins have it.

A new widget stays open after the first save, with the message Widget created. Its install code is under “Publish”, and you can now add brand images. The Install code and the Direct chat link are in the Publish step. The widget's card in Web chat widgets shows them too, together with the Embed URL, each with a copy button.

For a widget that already exists, Save publishes your changes to visitors at once and closes the editor. To prepare changes without showing them yet, use Save draft. See Drafts, publishing and versions.

Identity#

Brand images can be added after you save the widget for the first time. Each is a PNG, JPEG or WebP image of up to 1 MB and at most 2048 × 2048 pixels, and is saved as soon as you upload it, separately from the Save button. Images are not part of drafts or versions.

Hidden information is removed. When you upload a picture, HyoNova removes the information hidden inside the file: where and when it was taken, the device, an embedded thumbnail and comments. The picture itself is not changed and keeps its orientation. An animated PNG becomes a still picture. The same applies to agents' support photos.

Agents' photos. Beside an agent's replies, visitors see the agent's support photo and first name. An agent sets the photo in the inbox; a Support administrator can set it for anyone on the Agents page. When an agent leaves your company, their photo is deleted and their earlier replies show initials. See Your support photo and Agents and support photos.

Where there is no logo or photo, the chat shows initials. It never invents a picture.

Launcher button#

The launcher is the button that opens the chat on your website.

• Desktop and mobile are set separately. Button on Desktop and Button on Mobile each have their own shape, size and distances. A new widget uses a pill with a label on desktop and a round button on mobile.
• Readability of the button. The editor measures the contrast between the label and the button colour and tells you the result: Easy to read, readable at the size of the button but weaker than the 4.5:1 recommended for text, or Too weak to read. If the label colour you chose cannot be read on the button, the chat uses black or white instead.
• The round button shows no label, but screen readers still read it.
• Reset the launcher to defaults brings back the standard button.

Home screen, help and starters#

These settings are in the Experience step.

Each conversation starter has a label and an optional second line in English and Arabic, and one of three actions: Sends its label as the first message, Opens the help articles or Opens previous conversations. A starter needs a label in at least one language. A starter that opens help or previous conversations is not shown to visitors while that view is off. Restore the default starters brings back the three starters a new widget begins with.

You write help articles in Company administration › Support › Help articles. Published articles are public; drafts stay hidden, and so does an article that is past its Review by date. See Help articles.

Page rules#

A page rule gives some pages of your website their own start of the chat — for example your pricing page. Page rules are in the Experience step, under the conversation starters. A widget can have up to five.

• What is compared. Only the path of the page address — the part after the domain. The domain and everything after ? or # are not looked at, and capital and small letters count as the same. /pricing matches https://example.com/en/pricing/plans.
• The first matching rule wins. Rules are checked from the top. Use Move up and Move down to order them.
• Empty fields fall back. An empty greeting or introduction uses the general one. With no starter ticked, all starters are shown.
• It never opens the chat. A rule changes what the home screen says when the visitor opens the chat on a matching page. It does not open the chat by itself.
• Where the address comes from. With the install snippet it is the page that shows the chat button. On the direct chat link it is the page the visitor came from, when the browser reports it. The embed URL has no page address, so it always starts with the general text.

Without rules, the editor says No page rules: the chat starts the same way on every page.

Language#

The chat is in English or Arabic. It chooses the language in this order:

1. The widget's Language setting, when it is English or Arabic. A fixed language is final and shows no language switch.
2. The visitor's own choice. When the widget's Language is Visitor's language, the bottom of the chat has a language switch. The choice is remembered in that browser.
3. The language of your page — the lang attribute of its <html> tag.
4. The browser's language.

Arabic is chosen when the language found is Arabic; anything else gives English. Greetings, starters and button labels have an English and an Arabic field so that each visitor reads your own wording.

Live preview#

The editor shows a Live preview beside the form: the real chat with sample conversations. Nothing typed in it is sent.

• What to show — Closed: the launcher button, Home screen, AI Employee answering, Waiting for the team, Team is away, Agent answering, Help articles or Nobody available.
• Device — Desktop or Mobile.
• Chat language — English or Arabic.
• Preview as page — shown when the widget has page rules. Choose a rule to see the home screen as a visitor on a matching page would, or A page without a rule.

The preview follows the form as you edit, before you save. It always shows the button in its own corner; the side of the page and the distances apply on your website. Hide the preview closes it and Show the preview opens it again; on a narrow window it starts closed.

Drafts, publishing and versions#

What visitors see is the published settings of a widget. The editor of an existing widget has two buttons:

A draft is checked like a publish, so a form with a problem cannot be saved as a draft either. A new widget has no draft: its first Save creates and publishes it.

While a draft waits:

• The widget's card in Web chat widgets shows Draft not published, and the readiness check lists it as a note.
• The editor opens on the draft and says You are editing a draft that is not published yet. Visitors still see the published settings., with when the draft was saved and by whom.
• Publish draft publishes what the editor shows — including changes you made since the draft was saved.
• Discard draft deletes the unpublished changes after you confirm. The editor goes back to the published settings, and visitors notice nothing.

There is one draft per widget, shared by everyone who can edit it.

Versions#

Each publish is kept as a version. The Versions list is in the Publish step, newest first, and shows the 50 most recent. Each entry has its number (Version 3), First version, Published or Restored from version 2, the date and who did it. Current marks what visitors see now.

• A version holds all settings of the widget, including its Status, its Allowed domains, and where conversations go.
• An unpublished draft is replaced when you restore a version.
• Brand images are not versioned. The current images stay as they are.
• A version saved in a format that is no longer valid cannot be restored. HyoNova says This version was saved in an older format and cannot be restored.

Install the snippet#

Copy the Install code from the widget's Publish step, or from its card in Web chat widgets, and paste it into your website's HTML, just before the closing </body> tag of every page that should show the chat — or once in your site's shared layout or template.

It looks like this:

<script async src="https://chat.hyonova.com/chat/widget.js" data-widget-id="w_YOUR_WIDGET_ID"></script>

Always copy the real snippet from Web chat widgets; it contains your widget's id. The id is public — it names the widget, it is not a password. What protects your widget is the list of allowed domains.

The chat is served from its own address, chat.hyonova.com, and the install code you copy uses it. An install code you copied earlier points at HyoNova's earlier chat address. It keeps working and does not need to be replaced.

• The script loads async, so it does not slow your page down.
• If your website sends a Content-Security-Policy, allow https://chat.hyonova.com in script-src and frame-src. See Content-Security-Policy.
• Website builders (for example WordPress, Shopify, Wix or Webflow) usually have a place for "custom code" or "footer scripts". Paste the snippet there.

When the page loads, the chat button appears at the position you chose. The conversation stays in the visitor's browser: if they come back within 30 days on the same browser, they continue the same chat.

The chat and your page#

• Your site's CSS cannot change the chat. The chat keeps its own size, place and look. A broad rule of your theme for frames — for example one that makes every iframe full width — does not resize, move or hide it. To change where the button sits and how it looks, use the Launcher button settings.
• The chat changes nothing on your page. It adds no fonts and no styles, and it does not move your layout. On desktop the page scrolls as before while the chat is open. Only on phones, where the open chat fills the screen, the page behind it does not scroll.
• Open the chat from your own button. The snippet adds HyoNovaChat to your page: HyoNovaChat.open() opens the chat and HyoNovaChat.close() closes it. Besides it, the snippet adds one more global name for its own use, and nothing else.

Content-Security-Policy#

A website that sends a Content-Security-Policy must allow the chat. Otherwise the browser blocks it and the chat button does not appear.

• An install code you copied earlier. It loads the chat from HyoNova's earlier chat address. While that code is on your site, keep the address in its src in script-src and frame-src as well, or replace the code with a new copy from Web chat widgets.
• The embed URL needs only frame-src.
• Nothing else is needed. The chat loads no fonts, styles or images into your page.

If the button is still missing, see The chat button does not appear on a site with a Content-Security-Policy.

Allowed domains#

The chat starts only on websites whose address matches an entry in Allowed domains (up to 50 entries). HyoNova checks the real address of the page that embeds the chat, as reported by the browser.

Rules:

• Add both example.com and *.example.com if the chat should run on the main domain and on its subdomains.
• HTTPS only. Pages served over plain http:// cannot load the chat.
• A bare * is not allowed. Each entry must be a real domain.
• An empty list allows no website. The widget then works only through the direct chat link.
• HyoNova's own addresses are refused. You cannot add an address that belongs to HyoNova itself, such as the address of the HyoNova app or of the chat. A wildcard entry that would cover one is refused too.

If the domain is not allowed, the chat simply does not appear on that site. The widget gives the same neutral answer for an unknown, disabled or disallowed widget, so nothing about your company is revealed to other websites.

Direct chat link#

The direct chat link opens the chat as a full page on HyoNova's chat address, chat.hyonova.com, so it does not depend on your website. Share it in email signatures, on social profiles, or in a QR code. A link you shared earlier keeps working. Turn Direct chat link off in the widget's Publish step to stop it; the link then shows This chat is not available.

Embed URL#

The embed URL is the chat as a page that sits inside a frame on your own page, for example in a help centre. Use it when you want the chat inside your page layout instead of as a floating button.

Copy the Embed URL from the widget's card in Web chat widgets and use it as the address of a plain <iframe>. The install snippet is not needed for it.

<iframe src="YOUR_EMBED_URL" title="Chat" style="width: 400px; height: 600px; border: 0"></iframe>

• Only on allowed domains. The page that holds the frame must be on a domain in Allowed domains. Browsers refuse to show the chat in a frame on any other site, and HyoNova checks the framing site again before the chat starts.
• Let the browser name your page. Do not set referrerpolicy="no-referrer" on the frame. Some browsers use the referrer to tell the chat which site frames it; without it the frame stays empty.
• Content-Security-Policy. If your website sends one, allow https://chat.hyonova.com in frame-src. An embed URL you copied earlier keeps working; keep its address in frame-src while you use it. See Content-Security-Policy.
• The chat fills the frame, so give the frame the size you want. Page rules do not apply in a frame.

Online and offline#

The team counts as available when the widget's business hours (if set) are open and at least one agent of the widget's queue is Online. If the queue has no members, any agent who is Online counts.

An agent counts as Online only while they chose Online and have HyoNova open. Within about three minutes of closing HyoNova, the agent counts as away for visitors, although the status they chose is not changed. See When you count as online.

When nobody can answer and the visitor has no open conversation, the widget does what you chose under Outside business hours. Despite its name, this setting applies whenever nobody can answer — also inside your business hours when no agent is Online.

• Leave a message (form) (default): the visitor leaves a message with their name and an email or phone number, so your team can answer later. The message arrives in the inbox as a conversation with a ticket, like any other, and is marked as an offline message.
• Chat anyway (answered later): the visitor can write in the chat; the message waits in the inbox for the next agent.

The Offline message is the text visitors see when nobody can answer. Leave it empty to use the chat's standard wording.

A visitor who already has an open conversation keeps writing in it. Until an agent takes it, the chat says The team is away. See Who answers.

Pre-chat form#

Turn on Ask for details before the chat under Pre-chat form to ask for details before the first message. For each of Name, Email and Phone, choose Not asked, Optional or Required.

Details typed by a visitor are stored on the conversation but are not verified: HyoNova never links a chat to a customer in Customers on the strength of an email or phone the visitor typed. An agent decides. See Customer context.

Attachments#

With Visitors can attach files on, a visitor can add files to a message:

• Up to five files per message, 5 MB each. A larger file is refused with The file is too large.
• Preview and remove before sending. Each chosen file appears above the message field with its name and size — images with a small picture — and a button to remove it.
• Progress and retry. While a file uploads, the message shows how far it is. If sending fails, the message shows Not sent with Retry.
• The first message can carry a file. A message can also consist of files only.

HyoNova checks that each file's content matches its type and refuses the same kinds of files as in the inbox. See Attachments.

Typing indicator and typing preview#

While someone is typing, in the Privacy and features step, has three choices:

The indicators start once a conversation exists, that is, after the visitor's first message.

Live typing preview is off unless you choose it, and it is built to share as little as possible:

• The visitor decides. Inside the chat, the visitor reads You can share what you type with the support agent as you write, for a faster reply. Your message is only sent when you press Send. and chooses Share or No, thanks. Afterwards the chat always says Sharing what you type or Not sharing what you type, with Stop or Share to change it at any time.
• The answer lasts 30 days. The visitor's answer — yes or no — is remembered in their browser for 30 days. After that the chat asks again.
• Few people can read it. Only the agent the conversation is assigned to, and Support managers, can see the unsent text.
• It lives for seconds. The text is kept for about ten seconds in temporary storage that is not backed up. It is deleted when the visitor sends the message, empties the field or stops sharing, when the conversation is assigned to someone else, and when the time runs out.
• It is never a record. The unsent text is not copied to the ticket, to Customers, to search, to the audit log or to AI.
• Likely secrets are held back. Text that looks like a payment card number, a password or a code is not shared at all; the agent then sees only that the visitor is typing. This detection is a best effort: it cannot recognise every secret, so tell visitors not to type passwords or card numbers into a chat.
• Only the message field. The preview reads the chat's own message field and nothing else on your page.

For what the agent sees, see Customer draft.

More widget options#

Privacy#

• No account, no tracking across sites. Visitors do not sign in. The chat keeps a short-lived token, valid for two hours, and a resume key that lets the same browser continue the chat for up to 30 days. Each reaches only that visitor's own conversations on that widget.
• Only what the visitor writes. The chat sends HyoNova the visitor's messages and files, the page address where the chat was opened, the page's language and the browser language, so your team can answer in context. It does not read anything else from your page.
• The page address without its query string or fragment. Only the site and the path are sent and kept. Everything after ? or # is left out, because that part of an address can carry codes or tokens.
• The page your agents see. Agents see this address as Page beside the conversation. It is always an address on the site where the chat is installed: the page with the chat button, or the site itself when the chat sits in a frame. A conversation that came through the direct chat link shows no page.
• Counters, never text. For your analytics, the chat counts what was done by name — for example that the chat was opened or a help search found nothing. A counter holds no text, no page address and nothing about the visitor.
• Kept in the visitor's browser. Besides the resume key, the browser remembers the visitor's language choice and, for 30 days, their answer about sharing what they type.
• Typing preview is the visitor's choice. Without their agreement no unsent text leaves their device. See Typing indicator and typing preview.
• Help articles are public. Every visitor of a widget with Help articles on can read your published articles. Your company's other documents and knowledge are never shown to visitors.
• Limits against abuse. A visitor can start at most five new conversations per hour, and requests are rate-limited.
• Your policy. Add your privacy policy link to the widget, and mention HyoNova Support chat in your website's privacy notice. See Privacy.