Key information

• Modern design – Clean, intuitive interface with smooth animations, dark mode, and a ChatGPT-like conversation layout.
• AI-first – Optimized for Generative AI Agents, built to showcase intelligent conversations and seamless voice transitions.
• Customization without code – Fully tailor design, placement, behavior, and advanced conditions directly in the interface.
• Performance boost – Loads up to 70% faster than the Legacy Widget, minimizing impact on site performance.
• Voice built-in – Integrated Hello mode enables customers to move from chat to voice without switching tools.
• Customer feedback built-in – Supports CSAT surveys and Thumbs Up/Down feedback natively inside the widget.
• Compliance & accessibility – Fully aligned with ADA standards and global accessibility requirements.

Configuring the Widget

The Widget is fully configurable in the Zowie dashboard under AI Agent → Channels → Zowie Chat.

All customization options are available directly in the interface, with live preview support so you can see changes before publishing.

General settings

• Widget title – Internal label for your widget.
• Widget description – Add a short description for context.
• Text input placeholder – Customize the placeholder text in the chat box (e.g., “Write to reply…”).
• Message’s author – Show or hide the author of messages in the chat.
• Brand logo – Upload your company logo (JPG, PNG, or GIF; min 200×200 px; max 2MB).

CTA (Call-to-Action)

• Chat prompts – Decide if proactive prompts are displayed next to the widget icon.
• Show widget after X seconds – Delay widget visibility after page load.
• CTA placement –
  • Type – Icon only or icon with label.
  • Alignment – Bottom-left or bottom-right.
  • Padding – Adjust margins around the CTA.

Design

• Themes – System default, Light, or Dark mode.
• Colors – Configure primary color, font color, and CTA button color.
• Appearance options – Enable rounded or sharp corners.
• Brand welcome elements – Add custom header and subheader text inside the widget.
• Welcome message – Configure the message displayed when the widget is opened.

Advanced customization

• Schedules – Define availability times when the widget is displayed or hidden.
• AI Session Notice – Add a disclosure (heading + message) informing customers the chat is handled by AI, aligned with regulatory requirements (EU, US, state).
• Widget layer order (z-index) – Control how the widget overlays other site elements.
• Session timeout – End inactive chats after a set time (disabled by default).

Notifications

• New message sound – Toggle on/off.
• Browser title change – Flash page title to signal a new message.
• Push notifications – Enable desktop notifications (macOS + Windows supported).

File & interaction options

• File uploads – Select which file formats are allowed (AAC, AVI, CSV, DOC, DOCX, GIF, HEIC, HEIF, HTML, JPEG, JPG, JSON, MOV, MP3, MP4, PDF, PNG, RAR, RTF, SPX, TXT, XLS, XLSX, ZIP, ZIP7).
• Emoji picker – Enable or disable emoji selection.
• Transcript download – Allow customers to download their conversation transcript.
• Start with a message – Automatically display a starter message when the widget opens.

Conditions on behavior

Define when the widget appears and how customers can interact:

• Show widget based on matched conditions – Display only under specific rules.
• Hide widget based on matched conditions – Suppress under specific criteria.
• Allow start conversation – Let users initiate chats when conditions are met.
• Disallow start conversation – Prevent starting new chats under certain conditions.
• Allow continue conversation – Let users resume ongoing interactions.
• Disallow continue conversation – Prevent resuming under certain conditions.

Condition types

• Website URL – Target rules based on the page a customer is visiting.
• Timezone – Apply rules depending on the customer’s local time zone.
• Locale – Show or hide the widget depending on the customer’s language or region.
• Custom – Use custom attributes you pass from your system (e.g., user segment, logged-in status).

Operators

The following operators are available:

• Equals
• Not equals
• Contains
• Not contains

Example

• Website URL + Contains “/checkout” → Hide widget (the widget won’t appear on checkout pages).
• Custom attribute Segment = VIP → Allow start conversation (only VIP users can open new chats).

Additional capabilities

Beyond standard configuration, the Widget also supports additional capabilities that enhance customer experience and business insights. These features are not visible in the Widget configuration interface and are enabled with the support of Zowie’s Customer Success team.

1. Built-In Feedback – Collect customer satisfaction (CSAT) surveys at the end of conversations, and capture quick message-level feedback with Thumbs Up / Down.
2. eCommerce Tracking – Track customer activity on your site (e.g., viewed products, cart updates, purchases) to better understand behavior and improve automation.
3. Rich Message Formatting – The Widget supports rich text formatting in both AI and human messages, following the CommonMark specification. This enables clean, readable messages with support for headings, lists, links, quotes, inline code, and emphasis (bold/italic). Additionally, Zowie Widget includes GitHub Flavored Markdown (GFM) extensions, allowing the use of tables and strikethrough for enhanced presentation and clarity.

Deploying the Widget

Widget

Once you’ve configured the Widget in AI Agent → Channels → Zowie Chat, you need to deploy it to your website. Deployment is available in the upper-right corner of the configuration screen under the Deploy section.

You can choose between two methods:

Method 1: JavaScript code snippet

1. In the Deploy section, copy the JavaScript snippet provided.
2. Paste it into your website’s HTML, right before the closing </body> tag.
3. Save and publish your site.

Method 2: Using Google Tag Manager

1. Log in to your Google Tag Manager account.
2. Create a new tag of type Custom HTML.
3. Paste the Zowie Widget code snippet into the tag configuration.
4. Check the Support document.write checkbox.
5. Set the trigger to All Pages (or customize as needed).
6. Save and publish the tag.

Embedded

You can also add the widget in form of embedded component on your website. Preferences set for Widget will be applied automatically to embedded version. Configuration of properties and control methods might vary (see below for details.)

Advanced Widget Configuration

Zowie Chat JS API Overview

The Zowie Chat JS API provides advanced control over widget behavior and functionality beyond what's available in the admin interface. This API allows you to:

• Pass user metadata to personalize interactions
• Trigger specific widget actions
• Respond to widget events
• Set conversation language
• Track widget interactions with analytics platforms

Available Properties

Here are some key properties you can customize with ZowieWidget.init():

Control Methods

Zowie Chat exposes these JavaScript methods for programmatic control:

Event Callbacks

You can register these callback functions to track widget activity:

Integration with User Authentication

Zowie Widget supports JWT authentication across multiple platforms (JS, iOS, Android, React Native) to enable personalized user experiences and conversation history continuity.

Setting Up JWT Authentication

To enable JWT authentication for your Zowie Widget:

1. Generate RSA key pair: Create a private and public key pair for RSA 256 JWT algorithm
2. Share public key with Zowie: Contact your Zowie representative to configure authentication verification on your account
3. Implement token generation: Generate JWT tokens on your backend server, not in client-side code

JWT Payload Structure

The JWT payload must follow this specific structure:

{
  "sub": "USER'S UNIQUE ID",
  "iat": 1516239022,
  "firstName": "USER'S LAST NAME",
  "lastName": "USER'S FIRST NAME",
  "email": "USER's EMAIL",
  "extraParams": {
    "tier": "101",
    "shopName": "Bike Store",
    "userType": "employee",
    "sessionToken": "ABCEDF12345"
  }
}

Recommended Best Practice

It's strongly recommended to use your unique customer/user ID as the value for the sub field.

Passing JWT Tokens to Zowie Widget

For JavaScript implementation, pass the token during initialization:

ZowieWidget.init("${INSTANCE_ID}", {
    externalAcessToken: jwtToken // JWT token generated on your backend
});

For dynamic token retrieval:

ZowieWidget.init("${INSTANCE_ID}", {});

ZowieWidget.setExternalAccessTokenCallback(function(onSuccess, onFailure) {
    // Your authentication logic here
    fetchUserToken()
        .then(token => onSuccess(token))
        .catch(error => onFailure("Authentication failed"));
});

Metadata and User Information

You can pass additional user information to personalize the chat experience using the metadata object:

ZowieWidget.updateMetadata({
    "firstName": "John",
    "lastName": "Smith",
    "locale": "en-US",
    "timezone": "GMT+1",
    "phoneNumber": "+48123456789",
    "email": "[email protected]",
    "extraParams": {
        "customerTier": "premium",
        "loyaltyPoints": "250",
        "lastPurchaseDate": "2025-03-15"
    }
});

The extraParams object allows you to pass custom key-value pairs beyond the default fields. All values should be strings, and the widget's backend will handle type conversion.

Locale

By default, Zowie uses recognized language and user's browser language to determine the conversation and Widget UI language. You can override this by setting the locale parameter:

ZowieWidget.init("instanceId", {
      metadata: {
        locale:"en-US",
      }
    });

Analytics and Performance Tracking

Track widget interactions using event callbacks:

ZowieWidget.init("${INSTANCE_ID}", {
    onShow: function() {
        // Widget became visible
        console.log("Widget shown");
        // Google Analytics example
        ga('send', 'event', 'Zowie', 'shown');
    },
    onHide: function() {
        // Widget was hidden
        console.log("Widget hidden");
    },
    onStart: function() {
        // User started a conversation
        console.log("Conversation started");
        ga('send', 'event', 'Zowie', 'conversation_started');
    },
    onOpen: function() {
        // Widget window opened
        console.log("Widget opened");
        ga('send', 'event', 'Zowie', 'opened');
    },
    onClose: function() {
        // Widget window closed
        console.log("Widget closed");
        ga('send', 'event', 'Zowie', 'closed');
    },
    onLoaded: function() {
        // Widget fully loaded
        console.log("Widget loaded");
        ga('send', 'event', 'Zowie', 'loaded');
    },
    onEndChat: function() {
        // User ended conversation
        console.log("Chat ended");
        ga('send', 'event', 'Zowie', 'ended');
    }
});