Configure the widget

Most widget settings live in the dashboard and apply to every page that loads your snippet. A few can be overridden per page with window.HATANG_CONFIG. This page lists every setting, its limits and how the widget uses it.

Before you start

• You have installed the widget and created a website channel.
• Your role has the chat:manage permission.

Where the settings are

Open Support → Channels and pick your website. The site page has three tabs:

Tab	What it holds
Settings	The snippet, everything on this page, the identity secret and site deletion.
Automation	Follow-ups, social proof toasts, satisfaction rating (CSAT) and conversion tracking, plus the flows and campaigns active on this site.
Apps	The mobile apps that use this site's widget settings. See Mobile apps.

The Preview pane next to the form runs the real widget and follows your unsaved changes. Switch it between Open, Launcher, Offline and Pre-chat, and between Desktop and Phone.

Click Save settings when you are done. Widgets pick up changes within a minute.

General

Setting	Values	Notes
Domain	A host, e.g. shop.vn	The widget loads on this host and its subdomains.
Widget title	Text	Shown in the widget header. It is also the site's name in the dashboard.
Extra allowed origins	One origin per line	For local development and preview deployments, e.g. http://localhost:3000. Each must match exactly, including scheme and port.
Status	Active, Disabled (widget hidden)	Disabled hides the widget everywhere and keeps the history.
Colour	Hex color, default #111111	Launcher, header and visitor bubbles.
Position	Bottom right (default), Bottom left	Can be overridden per page with position.
Theme	Light (default), Dark, Match visitor's system	"Match visitor's system" follows the visitor's light or dark mode and switches live.

Launcher button

The round button in the corner of the page.

Setting	Values	Notes
Icon	Chat bubble (default), Support headset, Question mark, Round message	Preset icons in the widget color.
Button text (Vietnamese) / Button text (English)	Up to 24 characters each; empty means icon only	Turns the round button into a pill such as "Support". Add text if your website has its own chat feature, so visitors do not mix them up.
Custom image (optional)	An https:// URL of a square image, up to 500 characters	Replaces the icon, for example with your logo.

While the chat is closed, the launcher shows a red badge with the number of unread replies.

Window size and launcher position

Setting	Values	Notes
Chat window width	Narrow (340px), Medium (380px) (default), Wide (440px)	On screens 640px wide or less, the open chat fills the whole screen.
Desktop: bottom / Desktop: side	0–400 px; empty means 20px	Distance from the launcher to the corner.
Phone: bottom / Phone: side	0–400 px; empty means 16px	Used on screens 640px wide or less. When you leave both phone fields empty and set desktop values, phones use the desktop values.

The widget adds the device's safe-area inset (for example the iPhone home indicator) to the bottom offset. If your site has a bottom tab bar on phones, raise Phone: bottom above it. offset and mobileOffset in window.HATANG_CONFIG override these values field by field.

Chat header

Setting	Values	Notes
Show	Online agents' photos (default), Online agents' photos, or the logo when nobody is online, One chosen member's photo, Business logo	Agents mode shows up to three online agents. The second falls back to the logo when nobody is online. One chosen member's photo always shows that member (pick them in Member shown), online or not, and the logo if they leave the business. Logo mode shows the logo below, or the first letter of the widget title. Every SDK shows these: the server resolves them to agents' photos or the logo.
Logo (https URL, square image)	https:// URL, up to 500 characters	Used by Business logo, and as the fallback of the two choices above.
Intro line (Vietnamese) / Intro line (English)	Up to 120 characters each	A line under the title, such as "We usually reply in a few minutes".

Under the intro line, the header shows "We're online", or "We're away right now" followed by the next opening time when office hours are set.

Messages

Setting	Values	Notes
Default language	Auto (browser) (default), Tiếng Việt, English	See Language below.
Greeting (vi) / Greeting (en)	Up to 300 characters	The first bubble a visitor sees in an empty chat.
Away message (vi) / Away message (en)	Up to 300 characters	A notice at the top of the chat while nobody is available.
Show the greeting	On by default	Turn off to start with an empty chat.
Show the greeting on phones	On by default	Turn off to keep the greeting on desktop only.
Sign the greeting	Unsigned (default), An online agent	With an online agent, the first online agent's name appears under the greeting.
Pop the greeting over the launcher after	0–120 seconds; 0 = never	Shows the greeting as a bubble above the closed launcher, once per browser session, if the visitor has no conversation yet.

Language

The widget speaks Vietnamese or English. It picks the language in this order:

1. The language the page set earlier with the setLocale command (remembered in the browser).
2. locale in window.HATANG_CONFIG.
3. Default language in the dashboard, unless it is Auto (browser).
4. The browser language: Vietnamese if it starts with vi, otherwise English.

Other contact options

Buttons under the header that let visitors reach you elsewhere.

Setting	Notes
Zalo button	Opens your Zalo Official Account. Available only when a Zalo OA is connected to this website; otherwise the option shows not connected. See Zalo OA.
Messenger button	Opens your Facebook Page in Messenger. Available only when a Page is connected to this website. See Messenger and Instagram.
Phone number (call button)	A phone number, e.g. 0901 234 567 or +84 901 234 567. Opens the dialer.
Email (email button)	An email address. Opens the visitor's mail app.

Pre-chat form

Ask for details before a visitor's first message.

Setting	Values	Notes
Ask for details before the first message	Off by default	Turns the form on.
Name	Don't ask, Optional (default), Required
Phone	Don't ask, Optional, Required (default)	Vietnamese numbers (starting with 0, 84 or +84) must be a valid 10-digit mobile number; other numbers need 8–15 digits.
Email	Don't ask (default), Optional, Required

The form is skipped for visitors you have identified with a signature and for visitors who filled it in before in this browser. Only fields the widget does not know yet are asked. If nothing required is left to ask, the form is skipped. The answers are saved on the visitor and the customer profile.

Where the widget shows

Setting	Values	Notes
Devices	All devices (default), Desktop only, Phones only	"Phones" means screens 640px wide or less.
Only on URLs containing	Up to 20 lines, 200 characters each; empty = every page	The widget shows when the page URL contains any line.
Hide on URLs containing	Up to 20 lines, 200 characters each	The widget hides when the page URL contains any line, e.g. /checkout.
Play a sound for new messages	On by default	A short chime when a reply arrives while the chat is closed or the tab is hidden.
Flash the tab title while the visitor is on another tab	On by default	The tab title alternates with "(1) New message" until the visitor comes back.

Matching is a plain substring test on the full URL, and the widget re-checks it when a single-page app changes the URL. A chat that is already open stays visible.

Availability

Setting	Values	Notes
Use office hours	Off by default	Without office hours, the widget is online whenever at least one agent is online.
Timezone	IANA name, default Asia/Ho_Chi_Minh
Days and times	One time range per day, default 09:00 to 18:00	Tick the days you work.
Holidays	Dates as YYYY-MM-DD, comma-separated, up to 60	Treated as closed all day.
When nobody is online	Ask for the visitor's email before the first message (default), Ask, but allow skipping, Just accept the message	What the widget does when a visitor writes while you are offline.
Auto-resolve idle conversations after	0–365 days, default 3; 0 = never	Applies to every channel of this website except personal-Zalo groups. When the customer writes again, the conversation reopens and is routed by the current rules.
Hide the bubble entirely when offline	Off by default	Visitors who already have a conversation still see the widget.
Email the visitor a transcript when a conversation is resolved	Off by default	Needs the visitor's email.
Allow the widget inside cross-origin iframes	Off by default	By default the widget does not start inside an iframe whose parent page has another origin.
Notify these emails about new offline messages	Up to 20 addresses, comma-separated
Send chat emails from	An address on a domain verified under Email; blank = platform sender	The From address of chat emails to visitors.

How the widget decides it is online

The widget shows as Online when either:

• the AI assistant answers visitors (its mode is "when offline" or "first responder"), or
• it is within office hours (or no office hours are set) and at least one agent is online.

Otherwise it is Offline. The away message appears at the top of the chat, the header shows when you are back, and a visitor without a known email (or a phone number from the pre-chat form) is asked for one according to When nobody is online. With Ask, but allow skipping, the visitor can click Skip. The AI mode itself is set for the whole business under Support → AI assistant.

Automation tab

The Automation tab of the site holds:

• Follow-up when the visitor goes quiet: a fixed message or an AI-written nudge after the team's last message goes unanswered.
• Social proof toasts: "Hùng N. vừa đặt Áo thun" style toasts next to the launcher, from paid orders of the last 14 days or a hand-written list.
• Satisfaction rating (CSAT): stars in the widget when a conversation is resolved.
• Conversion tracking: chat started, lead and purchase events to your analytics. See JavaScript API.
• Lists of the flows and campaigns active on this site.

These are covered in Automation.

Identity secret and deleting the site

• Identity secret: lets your backend sign identify calls. See Identity verification.
• Delete site: permanently deletes the site with its conversations, visitors, connected social channels and app keys. To keep the history, set Status to Disabled (widget hidden) instead.

Page overrides with window.HATANG_CONFIG

Set window.HATANG_CONFIG before the widget script to change a few things on one page or one part of your site. Dashboard settings still apply to everything else.

<script>
  window.$hatang = window.$hatang || [];
  window.HATANG_SITE_ID = "site_123...";
  window.HATANG_CONFIG = {
    position: "left",
    locale: "en",
    hideLauncher: false,
    offset: { bottom: 24, side: 24 },
    mobileOffset: { bottom: 80, side: 16 }
  };
</script>
<script src="https://chat.hatang.dev/widget.js" async></script>

Key	Type	Effect
position	"left" or "right"	Overrides Position.
locale	"vi" or "en"	Starting language, unless the page called setLocale earlier. Overrides Default language.
hideLauncher	boolean	Hides the launcher button. Open the chat yourself with the open command or a data-hatang-open element.
offset	{ bottom?: number, side?: number }	Launcher distance from the corner in px (clamped to 0–400). Overrides Desktop: bottom / Desktop: side field by field.
mobileOffset	{ bottom?: number, side?: number }	Same, for screens 640px wide or less. Overrides Phone: bottom / Phone: side. Without it, phones use offset.

The config is read once when the widget starts. To change things later, use the JavaScript API (setLocale, hide, show).

note

With @hatang/chat-react, pass the same object as the config prop of <HatangChat />. With the WordPress plugin, Position and Language in the plugin settings write position and locale for you.

Next steps

• JavaScript API: commands and events for your own buttons and analytics.
• Identity verification: skip the pre-chat form for signed-in users and link their history.
• Automation: follow-ups, campaigns and distribution rules.