WhatsApp AI Agent Prompt

Customer WhatsApp message → Meta POST /api/webhook → Store message in MongoDB → If conversation.mode ==="agent": run tool-using AI agent → Send reply via Meta Graph API → Store assistant message (source: "ai" or "human") → Dashboard polls REST API every ~2.5s

MongoDB collections (Mongoose)

conversations

• phone (unique), name, mode ("agent" | "human"),timestamps

messages

• conversation_id, role (user | assistant), content
• whatsapp_msg_id — only on inbound user messages for dedupe; sparse unique index (do NOT set null on assistant rows)
• source — assistant only: "ai" | "human"
• Index: { conversation_id, created_at }

orders

• order_ref (unique, e.g. MS-YYYYMMDD-XXXX)
• conversation_id, customer_phone, customer_name
• items[]: product_id, product_name, quantity, unit_price_ghs
• total_ghs, delivery_address, payment_method
• status: pending | confirmed | shipped | delivered | cancelled

Sample product catalog (in-memory src/lib/products.ts)

At least 10–12 products with IDs like MS-IP15-128, categories: phones, laptops, tablets, audio, tvs, gaming, accessories.

Example products:

• iPhone 15 128GB — GHS 8,999
• Samsung Galaxy A55 — GHS 4,299
• Redmi Note 13 — GHS 1,899
• MacBook Air M2 — GHS 12,499
• HP 15 Laptop — GHS 5,499
• iPad 10.9 — GHS 3,899
• Sony WH-1000XM5 — GHS 3,299
• JBL Flip 6 — GHS 899
• Samsung 55" 4K TV — GHS 6,499
• PlayStation 5 — out of stock (agent suggests alternatives)
• Anker 20K power bank — GHS 449
• Dell 27" monitor — GHS 1,899

Helpers: searchProducts(query?, category?), getProductById(id), formatPriceGhs(n), PRODUCT_CATEGORIES.

AI agent (tool-calling)

Use OpenAI chat completions with tools and a multi-step loop (max ~8 steps).

System prompt rules

• You are {AGENT_NAME} for {BUSINESS_NAME} — electronics in Ghana, GHS
• Shopping flow: Discover → Recommend (max 3) → Detail → Order (one question per message) → Confirm → Track
• Short WhatsApp-friendly messages; never invent catalog data
• Warranty: 1 year on phones/laptops; no card numbers in chat; Mobile Money after order
• Bulk/corporate → human handoff

Tools (implement as functions backed by catalog + MongoDB)

On handoff: update conversations.mode to "human" in webhook after agent run.

Pass conversationId, phone, name into the agent for personalized greetings and order linking.

API routes

Webhook POST logic

1. Normalize webhook body (Meta may send { field, value } or nested entry/changes)
2. Ignore non-message events (status-only updates)
3. Find/create conversation by sender phone
4. Skip if whatsapp_msg_id already exists
5. If mode ==="human": store only, no AI
6. If mode ==="agent": load last N messages → runWhatsAppAgent → send reply → save assistant message before or after send (save even if send fails so dashboard shows reply)
7. Always return 200 quickly

WhatsApp send

Critical: WHATSAPP_PHONE_NUMBER_ID must match the number that receives webhooks.

Dashboard (/ client component)

WhatsApp Web–style layout:

• Left sidebar: Masyn-Shop branding, search, conversation list (name/phone, last message, time, AI/You badge)
• Agent card at bottom: agent name, tagline "Electronics · Phones · Laptops · TVs", capabilities list
• Right panel: chat header with mode toggle (AI Agent / Human),message bubbles (user left, assistant right; distinguish AI vs human replies),typing indicator when last message is from user in agent mode
• Compose bar: send manual messages in both modes
• Poll /api/conversations and messages every ~2.5s

Empty state copy: electronics sales on WhatsApp.

File structure (target)

Meta setup (document in README)

1. Create Meta Business app → WhatsApp product
2. System User → permanent token with whatsapp_business_messaging
3. Copy Phone Number ID from API Setup
4. ngrok http 3000 → webhook URL https://xxx.ngrok-free.app/api/webhook
5. Verify token + subscribe to messages
6. Add test recipient phone if using Meta test number

Edge cases to handle

• Duplicate webhook deliveries → unique sparse index on whatsapp_msg_id
• Do not store whatsapp_msg_id: null on multiple assistant rows (Mongo duplicate key)
• AI rate limits → friendly fallback message
• Out-of-stock products → suggest alternatives via search
• request_human_handoff → set mode human, do not auto-reply until staff toggles back
• Support Meta payload variations (from vs from_user_id, etc.)

Acceptance criteria

1. User texts WhatsApp → receives AI reply within seconds
2. User can browse phones, get product details, place order, receive order reference
3. User can ask order status by reference
4. Dashboard shows all chats; staff can toggle AI/Human and send manual replies
5. Human mode stops AI auto-replies
6. npm run build passes with no TypeScript errors

Build the complete app with README setup guide and .env.example. Use Masyn-Shop branding throughout.

Tips for the person using the prompt

1. Point them at your repo as a reference implementation if they have access: claude_code_prompt.md is the older generic version; the prompt above reflects the e-commerce version.
2. Tell them to set WHATSAPP_PHONE_NUMBER_ID to the ID from webhook logs if sends fail.
3. For another brand (not Masyn-Shop),replace business name, catalog, currency, and env vars — keep the same architecture.

I'm in Ask mode, so I can't create a file in your repo. If you want this saved as BUILD_PROMPT.md, switch to Agent mode and ask.