Chat Widget Guide
Learn how the chat widget works from your customers' perspective. Understand the user interface, features, and how customers can interact with your AI-powered assistant.
The Customer Experience
The WooAI chat widget provides customers with instant access to AI-powered assistance right on your WooCommerce store. Here's what they'll experience:
Widget Features
Common Customer Use Cases
Here are the most common ways customers use the chat widget:
Widget Interface Elements
Launcher Button
The floating button that appears in the corner of your website:
- Click to open: Opens the full chat window
- Notification badge: Shows unread message count
- Tooltip: Optional "Need help?" message on hover
- Animation: Subtle pulse to draw attention (configurable)
Chat Header
The top section of the open chat window:
- Avatar: Your chatbot's profile image or emoji
- Name: The chatbot's name (e.g., "Store Assistant")
- Status: Online indicator showing the bot is active
- Close button: Minimizes the chat window
Message Area
The main conversation space:
- Bot messages: Displayed on the left with bot avatar
- User messages: Displayed on the right in primary color
- Timestamps: Shown when messages are minutes apart
- Typing indicator: Shows when bot is generating response
- Product cards: Rich displays when products are recommended
Input Area
Where customers type their messages:
- Text field: Input area with placeholder text
- Send button: Submits the message
- Quick replies: Clickable suggestion buttons when available
Product Cards
When the chatbot recommends products, it displays rich product cards with:
| Element | Description |
|---|---|
| Product Image | Thumbnail of the product |
| Product Name | Clickable link to product page |
| Price | Current price with sale price if applicable |
| Stock Status | In Stock / Low Stock / Out of Stock |
| Add to Cart | Quick add button (for simple products) |
| View Details | Link to full product page |
Product cards display up to 3 recommended products by default. Customers can click "View all results" to see more options or visit the search page.
Keyboard Shortcuts
Power users can interact with the chat widget using keyboard shortcuts:
| Shortcut | Action |
|---|---|
| Enter | Send message |
| Shift + Enter | New line (multiline message) |
| Esc | Close chat window |
| ↑ | Edit last message (if empty input) |
Mobile Experience
On mobile devices, the chat widget provides an optimized experience:
Mobile-Specific Features
- Full-screen mode: Chat opens in a full-screen overlay for better usability
- Touch-friendly: Larger tap targets for buttons and links
- Smart keyboard handling: Input field stays visible when keyboard opens
- Swipe to close: Swipe down to minimize the chat
- Safe areas: Respects notch and home indicator on modern phones
Mobile Launcher
On smaller screens, the launcher button:
- Automatically sizes for touch (minimum 44x44px)
- Positions safely away from native UI elements
- Can be hidden on specific mobile pages (configurable)
Always test the chat widget on real mobile devices, not just browser dev tools. Touch interactions and keyboard behavior can differ significantly from desktop simulation.
Conversation Flow
Understanding how conversations typically progress helps you optimize your chatbot setup.
Typical Flow
1. Customer opens chat
└─ Welcome message displayed
2. Customer asks a question
└─ AI processes and responds
3. If product-related:
└─ RAG search finds relevant products
└─ Product cards displayed
4. Customer can:
├─ Ask follow-up questions
├─ Add product to cart
├─ Request more options
└─ Close chat
5. Session ends
└─ Conversation saved for potential returnPlaybook Triggers
Certain customer messages can trigger Playbook automation:
- Keyword triggers: "shipping", "return", "track order"
- Intent triggers: Detected purchase intent or support need
- Context triggers: Based on current page or cart status
Human Handoff
When customers need human assistance, the chatbot provides clear options:
Automatic Escalation
The chatbot may suggest human support when:
- Customer explicitly requests human help
- AI confidence is low after multiple attempts
- Sensitive issues are detected (complaints, billing disputes)
- Complex questions beyond AI capabilities
Handoff Options
Depending on your configuration, customers can be directed to:
- Email: Contact form or direct email link
- Phone: Phone number for calling
- Live Chat: Integration with live chat platforms
- Ticket System: Create a support ticket
- Callback Request: Collect phone for callback
Never trap customers in AI-only interactions. Always provide a clear path to human support for situations the AI cannot handle. This builds trust and improves customer satisfaction.
Widget Embedding Options
The chat widget can be displayed in different ways:
Floating Widget (Default)
The standard floating button and popup window that appears in the corner of every page.
/* Automatically loaded - no code needed */Inline Embed
Embed the chat directly into a page section using a shortcode:
[wooai_chat_inline height="500px"]Page-Specific Display
Control where the widget appears using the page visibility settings in Appearance configuration.
Shortcode Attributes
| Attribute | Description | Default |
|---|---|---|
height |
Height of inline widget | 500px |
welcome |
Custom welcome message | Default message |
context |
Page context hint | Auto-detected |
Performance
The chat widget is optimized for minimal impact on page performance:
Load Optimization
- Lazy loading: Widget JavaScript loads only after page is interactive
- Minimal footprint: Initial bundle under 50KB compressed
- Code splitting: Additional features load on demand
- No jQuery dependency: Pure JavaScript implementation
Response Times
| Action | Typical Time |
|---|---|
| Widget open animation | < 200ms |
| Message sent to processing | < 100ms |
| AI response (simple query) | 1-2 seconds |
| AI response with RAG search | 2-4 seconds |
| Product card rendering | < 300ms |
If responses feel slow, consider using a faster AI model like gemini-1.5-flash or gpt-4o-mini. These models provide excellent quality with significantly faster response times.
Accessibility
The chat widget is built with accessibility in mind:
Features
- Keyboard navigation: Full keyboard support for all interactions
- Screen reader support: ARIA labels and live regions for dynamic content
- Focus management: Proper focus handling when opening/closing
- Color contrast: WCAG 2.1 AA compliant default colors
- Reduced motion: Respects prefers-reduced-motion setting
ARIA Labels
<!-- Example ARIA implementation -->
<button aria-label="Open chat" role="button">...</button>
<div role="log" aria-live="polite" aria-label="Chat messages">...</div>
<input aria-label="Type your message" placeholder="...">Troubleshooting
Widget Not Appearing
- Check that WooAI is activated and license is valid
- Verify the page isn't in the "Hide on Pages" list
- Check for JavaScript errors in browser console
- Ensure no ad blocker is blocking the widget script
- Clear all caches (WordPress, CDN, browser)
Messages Not Sending
- Verify AI provider API key is configured and valid
- Check browser network tab for failed API requests
- Ensure your server allows outbound HTTPS connections
- Test with a different browser to rule out extensions
Slow Responses
- Switch to a faster AI model
- Check Supabase connection for RAG queries
- Reduce "Max Results" in RAG settings
- Verify your server isn't resource-constrained
Widget Styling Issues
- Check for CSS conflicts with your theme
- Use browser inspector to identify conflicting styles
- Add custom CSS with higher specificity if needed
- Test with a default WordPress theme to isolate issues
Product Cards Not Showing
- Verify RAG is configured and products are indexed
- Test RAG search directly in settings panel
- Ensure product data includes descriptions (not just titles)
- Check similarity threshold isn't too high