Shopify

Important: The Shopify integration allows you to embed an AI Employee on your Shopify store to handle customer inquiries, provide product recommendations, assist with orders, and improve the shopping experience.

​

🔢 Table of Contents

1. Overview
2. Prerequisites
3. Installation Steps
4. Configuring Your AI Employee
5. Customization Options
6. Common Use Cases
7. Troubleshooting
8. Best Practices

​

1. Overview

​

What This Integration Does

• Ask questions about products
• Get sizing and specification information
• Track order status
• Request returns or exchanges
• Get shopping recommendations
• Receive instant support 24/7

​

Key Features

• Easy Installation: Add with a simple script tag
• Customizable Widget: Match your store’s branding
• Mobile Responsive: Works on all devices
• Product Knowledge: Connect datastores with product info
• Order Integration: Can integrate with Shopify APIs (via HTTP Tool)
• Lead Capture: Collect customer information
• Multi-language: Support multiple languages

​

Technical Requirements

• Active Shopify store (any plan)
• Access to theme code editor
• ZappWay AI Employee created and configured
• Basic familiarity with HTML (helpful but not required)

​

2. Prerequisites

​

Before You Begin

1. Go to AI Employees
2. Click “Create AI Employee”
3. Configure settings and instructions
4. See AI Employee Guide for details

• Product descriptions
• Sizing guides
• Shipping policies
• Return policies
• FAQs

1. Open AI Employee settings
2. Go to Tools tab
3. Add Datastore Tool
4. Select your product datastore
5. Save configuration

1. Open your AI Employee in the dashboard
2. Copy the Agent ID from the URL or settings
3. Keep this handy for installation

​

3. Installation Steps

​

Step 1: Access Theme Code Editor

1. Log in to your Shopify Admin dashboard
2. Navigate to Online Store → Themes
3. Find your current active theme
4. Click Actions → Edit code

​

Step 2: Copy Integration Script

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'YOUR_AGENT_ID',
  })

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'clf1a2b3c4d5e6f7g8h9',
  })

​

Step 3: Insert Script in Theme

1. In the theme code editor, locate the theme.liquid file in the Layout folder
2. Find the closing </head> tag (usually near the top of the file)
3. Paste the script above the </head> tag
4. Click Save in the top-right corner

​

Step 4: Verify Installation

1. Visit your Shopify store in a new browser tab
2. Look for the chat bubble in the bottom-right corner
3. Click the bubble to open the chat widget
4. Send a test message to your AI Employee
5. Verify responses are working correctly

​

4. Configuring Your AI Employee

​

Recommended Instructions for Shopify

You are a helpful customer service assistant for [Your Store Name].
Your goal is to help customers find products, answer questions, and provide excellent shopping support.

PERSONALITY:
- Friendly, enthusiastic, and helpful
- Product-focused and solution-oriented
- Patient with customer questions

CAPABILITIES:
- Answer product questions (features, sizing, materials)
- Provide shopping recommendations
- Help with order tracking
- Explain shipping and return policies
- Assist with account issues
- Offer promotions and discounts when available

PROCESS:
1. Greet customers warmly
2. Understand what they're looking for
3. Search product knowledge base
4. Provide helpful, accurate information
5. Suggest related products when appropriate
6. Ask if they need anything else

PRODUCT RECOMMENDATIONS:
When recommending products:
- Ask about customer preferences and needs
- Suggest 2-3 specific products with details
- Mention key features and benefits
- Include pricing information
- Provide direct product links when possible

WHEN TO ESCALATE:
- Order cancellations or modifications
- Payment issues
- Damaged or defective products
- Complex technical problems
- Custom or bulk orders

Always be enthusiastic about our products and help customers have a great shopping experience!

​

Connecting Product Data

1. Go to Datastores
2. Click “Create Datastore”
3. Name it “Product Catalog” or similar
4. Add datasources:
   • Product descriptions (copy from Shopify product pages)
   • Sizing guides (PDF or text)
   • Shipping policy
   • Return policy
   • FAQs

1. Open AI Employee → Tools tab
2. Add Datastore Tool
3. Select “Product Catalog” datastore
4. Save

​

Optional: Order Tracking Integration

1. Add HTTP Tool to AI Employee
2. Configure endpoint: https://your-store.myshopify.com/admin/api/2024-01/orders.json
3. Add authentication (Shopify API key)
4. Update instructions to mention order tracking capability

​

5. Customization Options

​

Widget Appearance

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'YOUR_AGENT_ID',
    
    // Bubble customization
    theme: {
      primaryColor: '#4F46E5',      // Your brand color
      position: 'right',             // 'right' or 'left'
      bottom: 20,                    // Distance from bottom (px)
      right: 20,                     // Distance from side (px)
    },
    
    // Widget customization
    window: {
      title: 'Shopping Assistant',  // Chat window title
      welcomeMessage: 'Hi! How can I help you find the perfect product today?',
    },
  })

​

Show on Specific Pages

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  // Only show on product pages
  if (window.location.pathname.includes('/products/')) {
    Chatbox.initBubble({
      agentId: 'YOUR_AGENT_ID',
    });
  }

• Product pages: /products/
• Collection pages: /collections/
• Cart page: /cart
• Checkout: /checkout
• All pages: (no condition)

​

Hide on Mobile

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  // Only show on desktop
  if (window.innerWidth > 768) {
    Chatbox.initBubble({
      agentId: 'YOUR_AGENT_ID',
    });
  }

​

6. Common Use Cases

​

Product Recommendations

I'd love to help you find the perfect gift! 
To give you the best recommendations, could you tell me:

1. What are her interests or hobbies?
2. What's your budget range?
3. Are you looking for something specific (jewelry, clothing, accessories)?

• Product datastore with detailed descriptions
• Instructions to ask qualifying questions
• Knowledge of product categories

​

Order Tracking

I'll look up your order for you!
[Uses HTTP Tool to query Shopify API]

Your order #12345 was shipped on January 10th via USPS.
Tracking number: 9400111899223344556677
Expected delivery: January 15th

You can track it here: [tracking link]

• HTTP Tool configured with Shopify API
• API credentials with order read permission
• Instructions for handling order queries

​

Sizing Assistance

Great choice! To help you find the perfect fit, 
could you share your usual shirt size (S, M, L, XL)?

Our Classic T-Shirt runs true to size. Here's our sizing guide:
- Small: Chest 34-36", Length 28"
- Medium: Chest 38-40", Length 29"
- Large: Chest 42-44", Length 30"
- X-Large: Chest 46-48", Length 31"

Would you like me to recommend a size based on your measurements?

• Sizing guide uploaded to datastore
• Instructions to ask clarifying questions
• Product-specific sizing information

​

Returns and Exchanges

I'm sorry to hear that! I can help you with the return process.

Our return policy:
- 30-day return window from delivery date
- Items must be unworn and in original packaging
- Free return shipping

To start your return:
1. What's your order number?
2. Which item(s) would you like to return?
3. Reason for return? (helps us improve)

I'll generate a prepaid return label for you!

• Return policy in datastore
• Form Tool for collecting return details
• Instructions for return process

​

Abandoned Cart Recovery

Hi! I noticed you have some items in your cart. 
Is there anything I can help you with to complete your purchase?

- Questions about the products?
- Need help with sizing?
- Looking for a promo code?
- Issues at checkout?

I'm here to help! 🛍️

• Proactive message trigger (custom implementation)
• Instructions for cart recovery
• Knowledge of current promotions

​

7. Troubleshooting

​

Chat Bubble Not Appearing

1. Verify Agent ID is correct:
   • Check for typos in the script
   • Ensure Agent ID matches your dashboard
2. Check script placement:
   • Must be before </head> tag
   • Not inside any other script tags
   • Saved correctly in theme.liquid
3. Clear browser cache:
   • Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
   • Try incognito/private browsing mode
4. Check browser console for errors:
   • Open DevTools (F12)
   • Go to Console tab
   • Look for error messages
   • Common error: “Failed to load module”
5. Verify theme file:
   • Ensure you edited the active theme
   • Check that changes were saved
   • Preview theme before publishing

​

AI Not Responding

1. Test AI Employee directly:
   • Go to AI Employee in ZappWay dashboard
   • Use test chat interface
   • If it works there, issue is with integration
2. Check AI Employee status:
   • Ensure AI Employee is not disabled
   • Verify instructions are configured
   • Check that datastores are connected
3. Review rate limits:
   • Check if rate limits are exceeded
   • See Rate Limit Guide
4. Check datastore status:
   • Ensure datastores are processed (not “Processing”)
   • Verify content is indexed

​

Widget Styling Issues

1. Customize colors:

   theme: {
     primaryColor: '#YOUR_BRAND_COLOR',
   }

2. Adjust position:

   theme: {
     position: 'left',  // or 'right'
     bottom: 30,
     left: 30,
   }

3. Change widget size:

   window: {
     height: 700,
     width: 450,
   }

​

Script Loading Slowly

• CDN loading delay (rare)
• Slow network connection
• Other scripts blocking

1. Use async loading:

   
     import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';
     Chatbox.initBubble({ agentId: 'YOUR_AGENT_ID' });
   

2. Self-host the script (advanced):
   • Download library from CDN
   • Upload to Shopify theme assets
   • Update script src to point to local file

​

8. Best Practices

​

Content Strategy

• Update datastore when products change
• Include seasonal product info
• Add new products to datastore immediately
• Remove discontinued products

• Outdated pricing information
• Products no longer in stock
• Inconsistent product descriptions

• Detailed product descriptions
• Materials and specifications
• Care instructions
• Sizing charts (with measurements)
• Color options and variations
• Product use cases and benefits
• Customer reviews and testimonials
• Comparison with similar products

​

AI Employee Configuration

If customers seem unsure, offer to:
- Show bestsellers or new arrivals
- Suggest products based on season
- Offer category-specific recommendations
- Mention current sales or promotions

When discussing pricing:
- Mention current prices accurately
- Highlight any active discounts
- Compare value vs similar products
- Explain what's included (free shipping, warranty, etc.)
- Offer payment plan options if available

For each recommended product, provide:
- Product name
- Key features (2-3 bullet points)
- Price
- Direct link: [View Product](https://your-store.com/products/product-name)

​

Customer Experience

• AI should respond within 2-3 seconds
• If processing longer (e.g., API calls), show typing indicator
• Provide status updates for complex queries

Good afternoon. I'm delighted to assist you in finding 
the perfect piece from our collection. How may I be of service today?

Hey there! 👋 Ready to find something awesome? 
I'm here to help you discover your next favorite thing!

Welcome! I can help you find the right product based on your 
specific requirements. What are you looking for today?

​

Analytics and Improvement

• Most common customer questions
• Products frequently asked about
• Drop-off points in conversations
• Questions AI couldn’t answer

• Check conversation logs
• Identify knowledge gaps
• Update datastore with missing info

• Analyze top product inquiries
• Update AI instructions based on trends
• Add new FAQs to datastore

• Major knowledge base overhaul
• Review and refine AI personality
• A/B test different approaches

​

Security

• Don’t store payment information in chat
• Don’t ask for sensitive data (passwords, full card numbers)
• Comply with privacy regulations (GDPR, CCPA)
• Use secure connections (HTTPS) only

​

📞 Support & Resources

​

Getting Help

• Help button in ZappWay dashboard
• Live chat (available on Pro+ plans)

• Shopify Theme Documentation
• Liquid Template Language

• AI Employee Guide
• Datastore Setup
• Widget Customization

​

Feedback

• Email: [email protected]
• Include:
  • Shopify store URL
  • Agent ID
  • Screenshots of issue
  • Browser console errors (if any)

​

✅ Quick Reference

​

Installation Checklist

✓ AI Employee created and configured
✓ Product datastore created and populated
✓ Datastore connected to AI Employee
✓ Agent ID copied
✓ Script added to theme.liquid (before </head>)
✓ Theme saved
✓ Store tested in browser
✓ Chat bubble appears correctly
✓ Test conversation completed
✓ Responses are accurate

​

Script Template

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'YOUR_AGENT_ID',
    theme: {
      primaryColor: '#4F46E5',
      position: 'right',
    },
    window: {
      title: 'Shopping Assistant',
      welcomeMessage: 'Hi! How can I help you today?',
    },
  })

​

Common Customizations

theme: { position: 'left', left: 20 }

if (window.location.pathname.includes('/products/')) {
  Chatbox.initBubble({ agentId: 'YOUR_AGENT_ID' });
}

if (window.innerWidth > 768) {
  Chatbox.initBubble({ agentId: 'YOUR_AGENT_ID' });
}