Chat Widget

​

Overview

​

Widget Features

​

For Visitors

• Instant responses - AI replies in seconds, 24/7
• Persistent conversations - Return visits continue the thread
• Mobile-friendly - Responsive design on all devices
• No account required - Just click and chat

​

For You

• Zero code deployment - Copy/paste embed snippet
• Customizable appearance - Match your brand colors
• Real-time monitoring - See chats in your inbox
• Human takeover - Jump in anytime to help

​

Setting Up a Widget

​

From Agent Deploy Tab

​

Embed Code

<script>
  (function(w,d,s,o,f,js,fjs){
    w['PatWidget']=o;w[o]=w[o]||function(){(w[o].q=w[o].q||[]).push(arguments)};
    js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
    js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
  }(window,document,'script','PatChat','https://magpipe.ai/widget/pat-chat.js'));
  PatChat('init', { widgetKey: 'YOUR_WIDGET_KEY' });
</script>

​

WordPress Installation

1. Go to Appearance → Theme Editor (or use a plugin like “Insert Headers and Footers”)
2. Edit footer.php or use the plugin’s footer section
3. Paste the embed code before </body>
4. Save changes

​

Shopify Installation

1. Go to Online Store → Themes → Edit Code
2. Open theme.liquid
3. Paste the embed code before </body>
4. Save

​

Wix Installation

1. Go to your site editor
2. Click Add → Embed → Custom Code
3. Paste the embed code
4. Set to load on “Body - end”
5. Publish

​

Squarespace Installation

1. Go to Settings → Advanced → Code Injection
2. Paste in the “Footer” section
3. Save

​

Customization Options

​

Appearance Settings

​

Position Options

• Bottom-right - Standard, doesn’t interfere with navigation
• Bottom-left - Alternative for right-heavy layouts

​

Messages

Hi there! 👋 I'm the AI assistant for Acme Corp.
How can I help you today?

Thanks for reaching out! We're currently closed.
Leave a message and we'll get back to you during business hours.

​

Visitor Information Collection

​

Widget Behavior

​

Conversation Flow

1. Visitor clicks chat bubble
        ↓
2. Widget expands with welcome message
        ↓
3. Visitor types question
        ↓
4. AI generates response (using agent prompt + knowledge)
        ↓
5. Conversation continues
        ↓
6. Session saved to Inbox

​

Session Persistence

• Visitor ID stored in browser localStorage
• Returning visitors see their conversation history
• Sessions expire after 30 days of inactivity
• Clearing browser data resets the session

​

Business Hours

• During hours: AI responds normally
• Outside hours: Shows offline message, still accepts messages

​

Viewing Chat Conversations

​

In the Inbox

1. Go to Inbox
2. Click Chat filter to show only widget conversations
3. Click a conversation to view the full thread
4. Reply to take over from the AI

​

Conversation Details

• Visitor info (name, email if provided)
• Page URL where they started chatting
• Browser/device information
• Full message thread with timestamps
• AI indicator on AI-generated messages

​

Human Handoff

​

Taking Over a Chat

1. Open the chat conversation in Inbox
2. Type your message in the reply box
3. Click Send

​

AI Pause Behavior

• AI immediately pauses for this conversation
• Your messages appear without the AI indicator
• AI resumes after 5 minutes of your inactivity

​

Handoff Indicators

• 🤖 = AI-generated response
• No indicator = Human response

​

Widget API

​

JavaScript Commands

// Open the chat widget
PatChat('open');

// Close the chat widget
PatChat('close');

// Toggle the widget
PatChat('toggle');

// Send a message programmatically
PatChat('sendMessage', 'Hello, I have a question about pricing');

// Set visitor info
PatChat('setVisitor', {
  name: 'John Doe',
  email: '[email protected]'
});

// Destroy the widget (remove from page)
PatChat('destroy');

​

Event Callbacks

PatChat('init', {
  widgetKey: 'YOUR_WIDGET_KEY',
  onOpen: function() {
    console.log('Chat opened');
  },
  onClose: function() {
    console.log('Chat closed');
  },
  onMessage: function(message) {
    console.log('New message:', message);
  }
});

​

Pre-filled Messages

// Link on your page
<a href="#" onclick="PatChat('open'); PatChat('sendMessage', 'I want to learn about your enterprise plan');">
  Contact Sales
</a>

​

Domain Restrictions

​

Why Restrict Domains

• Someone could embed your widget on their site
• They’d use your AI credits
• Conversations would appear in your inbox

​

Setting Allowed Domains

1. Go to widget settings
2. Enter allowed domains (one per line):
   Copy

   yoursite.com
   www.yoursite.com
   shop.yoursite.com
   
3. Save settings

​

Localhost for Testing

localhost
127.0.0.1

​

Styling and Theming

​

CSS Customization

/* Custom bubble position */
#pat-chat-widget {
  bottom: 100px !important;
  right: 20px !important;
}

/* Hide on specific pages */
.no-chat #pat-chat-widget {
  display: none;
}

​

Z-Index

​

Analytics

​

Widget Metrics

• Total chat sessions
• Messages per session (average)
• Response time (AI)
• Handoff rate (AI to human)
• Visitor satisfaction (if collected)

​

Google Analytics Integration

PatChat('init', {
  widgetKey: 'YOUR_WIDGET_KEY',
  onOpen: function() {
    gtag('event', 'chat_opened', { event_category: 'engagement' });
  },
  onMessage: function(msg) {
    gtag('event', 'chat_message', { event_category: 'engagement' });
  }
});

​

Troubleshooting

​

Widget Not Appearing

1. Check the embed code - Ensure it’s before </body>
2. Verify widget key - Must match exactly
3. Check domain restrictions - Your domain must be allowed
4. Check browser console - Look for JavaScript errors
5. Check for conflicts - Other scripts might interfere

​

Widget Behind Other Elements

​

Messages Not Sending

1. Check network tab for API errors
2. Verify agent is active
3. Check agent has permission for chat

​

Slow Responses

• OpenAI API latency (~1-3 seconds)
• Knowledge base retrieval (adds ~500ms)
• Network conditions

​

Best Practices

​

Placement

• Bottom-right is conventional and expected
• Don’t overlap with other floating elements
• Ensure mobile-friendly on all devices

​

Welcome Message

• Keep it short (1-2 sentences)
• Be welcoming but professional
• Set expectations (“I’m an AI assistant…”)
• Offer help immediately

​

Agent Configuration

• Mention it’s a website chat (not phone)
• Keep responses concise (2-3 sentences)
• Allow markdown formatting
• Include escalation path (“Would you like me to have someone call you?”)