⚠️

Important: New Widget Available

A newer version of Widget is now available. Please follow the migration instructions in this guide to switch from the Legacy Widget to the new version. The Legacy Widget will be sunset by the end of October 2025.

Core Benefits

• Instant Customer Support: Provide 24/7 automated support without human intervention
• Seamless Website Integration: Minimal impact on website performance with only 70kB loaded at page load
• Multi-Channel Strategy: Part of Zowie's omnichannel approach to customer communications
• Data Collection: Capture valuable customer inquiries and feedback
• Reduced Support Costs: Automate repetitive inquiries and free up human agents for complex issues

Widget Appearance and Behavior Options

The Zowie Widget offers extensive customization options:

• Visual styling (colors, logo, placement)
• Behavioral settings (trigger timing, proactive engagement)
• Content personalization (greeting messages, placeholder text)
• Availability scheduling based on timezone
• Condition-based visibility rules
• Device-specific display options (desktop vs. mobile)

Step-by-Step Widget Implementation

Accessing the Widget Configuration Interface

1. Navigate to the Channels tab from the AI Agent menu
2. Select Widget from the channels list

Basic Widget Configuration

Before installation, configure your widget's appearance and behavior:

1. Widget Name: Enter the title to display at the top of your widget
2. Widget Description: Enter the description to display at the top of your widget
3. Logo (optional): Upload your company logo
4. Header and Message Colors: Customize to match your brand
5. Text Input Placeholder: Add helper text for the input field
6. Timing Availability Settings: Set when the widget should appear on the website

Once these settings are configured, click Save.

Installing the Widget on Your Website

Method 1: Using JavaScript Code Snippet

<script type="text/javascript">
(function(d, s, id, cb) {
    var js = d.createElement(s);
    var n = d.createElement("div");
    n.id = id;
    if (js.readyState) {
        js.onreadystatechange = function() {
            if (js.readyState === "loaded" || js.readyState === "complete") {
                js.onreadystatechange = null; 
                cb();
            }
        };
    } else {
        js.onload = function(){cb();};
    }
    js.src = "https://live-chat.chatbotize.com/chatbotize-entrypoint.min.js";
    document.body.appendChild(js);
    document.body.appendChild(n);
})(document, "script", "chatbotize", function() {
    Zowie.init({
        instanceId: "${INSTANCE_ID}",
        startOnOpen: true,
        headerMode: "white"
    });
});
</script>

⚠️

Important:

Download the snippet directly from the Zowie app using the Show code option in the Widget menu. This ensures you have the correct ${INSTANCE_ID} for your account.

Method 2: Using Google Tag Manager

1. Log in to your Google Tag Manager account
2. Create a new tag with Custom HTML type
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

After installation, the widget will appear in its default position (bottom-right corner).

Testing Widget Functionality

To ensure proper functionality across different environments:

1. Desktop Testing: Verify the widget appears correctly on various browsers (Chrome, Firefox, Safari, Edge)
2. Mobile Testing: Check responsiveness on different mobile devices and orientations
3. Functional Testing: Test conversation flows by initiating chats and verifying responses
4. Performance Testing: Ensure the widget doesn't negatively impact page load times

Best Practices for Widget Customization

Widget Customization Guidelines

Color Selection

• Match your widget colors to your brand's color palette
• Ensure sufficient contrast between text and background colors
• Consider using your primary brand color for the header and a complementary color for messages

Logo Requirements

• Use a transparent PNG format for best results
• Recommended dimensions: 25px × 25px
• Keep file size under 50KB for optimal loading

Widget Placement

The widget can be customized to appear in different positions on your website:

Zowie.init({
    instanceId: "${INSTANCE_ID}",
    startOnOpen: true,
    headerMode: "white",
    position: {
        "desktopRight": 25,  // Pixels from right edge on desktop
        "desktopBottom": 20, // Pixels from bottom edge on desktop
        "mobileRight": 20,   // Pixels from right edge on mobile
        "mobileBottom": 25,  // Pixels from bottom edge on mobile
        "mobileOffset": 475  // Mobile breakpoint in pixels
    }
});

Customizing Widget Behavior

Setting Conversation Language

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

Zowie.init({
    instanceId: "${INSTANCE_ID}",
    startOnOpen: true,
    headerMode: "white",
    metadata: {
        "locale": "en-US"  // Start conversation in English
    }
});

Engagement Timing

Set the appropriate delay before the widget appears to avoid disrupting the user experience:

• For product pages: 3-5 seconds (gives visitors time to view the product)
• For high-intent pages (pricing, contact): 3-5 seconds (engage while interest is high)
• For blog/content pages: 10+ seconds (allow reading time before engagement)

Conversation Starters

Configure initial messages that align with the page context:

• Homepage: "Hi there! How can I help you today?"
• Product pages: "Have questions about this product? I'm happy to help!"
• Checkout pages: "Need assistance completing your purchase?"

Interaction Patterns

You can customize interaction options:

Zowie.init({
    instanceId: "${INSTANCE_ID}",
    startOnOpen: true,
    allowPickEmoji: true,           // Enable emoji picker
    allowFileUpload: true,          // Allow file uploads
    allowFileExtensions: ".jpeg,.jpg,.png,.pdf",  // Permitted file types
    allowEndChat: true,             // Allow users to end chat session
    allowDownloadTranscript: true,  // Enable transcript downloads
    surface: "desktop-mobile"       // Platform visibility
});

Mobile Responsiveness Considerations

• Set appropriate mobile-specific positioning
• Use concise messages that display well on smaller screens
• Test widget behavior on various device sizes and orientations
• Consider setting different timing rules for mobile users

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:

• Customize widget appearance and behavior programmatically
• Pass user metadata to personalize interactions
• Control widget positioning and visibility
• 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 Zowie.init():

Control Methods

Zowie Chat exposes these JavaScript methods for programmatic control:

Event Callbacks

You can register these callback functions to track widget activity:

Widget Triggering Rules and Conditions

Zowie allows you to define specific conditions for when and where your widget appears:

URL-Based Visibility

Configure the widget to appear only on specific pages:

1. Navigate to the Placement tab in widget settings
2. Use the URL patterns section to include or exclude pages
3. Common patterns:
   • example.com/products/* (wildcard for all product pages)
   • example.com/checkout (exact match for checkout page)
   • !example.com/help/* (exclude help pages)

Metadata-Based Conditions

You can control widget visibility and behavior based on custom metadata conditions through the Placement tab:

1. Show widget based on matched conditions: Make the widget visible only when specific criteria are met
2. Hide widget based on matched conditions: Prevent the widget from appearing when certain criteria are met
3. Allow start conversation based on matched conditions: Control when users can initiate conversations

To configure these conditions:

1. Navigate to the Placement tab in Widget settings
2. Scroll to the relevant section (Show/Hide/Allow start conversation)
3. Click the Add button to create a new condition
4. Select the parameter type from the dropdown (Custom)
5. Enter the parameter name (e.g., "segment")
6. Select the operator (equals)
7. Enter the expected value (e.g., "Segment Gold")
8. Click Add to save the condition

For example, you might create rules such as:

• Show widget when customer_type equals premium
• Hide widget when page_section equals checkout
• Allow conversation when visit_count greater_than 3

These conditions work with metadata that you can pass to the widget using the Zowie JS API:

Zowie.updateMetadata({
    "extraParams": {
        "segment": "Gold",
        "customer_type": "premium",
        "visit_count": "5"
    }
});

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"
  }
}

⚠️

Important:

The sub field is critical as it serves as the unique identifier for the conversation. Zowie uses this field to determine conversation context and allow users to access their complete chat history.

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:

Zowie.init({
    instanceId: "${INSTANCE_ID}",
    startOnOpen: true,
    accessToken: jwtToken // JWT token generated on your backend
});

For dynamic token retrieval:

Zowie.init({
    instanceId: "${INSTANCE_ID}",
    startOnOpen: true
});

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

For implementation on other platforms (iOS, Android, React Native), please refer to the SDK-specific documentation linked below:

Metadata and User Information

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

Zowie.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.

Analytics and Performance Tracking

Track widget interactions using event callbacks:

Zowie.init({
    instanceId: "${INSTANCE_ID}",
    startOnOpen: true,
    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');
    }
});

Troubleshooting

Common Issues and Solutions

Widget Not Appearing

• Verify the script is properly loaded in your page source
• Check for JavaScript errors in your browser console
• Ensure your instance ID is correct
• Verify the widget isn't hidden by CSS rules
• Check if visibility conditions are preventing display

Authentication Problems

• Verify JWT token format and signature
• Check expiration dates on tokens
• Ensure proper RSA key configuration

Conflicting with Other Site Elements

• Adjust z-index values
• Modify widget positioning
• Check for JavaScript conflicts with other tools

For further assistance, contact your Customer Success Manager at Zowie.