Skip to main content

​
Web Widget Deployment & Customization

​
Introduction

The ChatCrafterAI web widget is your agent embedded directly on your website, providing instant, intelligent assistance to every visitor. Unlike external chat platforms that redirect users away from your site, the web widget keeps customers engaged on your pages while delivering personalized support.

​
What is the Web Widget?

The web widget is a lightweight, embeddable chat interface that integrates seamlessly into any website. It appears as a chat bubble or button (typically in the bottom-right corner) that expands into a full conversation interface when clicked. The widget is built with modern web technologies, ensuring fast loading times, responsive design, and compatibility with all major browsers.

​
Why Use the Web Widget?

​
Complete Control Over Look and Feel

Unlike third-party messaging apps with fixed designs, the web widget gives you total control over appearance. Customize colors to match your brand, choose positioning that fits your layout, and adjust sizing for optimal user experience. Your agent becomes a natural extension of your website rather than an external element.

​
Brand Consistency

Every interaction with the widget reinforces your brand identity. Use your brand colors, incorporate your logo, match your website’s typography, and maintain your established tone of voice. This consistency builds trust and makes the support experience feel integrated rather than outsourced. When customers need help, they want immediate answers without leaving their current context. The web widget provides this instant assistance without redirecting to another platform or requiring app downloads. This friction-free experience significantly improves conversion rates, with studies showing embedded chat can increase conversions by 20-40% compared to external support links.

​
Mobile Responsive Design

The widget automatically adapts to screen sizes, providing optimized experiences on desktop, tablet, and mobile devices. Touch-friendly buttons, appropriate text sizing, and smart positioning ensure usability across all devices without requiring separate mobile implementations.

​
Zero Installation Requirements

Customers interact with your agent immediately upon clicking the widget—no account creation, app downloads, or platform switching required. This zero-friction approach maximizes engagement, especially for first-time visitors who aren’t yet invested in your brand.

​
Installation Process

Setting up the web widget takes just four simple steps:

​
Step 1: Generate Embed Code

  1. Navigate to your agent dashboard in ChatCrafterAI
  2. Click on “Channels” in the left sidebar
  3. Select “Web Widget”
  4. Click “Generate Embed Code”
  5. ChatCrafterAI creates a unique code snippet for your agent
The embed code is specific to your agent and includes all necessary configuration to establish a secure connection between your website and ChatCrafterAI’s servers.

​
Step 2: Copy Code to Your Website HTML

The embed code is a simple JavaScript snippet that you paste into your website’s HTML. For best results: Placement Location: Add the code just before the closing </body> tag on every page where you want the widget to appear. Most websites use a template system, so you typically only need to add it once to your main template file. Common Platforms:
  • WordPress: Add to your theme’s footer.php file or use a custom HTML widget
  • Shopify: Add to theme.liquid in the “Layout” section
  • Wix: Use the custom code feature in site settings
  • Squarespace: Add through Settings > Advanced > Code Injection
  • Custom HTML: Insert before </body> in your template file

​
Step 3: Customize Appearance

After installation, customize the widget to match your brand:
  1. Return to the Web Widget settings in ChatCrafterAI
  2. Access the “Customization” tab
  3. Adjust settings in real-time with live preview
  4. Save changes (they apply immediately)
All customizations are managed through ChatCrafterAI’s interface—no code changes required after initial installation.

​
Step 4: Test and Deploy

Before going live:
  1. Desktop Testing: Open your website and verify the widget appears correctly
  2. Mobile Testing: Check functionality on iOS and Android devices
  3. Browser Compatibility: Test in Chrome, Firefox, Safari, and Edge
  4. Conversation Testing: Send test messages to verify agent responses
  5. Performance Check: Ensure page load times aren’t negatively impacted
Once testing confirms everything works correctly, your widget is live and serving customers.

​
Customization Options

​
Colors and Branding

Primary Color: The main color used for the chat bubble, header, and agent message bubbles. Choose a color from your brand palette for immediate recognition. Secondary Color: Used for accents, buttons, and interactive elements. Should complement your primary color while providing sufficient contrast. Text Color: Customize text color for readability. The widget automatically suggests optimal text colors based on your background choices. Header Background: Customize the chat header separately from message areas for visual hierarchy.

​
Position and Placement

Corner Position:
  • Bottom-Right (Default): Most common placement, doesn’t interfere with content
  • Bottom-Left: Useful if right side has existing elements (accessibility tools, other widgets)
  • Top-Right: Less common but useful for specific layouts
  • Top-Left: Rarely used, available for unique design requirements
Margin Offset: Adjust distance from screen edges to align with your design grid or avoid conflicting elements.

​
Size and Dimensions

Chat Bubble Size:
  • Small: Minimalist approach, less prominent
  • Medium: Balanced visibility and subtlety (recommended)
  • Large: Maximum visibility for support-focused sites
Expanded Window Size:
  • Compact: Smaller conversation window, less screen coverage
  • Standard: Balanced size for most use cases
  • Full: Larger window for complex conversations

​
Welcome Message and Greeting

Greeting Text: The first message visitors see when opening the widget. Make it welcoming and action-oriented. Examples:
  • “Hi! How can I help you today?”
  • “Welcome! Ask me anything about our products.”
  • “Need assistance? I’m here to help!”
Proactive Message: Configure the widget to display a message automatically after a set time (e.g., “Been browsing for a while? I can help you find what you need!”). This can increase engagement by 30-50%. Greeting Avatar: Upload a custom avatar image that represents your agent or brand. This personalizes the experience and makes the agent feel more approachable.

​
Theme Options

Light Theme: Clean, bright interface suitable for most websites. Works well with light-colored websites. Dark Theme: Modern, elegant appearance. Reduces eye strain and works perfectly with dark-mode websites. Auto-Detect: Automatically matches the user’s system preference (light or dark mode), providing optimal experience for each visitor.

​
Language Settings

Select the primary language for your widget interface. This controls system messages, button labels, and default greetings. Your agent’s conversation language is configured separately in the knowledge base settings.

​
JWT Authentication for Logged-In Users

JWT (JSON Web Token) authentication enables personalized experiences for logged-in users by securely identifying them to your agent.

​
Why Use JWT Authentication?

Customer Recognition: Immediately identify returning customers by name, account ID, or email. Conversation Persistence: Maintain conversation history across sessions. When a logged-in user returns, they see their previous conversations. Pre-filled Data: Automatically populate customer information (name, email, account details) without asking users to repeat it. Enhanced Analytics: Track which specific users interact with your agent, enabling user-level analytics and personalization. Security: JWT tokens are cryptographically signed, preventing impersonation and ensuring only authenticated users access their data.

​
JWT Setup Process

  1. Generate JWT Secret: ChatCrafterAI provides a secret key in your widget settings. Store this securely on your backend server.
  2. Create Token on Your Server: When a user logs into your website, your backend generates a JWT token containing user information (ID, name, email) signed with your secret key.
  3. Pass Token to Widget: Include the JWT token when initializing the widget in your frontend code. The token is sent securely to ChatCrafterAI for verification.
  4. Verification: ChatCrafterAI validates the token signature, confirms authenticity, and associates the conversation with the identified user.

​
Conceptual Implementation

Your backend generates a token containing: 
{
  "userId": "12345",
  "email": "customer@example.com",
  "name": "John Smith"
}
Pass this token when the widget loads, allowing the agent to greet the user by name and access their history immediately.

​
Mobile Optimization

The web widget is built mobile-first, ensuring excellent experiences on all devices:

​
Responsive Design

The widget automatically adjusts dimensions, font sizes, and button spacing based on screen size. On mobile devices, the expanded chat window uses more screen space for easier interaction.

​
Touch-Friendly Interface

All interactive elements (buttons, input fields, quick replies) are sized and spaced for accurate touch interaction, following mobile usability guidelines.

​
Cross-Platform Compatibility

Works flawlessly on iOS Safari, Android Chrome, and all major mobile browsers without requiring special configurations or separate mobile versions.

​
Performance Considerations

​
Lightweight Embed

The widget’s initial load is under 50KB (compressed), ensuring minimal impact on page load times. This is smaller than most analytics scripts or advertising pixels.

​
Lazy Loading

Enable lazy loading to defer widget initialization until a user interacts with it or after page content fully loads. This prioritizes your main content while keeping support readily available.

​
Asynchronous Loading

The widget loads asynchronously, meaning it never blocks your page’s main content. Your website remains fully functional even if the widget experiences temporary loading delays.

​
CDN Delivery

Widget assets are served from a global Content Delivery Network (CDN), ensuring fast loading times regardless of visitor location.

​
Monitoring and Analytics

​
Conversation Metrics

Track total conversations initiated through the web widget, average conversation length, and resolution rates. This helps you understand how effectively your agent serves website visitors.

​
Page-Level Analytics

Identify which pages generate the most agent interactions. High interaction pages might need content improvements, while low interaction pages might need better widget visibility.

​
Drop-Off Analysis

See where users abandon conversations. If many users drop off after specific questions, your agent may need better training in those areas.

​
Conversion Tracking

Measure how agent interactions correlate with conversions (purchases, sign-ups, downloads). This quantifies the widget’s business impact.

​
Advanced Features

​
Pre-Chat Forms

Collect essential information (name, email, topic) before conversations begin. This helps route conversations appropriately and ensures you can follow up if users leave before resolution.

​
Offline Messaging

When your support team is offline or unavailable, the widget can collect messages and contact information, automatically creating support tickets or sending email notifications.

​
Canned Responses

Configure quick-access answers to common questions. Support agents taking over from the agent can use these for faster response times.

​
File Upload Support

Allow users to upload screenshots, documents, or images during conversations. This is invaluable for technical support or product-related inquiries.

​
Testing Your Widget

​
Desktop Testing Checklist

  • Widget appears in correct position
  • Colors match your brand
  • Welcome message displays correctly
  • Conversations work smoothly
  • Agent responses are accurate
  • Links and buttons function properly

​
Mobile Testing Checklist

  • Widget is visible and accessible
  • Touch interactions work accurately
  • Text is readable without zooming
  • Input field appears correctly with mobile keyboard
  • Conversation history scrolls smoothly
  • Images and media display properly

​
Browser Compatibility Testing

Test in all major browsers your customers use:
  • Google Chrome (desktop and mobile)
  • Safari (macOS and iOS)
  • Firefox
  • Microsoft Edge
  • Samsung Internet (for Android users)

​
Performance Testing

  • Measure page load time before and after widget installation
  • Verify widget doesn’t block page rendering
  • Check Network tab in browser DevTools for load times
  • Test on slow 3G connections to verify mobile performance

​
Common Issues and Fixes

​
Widget Not Appearing

Symptoms: The chat bubble doesn’t show up on your website Possible Causes and Solutions:
  1. Incorrect Code Placement: Ensure the embed code is placed just before </body> tag, not in <head>
  2. JavaScript Errors: Check browser console for errors that might prevent script execution
  3. Ad Blockers: Some ad blockers interfere with chat widgets; test in incognito mode
  4. Caching: Clear browser cache and force refresh (Ctrl+F5 or Cmd+Shift+R)
  5. Widget Disabled: Verify the widget is enabled in ChatCrafterAI dashboard

​
Slow Loading Times

Symptoms: Widget takes several seconds to appear or causes page slowdown Solutions:
  1. Enable Lazy Loading: Configure widget to load after page content
  2. Check Network: Use browser DevTools to identify slow-loading resources
  3. Verify CDN: Ensure CDN is delivering assets efficiently (check response times)
  4. Optimize Triggers: Disable proactive messages if they’re causing delays

​
Wrong Colors or Styling

Symptoms: Widget doesn’t match your customization settings Solutions:
  1. Clear Cache: Widget settings are cached; force refresh after changes
  2. Review CSS Conflicts: Your website’s CSS might override widget styles
  3. Check Customization Settings: Verify saved settings in ChatCrafterAI dashboard
  4. Use Incognito Mode: Test in incognito to rule out browser extension interference

​
JWT Authentication Not Working

Symptoms: Logged-in users aren’t recognized or see errors Solutions:
  1. Verify Token Format: Ensure JWT token follows correct structure
  2. Check Secret Key: Confirm you’re using the exact secret key from ChatCrafterAI
  3. Token Expiration: Implement reasonable expiration times (1-24 hours)
  4. Debug Token: Use JWT.io to decode and verify token contents
  5. Server Time Sync: Ensure your server clock is synchronized (JWT uses timestamps)

​
Next Steps

Now that your web widget is deployed, explore how to leverage it across multiple channels: The web widget serves as your primary customer touchpoint on your website, working in harmony with other channels to provide comprehensive, omnichannel support that meets customers wherever they choose to engage.