Merchant Documentation
ChatCart User Manual
Everything you need to connect WhatsApp to your Shopify store, automate order messages, and let AI handle customer support.
Getting Started
What is ChatCart?
ChatCart connects your Shopify store to WhatsApp Business. When a customer places an order, abandons their cart, or messages your WhatsApp number — ChatCart handles it automatically with AI-powered responses and real-time Shopify data.
AI Chatbot
Answers customer questions about orders, products, and returns using live Shopify data.
Order Notifications
Automatic WhatsApp messages for order confirmation, shipping, and delivery.
Abandoned Cart
Recover lost sales with automated cart reminder messages at 1h, 24h, and 72h.
COD Verification
Confirm cash-on-delivery orders via WhatsApp before processing to reduce returns.
Store Widget
A WhatsApp chat button on your store pages for direct customer contact.
Analytics
Track message delivery, read rates, cart recovery revenue, and COD confirmation rates.
📦 Installation
ChatCart is installed from the Shopify App Store like any other app.
Install from Shopify App Store
Search for ChatCart in the Shopify App Store and click Add app. You'll be redirected to your Shopify admin to approve permissions.
Approve permissions
ChatCart needs access to orders, products, customers, and checkouts to send the right messages at the right time. Click Install app.
Connect WhatsApp
After install, you'll land on the setup page. Connect your WhatsApp Business account using Quick Setup (recommended) or Manual Setup.
⚡ Quick Start Checklist
Follow these steps to go live in under 10 minutes.
| Step | Action | Where |
|---|---|---|
| 1 | Connect WhatsApp via Quick Setup | App → WhatsApp Setup |
| 2 | Verify webhook in Meta Developer Console | Meta Dashboard |
| 3 | Enable message templates | App → Templates |
| 4 | Send a test message | App → WhatsApp Setup → Test |
| 5 | Install the store widget | App → Widget → Enable |
WhatsApp Setup
✨ Quick Setup (Recommended)
Quick Setup uses Meta's Embedded Signup to connect your WhatsApp Business account in one click — no copy-pasting tokens or IDs.
Go to WhatsApp Setup
In the ChatCart app, click WhatsApp Setup in the sidebar. You'll see the Quick Setup card at the top.
Click "Connect WhatsApp Business"
A Facebook popup will open. Log in with your Facebook account that has admin access to your Meta Business account.
Follow the Facebook wizard
Select or create your WhatsApp Business Account (WABA), add your business phone number, and verify it via SMS or call.
Wait for connection
ChatCart automatically saves your credentials. The setup page will refresh showing "WhatsApp Connected" with your phone number and business name.
🔧 Manual Setup
Use Manual Setup if you already have a Meta Business account and WhatsApp Business Account with credentials.
Where to find your credentials
| Field | Where to find it |
|---|---|
| Phone Number ID | Meta Dashboard → Your App → WhatsApp → API Setup → Phone Number ID |
| WABA ID | Meta Business Manager → WhatsApp Accounts → click your account → ID shown at top |
| Access Token | Meta Business Manager → System Users → Generate token (select whatsapp_business_messaging scope) |
| Webhook Verify Token | Any secret string you choose — you'll enter the same string in Meta's webhook config |
Go to Manual Setup
In the app, go to WhatsApp Setup → Use Manual Setup. Complete steps 1 and 2 (Meta Business Account setup) then move to Step 3: API Credentials.
Enter your credentials
Fill in Phone Number ID, WABA ID, Access Token, and your business phone number. Click Save credentials.
Send a test message
Enter your phone number (with country code, no +) and click Send test message. You should receive a WhatsApp message within seconds.
🔗 Webhook Configuration
The webhook allows Meta to send incoming customer messages to ChatCart so the AI bot can respond.
Webhook settings
| Setting | Value |
|---|---|
| Callback URL | https://chatcart.appaza.dev/api/whatsapp/webhook |
| Verify Token | The webhook verify token you set in Manual Setup, or your CRON_SECRET value |
| Subscribed fields | messages (required for AI chatbot to work) |
Open Meta Developer Console
Go to developers.facebook.com → your app → WhatsApp → Configuration.
Add webhook URL
Click Edit next to Webhook. Enter the Callback URL and Verify Token. Click Verify and save.
Subscribe to messages
After saving, click Manage next to Webhook fields. Find messages and click Subscribe.
Features
🤖 AI Chatbot
The AI chatbot automatically replies to customer WhatsApp messages with accurate information pulled live from your Shopify store.
How it works
Supported intents
| Customer says | Intent | What AI does |
|---|---|---|
| "Where is my order?" | ORDER_STATUS | Fetches their orders from Shopify by phone number, reports status + tracking |
| "Do you have blue shirts?" | PRODUCT_QUERY | Fetches live product catalog with prices and stock status |
| "What would you recommend?" | RECOMMENDATION | Shows available products and suggests based on context |
| "I want to return my order" | RETURN_REFUND | Looks up customer orders, guides through return process |
| "Hi / Hello" | GREETING | Sends a welcome message instantly (no AI needed) |
Conversation memory
ChatCart remembers the last 10 messages per customer session, so the AI understands context across a conversation (e.g., follow-up questions about the same order).
📋 Message Templates
Templates are pre-approved WhatsApp messages sent automatically when Shopify events occur. They must be approved by Meta before they can be used.
Default templates included
| Template | Trigger | Status |
|---|---|---|
| Order confirmation | Order placed | Auto-approved |
| Order shipped | Fulfillment created | Auto-approved |
| Order delivered | Fulfillment delivered | Auto-approved |
| Order cancelled | Order cancelled | Auto-approved |
| Abandoned cart – 1h | Cart abandoned 1 hour ago | Pending approval |
| Abandoned cart – 24h | Cart abandoned 24 hours ago | Pending approval |
| Abandoned cart – 72h | Cart abandoned 72 hours ago | Pending approval |
| COD verification | Cash-on-delivery order placed | Pending approval |
| Welcome message | First contact from customer | Pending approval |
Editing a template
Go to Templates page
In the app sidebar click Templates. You'll see all templates with their current status.
Click Edit on a template
You can edit the message body text. Use {{variable_name}} placeholders — for example {{customer_name}} or {{order_number}}.
Enable or disable
Toggle a template off to stop sending that message type without deleting it.
🛒 Abandoned Cart Recovery
When a customer adds items to their cart but doesn't check out, ChatCart sends automatic reminders at three intervals.
| Time after abandonment | Template | Includes |
|---|---|---|
| 1 hour | abandoned_cart_1h | Customer name, recovery link |
| 24 hours | abandoned_cart_24h | Customer name, 10% discount code, recovery link |
| 72 hours | abandoned_cart_72h | Customer name, 15% discount code, recovery link (last chance) |
Monitoring recovery
Go to Analytics → Abandoned Carts to see how many carts were recovered and the total recovery revenue for the period.
💵 COD Verification
For cash-on-delivery orders, ChatCart sends a WhatsApp message with confirm/cancel buttons before processing the order. This reduces failed deliveries and unnecessary shipping costs.
How it works
- Customer places a COD order on your Shopify store
- ChatCart detects the payment gateway contains "cash"
- A WhatsApp interactive message is sent with Confirm / Cancel buttons
- Customer taps Confirm → order is processed normally
- Customer taps Cancel → order is cancelled, analytics updated
🪄 WhatsApp Widget
The widget adds a WhatsApp chat button to your store so customers can contact you directly.
Widget settings
| Setting | Description |
|---|---|
| Position | Bottom-right or bottom-left corner of the page |
| Button color | Default WhatsApp green — customizable |
| Pre-filled message | Message pre-typed when customer opens WhatsApp |
| Show on pages | Control which page types show the widget (product, cart, home, collection) |
| Welcome bubble | A pop-up text above the button after a delay |
| Product button | An "Order via WhatsApp" button on product pages |
| Delay | Seconds before the widget appears after page load |
Enabling the widget
Go to Widget in the sidebar, toggle Enable widget on, configure your settings, and click Save. The widget appears on your live store immediately.
Management
📊 Analytics
The Analytics page shows a 30-day summary of your WhatsApp performance.
| Metric | Description |
|---|---|
| Messages Sent | Total WhatsApp messages dispatched |
| Delivered | Messages confirmed delivered to customer's device |
| Read Rate | % of messages opened and read by the customer |
| Carts Recovered | Abandoned carts where customer completed checkout after receiving a reminder |
| Recovery Revenue | Total order value from recovered carts |
| COD Confirmed | COD orders confirmed via WhatsApp |
| COD Rejected | COD orders cancelled by customer |
⚙️ Settings
Business hours
Set the hours during which automated messages are sent. Messages triggered outside these hours are queued or skipped depending on your Fallback behavior setting.
Default language
Sets the language preference passed to the AI chatbot. The AI will reply in this language when possible.
Timezone
Used for business hours calculations. Set this to your store's local timezone.
Fallback behavior
| Option | What happens outside business hours |
|---|---|
log_only | Message is logged but not sent |
send_anyway | Message is sent regardless of hours |
queue | Message is queued to send when hours resume |
💎 Plans & Limits
| Plan | Monthly messages |
|---|---|
| Free | 50 messages |
| Starter | 500 messages |
| Growth | 2,000 messages |
| Pro | 10,000 messages |
To upgrade your plan, go to Settings → Plan and select the plan you need.
Help
❓ Frequently Asked Questions
messages field — go to Meta Developer Console → WhatsApp → Configuration and subscribe. (2) Your WhatsApp account is a test number — test numbers cannot receive real messages from customers. (3) The AI provider API key is not set in your environment variables.
8801712345678. Make sure your customers enter their phone number in this format at checkout.
OPENROUTER_MODEL env var — use meta-llama/llama-3.3-70b-instruct:free), the API key is invalid, or the model hit its rate limit. Check your Coolify logs for [AI bot error] entries.
🛠️ Troubleshooting
Webhook verification fails
CRON_SECRET environment variable.
Messages not sending — "WhatsApp not configured"
The shop has no active WhatsApp configuration. Go to WhatsApp Setup and complete the connection. Make sure the setup shows "WhatsApp Connected".
Phone registration failed
Error code 133005 means a PIN is already set — this is normal and harmless. Any other phone registration error means the phone number ID or access token is wrong.
Token expired
User access tokens expire. For production, always use a System User token from Meta Business Manager which does not expire. Go to Manual Setup → Update Credentials to enter a new token.
Reading Coolify logs
Open your Coolify dashboard → ChatCart service → Logs. Key log lines to look for:
# Webhook receiving messages ✅
POST /api/whatsapp/webhook 200
# AI context fetching ✅
[context-fetcher] intent=PRODUCT_QUERY shop=yourstore.myshopify.com
# AI error ❌
[AI bot error]: OpenRouter error 400: ...
# No session found ❌
[context-fetcher] No Shopify session found for yourstore.myshopify.comStill stuck?
Email support at support@chatcart.app with your shop domain and a screenshot of the Coolify logs showing the error.