Widget settings

Every website has its own widget settings. Change them in the agent app under Websites, pick your website and use the Appearance, Forms, Business hours, Behavior and Security tabs, on the web or in the mobile app. Visitors get the new settings on their next page load.

Appearance#

The Appearance tab shows a live preview as you edit. On screens up to 480 px wide, the open chat fills the whole screen.

Pre-chat and offline forms#

The pre-chat form asks visitors a few questions before their first message, while your team is available. It is off by default; when you turn it on it asks for a name and an email.

The offline form replaces the chat when nobody is available (outside business hours, or when no agent is online). Its answers and message arrive in your inbox as an offline conversation. It is on by default and asks for a name (optional) and an email.

Each form has an optional intro message (up to 300 characters) and up to 10 fields. Every field has a label (up to 60 characters), can be required, and has one of these types:

• text: Single line of text (answers up to 200 characters)
• email: Email address, checked for a valid format
• tel: Phone number, checked for a valid format
• textarea: Several lines of text (answers up to 2,000 characters)
• select: Dropdown with 1–20 options of up to 60 characters each

Each field also has a key that identifies the answer: lowercase letters, digits and underscores, starting with a letter, up to 32 characters, unique within the form. Fields keyed name, email and phone also fill in the visitor’s profile (marked as unverified). Answers are checked again on our servers, so a modified page can’t skip required fields.

Business hours#

With business hours on, the widget is online only during your opening times, in the time zone you choose (any IANA zone, such as Europe/Berlin or America/New_York). Outside them, visitors see the offline form and when you open next.

• Each day can have up to 6 periods, like 09:00–12:30 and 13:30–17:00. A day without periods is closed.
• Use 24:00 to mean the end of the day. A period can’t cross midnight: split 22:00–02:00 into 22:00–24:00 and 00:00–02:00 on the next day.
• Add up to 100 holidays: dates you are closed all day.
• Business hours are off by default. When you turn them on, the starting schedule is Monday to Friday, 09:00–17:00, UTC.

When everyone is busy, visitors can still start a chat. If every online agent is at their chat limit, or your team has reached your plan’s concurrent-chat limit, the chat waits in a fair queue and the widget shows a waiting card with the visitor’s place in line and an estimated wait (“You’re #3 in line · Estimated wait: about 3 min”). It updates live, and the first chat in line is assigned as soon as an agent is free. To show only the place in line, turn on Hide estimated wait time.

Behavior#

The Behavior tab decides how visitors are notified, where the widget appears, what visitors can do in the chat and what the launcher does. In the agent app, open Websites, pick your website and choose Behavior, on the web or in the mobile app. A live preview shows the launcher, the chat and the waiting card as you change settings.

Notifications#

Visibility and restrictions#

Devices are told apart by the visitor’s browser:

• Desktop (computers and laptops)
• Tablet (iPad, Android tablets and other large touch screens)
• Mobile (phones)

Visitors the widget is hidden from never see the launcher. Restrictions are checked when the page loads, and page rules again whenever the address changes, including navigation in single-page apps.

Page rules#

Set Pages to Show only on matching pages or Hide on matching pages and add up to 50 rules. A page matches when any rule matches it. With the mode off, or without rules, the widget shows on every page.

• A value starting with / is compared with the page’s path (and query), so /checkout works on every domain the widget runs on. Any other value is compared with the full URL, like https://shop.example.com/sale.
• Case doesn’t matter.
• A value can be up to 500 characters, without spaces, quotes, <, > or backslashes.
• The Pages dialog has a tester: enter a path or URL to see whether the widget would show there before you save.

Country rules#

Set Countries to Show only in or Hide in and pick the countries. A visitor whose country is unknown counts as not listed: Show only in hides the widget from them, and Hide in shows it.

Country rules require your ZebChat deployment to know visitor countries. Where it doesn’t, the rules are saved but not applied yet, and the agent app says so next to them.

Features#

On click#

What the launcher does when a visitor clicks it:

• Open the chat panel (default): the chat opens on top of your page.
• Open in a new window: the chat opens in its own browser window (a new tab on phones), so it stays open while visitors browse. It continues the same conversation, and clicking a message preview opens it too. If the browser blocks the window, the panel opens instead.

ZebChat.open() from your own code always opens the panel, because browsers only allow pop-up windows from a real click.

Domains#

• Your website’s domain and each entry in Allowed domains match themselves and all of their subdomains: example.com also allows shop.example.com.
• An entry like *.example.com matches subdomains only.
• localhost and IP addresses can be added for testing.
• On any other host the widget stays hidden.

Spam protection#

Every widget is protected by rate limits per visitor, per IP address and per website.

For extra protection, set Spam protection to Cloudflare Turnstile in the Security tab. Visitors then pass a Turnstile check before a conversation starts, and our servers verify it with Cloudflare. The Turnstile script loads only for websites that turn this on.

Files and ratings#

• Visitors can attach images and documents at any time, including to start a chat: a file on its own is enough. The pre-chat form and spam protection still come first. Turn this off with File uploads in the Behavior tab.
• When a chat ends, visitors are asked to rate it (1–5 stars and an optional comment). Turn this off with Chat rating in the Behavior tab.

The visitor’s menu: details, transcripts and sound#

The ⋯ button in the chat header gives visitors up to three options. They work on phones too, where the chat fills the screen.

• Your details: visitors add or change their name, email and phone. Your team sees them on the visitor’s profile, marked unverified. Verified visitors see their details read-only, since they come from your site.
• Email transcript: emails the visitor a copy of the conversation, with the time of every message and links to shared files (valid for 7 days). Internal notes are never included. It is also offered when a chat ends, next to the rating. To protect your sender reputation, each chat can be emailed once every 10 minutes, and each visitor a few times an hour. Turn it off with Email transcript in the Behavior tab.
• Sound: a short chime for new replies while the chat is closed or out of focus. Visitors can turn it off; your page can too, with setSound. With Sound for new messages off in the Behavior tab, there is no chime and no Sound option at all.

Privacy & consent#

Configure this in Websites → your website → Privacy. Choose a consent mode:

• Off: the widget works as usual and remembers returning visitors.
• Manual: your site decides. Call ZebChat.consent(true | false) from your cookie banner.
• Regional: ZebChat applies the rules of the visitor’s region, decided on the server from their country.

The widget decides in this order, first match wins:

1. Global Privacy Control (where honoured) or the visitor’s own opt-out;
2. ZebChat.consent() called by your page;
3. the visitor’s remembered answer (asked again after 180 days or a settings change);
4. the region’s default.

Chat always works, even without consent: the visitor key stays in memory, and nothing is stored in the browser or tracked. You can also ask visitors to tick I agree to the privacy policy before their first message (this needs a privacy policy URL). Consent decisions are logged for you; see Security & data.

Verified visitors#

If your visitors log in to your site, you can tell ZebChat who they are with a signature your server computes. Create the website’s identity secret in the Security tab, then follow setUser.

Changing settings through the API#

Settings are stored per website and can also be updated with PATCH /websites/{websiteId}. Updates are partial, even inside nested objects: omitted fields keep their value. Lists (form fields, one day’s periods, holidays) are replaced as a whole. This example turns on business hours, sets the time zone and changes only Saturday:

PATCH /api/v1/organizations/{organizationId}/websites/{websiteId}
Authorization: Bearer <access token>
Content-Type: application/json

{
  "settings": {
    "businessHours": {
      "enabled": true,
      "timezone": "Europe/Berlin",
      "weekly": { "sat": [{ "start": "10:00", "end": "14:00" }] },
      "holidays": ["2026-12-25", "2026-12-26"]
    }
  }
}

Authentication#

Call the API with a signed-in user’s access token, or from your server with an API key (Pro and Enterprise). See the REST API overview.