eChatr Documentation
Complete guide to integrating AI-powered shopping assistance into your e-commerce platform.
📚 What you'll learn
- • How to install and configure the eChatr widget
- • Managing products and API keys via the Customer Portal
- • Implementing callback functions for cart and navigation
- • Setting up webhooks for purchase and analytics events
- • Best practices for optimal customer experience
Quick Start
Get your AI shopping assistant running in under 5 minutes.
Sign Up & Get Your API Key
Visit the Customer Portal to create your account and receive your unique API key.
Upload Your Products
Upload your product catalog via the portal or API. AI embeddings are generated automatically.
curl -X POST 'https://api.echatr.com/api/v1/products/bulk' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@products.csv'Add Widget to Your Site
Add these two lines to your website's HTML, just before the closing </body> tag:
<script src="https://cdn.jsdelivr.net/npm/@ecommerce-chat/shopping-assistant@1"></script>
<script>
ShoppingAssistant.init({
apiKey: "YOUR_API_KEY",
apiUrl: "https://api.echatr.com/api/v1"
});
</script>Installation
Via CDN (Recommended)
The fastest way to get started. No build tools required.
<!-- Add before closing </body> tag -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ecommerce-chat/shopping-assistant@1/dist/widget.css">
<script src="https://cdn.jsdelivr.net/npm/@ecommerce-chat/shopping-assistant@1/dist/widget.iife.js"></script>Via NPM
For projects using a build system like Webpack or Vite.
npm install @ecommerce-chat/shopping-assistantimport '@ecommerce-chat/shopping-assistant/dist/widget.css';
import { ShoppingAssistant } from '@ecommerce-chat/shopping-assistant';
ShoppingAssistant.init({ apiKey: 'YOUR_API_KEY' });Configuration
Customize the widget's appearance and behavior to match your brand.
Basic Configuration
ShoppingAssistant.init({
apiKey: 'YOUR_API_KEY', // Required: Your unique API key
apiUrl: 'https://api.echatr.com/api/v1', // Optional: API endpoint
position: 'bottom-right', // Optional: 'bottom-right' | 'bottom-left'
primaryColor: '#667eea', // Optional: Brand color for widget
theme: 'light', // Optional: 'light' | 'dark'
});| Parameter | Type | Default | Description |
|---|---|---|---|
| apiKey | string | - | Your unique API key from the portal |
| apiUrl | string | api.echatr.com/api/v1 | Backend API endpoint |
| position | string | 'bottom-right' | Widget position on screen |
| primaryColor | string | '#0066cc' | Primary brand color (hex) |
| theme | string | 'light' | Color theme |
API Reference
Authentication
All API requests require authentication using your API key in the request header.
x-api-key: YOUR_API_KEYUpload Products (Bulk)
/api/v1/products/bulkUpload multiple products via CSV or JSON file.
Request
curl -X POST 'https://api.echatr.com/api/v1/products/bulk' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@products.csv'CSV Format
id,name,description,category,price,image_url,tags
PROD-001,Blue Pen,Premium gel ink pen,Pens,2.99,https://example.com/pen.jpg,"blue,pen,office"
PROD-002,Notebook,Ruled notebook,Notebooks,12.99,https://example.com/notebook.jpg,"notebook,ruled"Get Statistics
/api/v1/customer/statsRetrieve customer statistics including sessions and messages.
Response
{
"customer_id": "cust_123",
"customer_name": "Acme Corp",
"total_products": 150,
"total_sessions": 1247,
"active_sessions": 12,
"total_messages": 8934,
"last_activity": "2025-01-15T14:30:00Z"
}Customer Portal
Manage your AI shopping assistant through the intuitive web portal at portal.echatr.com
📊 Dashboard
- • View total products and chat sessions
- • Monitor active sessions in real-time
- • Track message volume
- • Product embedding progress
- • Top product categories
🔑 API Keys
- • View your current API key
- • Copy key to clipboard
- • Regenerate key instantly
- • View key creation date
- • Integration instructions
🔧 Integration Settings
- • Enable/disable cart features
- • Configure product navigation
- • Toggle product details view
- • Coupon application settings
- • Live code examples
🔔 Webhooks
- • Purchase complete notifications
- • Cart abandonment alerts
- • Product view tracking
- • Custom endpoint URLs
- • Event payload examples
Product Management
🤖 AI Embeddings
When you upload products, AI embeddings are automatically generated. This enables semantic search so customers can ask questions like "find me blue office supplies" instead of exact product name searches.
Required Product Fields
| Field | Required | Description |
|---|---|---|
| id | Yes | Unique product identifier (SKU) |
| name | Yes | Product display name |
| description | Yes | Detailed product description (used for AI search) |
| category | Yes | Product category |
| price | Yes | Product price (decimal) |
| image_url | Optional | Product image URL |
| tags | Optional | Comma-separated tags for better search |
Integration Guide
Connect the AI assistant to your shopping cart and product pages using callback functions.
Full Integration Example
ShoppingAssistant.init({
apiKey: 'YOUR_API_KEY',
apiUrl: 'https://api.echatr.com/api/v1',
position: 'bottom-right',
primaryColor: '#667eea',
// Get current cart state
getCart: function() {
return {
items: myCart.getItems(),
total: myCart.getTotal()
};
},
// Add product to cart
onAddToCart: async function(productId, quantity) {
await myCart.addItem(productId, quantity);
return { success: true };
},
// Navigate to product page
onNavigateToProduct: function(productId) {
window.location.href = `/products/${productId}`;
},
// Show product details
onViewProductDetails: function(productId) {
myModal.showProduct(productId);
},
// Remove from cart
onRemoveFromCart: async function(productId) {
await myCart.removeItem(productId);
return { success: true };
}
});Callback Functions
getCart()
Called when the AI needs to know the current cart state.
getCart: function() {
return {
items: [
{ productId: 'PROD-1', quantity: 2, name: 'Blue Pen', price: 2.99 }
],
total: 5.98
};
}onAddToCart(productId, quantity)
Called when the AI assistant adds a product to the cart.
onAddToCart: async function(productId, quantity) {
// Your cart logic here
await myShoppingCart.add(productId, quantity);
// Return success status
return { success: true };
}onNavigateToProduct(productId)
Called when the user wants to view a product page.
onNavigateToProduct: function(productId) {
// Navigate to product page
window.location.href = '/products/' + productId;
// Or scroll to product on same page
document.getElementById('product-' + productId)
.scrollIntoView({ behavior: 'smooth' });
}onViewProductDetails(productId)
Called when the user requests detailed product information.
onViewProductDetails: function(productId) {
// Show product in modal
myProductModal.show(productId);
// Or open quick view panel
quickViewPanel.display(productId);
}onRemoveFromCart(productId)
Called when the AI removes a product from the cart.
onRemoveFromCart: async function(productId) {
await myShoppingCart.remove(productId);
return { success: true };
}Webhooks
Configure webhooks in the Customer Portal to receive real-time notifications about customer actions.
Purchase Complete
Triggered when a customer completes a purchase after using the AI assistant.
POST https://your-domain.com/webhooks/purchase-complete
{
"event": "purchase_complete",
"session_id": "sess_abc123",
"customer_id": "cust_456",
"total_amount": 49.99,
"items": [
{ "product_id": "PROD-1", "quantity": 2, "price": 24.99 }
],
"timestamp": "2025-01-15T14:30:00Z"
}Cart Abandonment
Triggered when a customer leaves after the AI added items to their cart.
POST https://your-domain.com/webhooks/cart-abandonment
{
"event": "cart_abandonment",
"session_id": "sess_abc123",
"cart_value": 29.99,
"items": [
{ "product_id": "PROD-2", "quantity": 1 }
],
"timestamp": "2025-01-15T14:35:00Z"
}Product View
Triggered when a customer views a product recommended by the AI.
POST https://your-domain.com/webhooks/product-view
{
"event": "product_view",
"session_id": "sess_abc123",
"product_id": "PROD-3",
"timestamp": "2025-01-15T14:32:00Z"
}Best Practices
✅ Product Descriptions
Write detailed, natural product descriptions. The AI uses these for semantic search, so "Premium gel ink pen with comfortable rubber grip" works better than just "Pen".
✅ Regular Updates
Keep your product catalog synchronized. Update prices, availability, and descriptions regularly so the AI provides accurate information.
✅ Error Handling
Implement proper error handling in your callback functions. Return { success: false } when operations fail so users get appropriate feedback.
✅ Mobile Optimization
The widget is fully responsive on mobile. Test your callback functions on mobile devices to ensure smooth navigation and cart operations.
✅ Monitor Performance
Use the Customer Portal dashboard to track sessions, messages, and customer engagement. Adjust your product descriptions based on common queries.
Troubleshooting
Widget not appearing
- • Check that the script and CSS are loaded (inspect Network tab)
- • Verify API key is correct
- • Ensure no JavaScript errors in console
- • Confirm the widget isn't hidden by CSS z-index
Products not found by AI
- • Check Product Stats in the portal - are embeddings generated?
- • Ensure product descriptions are detailed and descriptive
- • Verify products were uploaded successfully
- • Wait a few minutes for embedding generation after upload
Cart functions not working
- • Verify callback functions are implemented correctly
- • Check browser console for JavaScript errors
- • Ensure callbacks return the expected format
- • Enable cart features in Integration Settings
401 Authentication errors
- • Verify your API key is correct
- • Check that the key hasn't been regenerated
- • Ensure the key is being sent in the x-api-key header
- • Contact support if the issue persists