WhatsApp AI Shopify Bot

Overview

WhatsApp AI Shopify Bot connects Claude directly to a live Shopify store over WhatsApp. Customers can ask product questions, check order status, get a secure checkout link, and get handed off to a human, all inside a WhatsApp conversation. It is built on the Meta WhatsApp Cloud API and Shopify's Admin GraphQL API, with Claude driving the conversation through typed tool calls rather than free-text guesses.

Problem

The PRD frames the need directly: customers, especially in the MENA region, increasingly expect to reach a retailer on WhatsApp rather than email or a web form, and existing support channels do not scale. Shopify holds the catalog, inventory, and order data, but WhatsApp had no connection to it. The goal was a bot that could deflect routine support questions (order status, product lookup) and support an end-to-end conversational path from product discovery to a checkout link, while cleanly escalating anything it could not resolve to a human.

Approach

The product decisions were locked early in the PRD: build directly on the Meta WhatsApp Cloud API (cheapest, full control, free test number for local development) rather than a BSP; auto-detect the customer's language instead of asking them to pick one; keep payment entirely on Shopify's hosted checkout instead of collecting any payment data in chat; and build a pluggable human handoff (flag and notify staff) rather than a hard dependency on a specific helpdesk. The plan explicitly sequenced local development first (test WhatsApp number, mock or live Shopify data, Claude wired in) before any production number or Meta Business verification.

Architecture

• Node.js + TypeScript, Express webhook server (src/index.ts) that acknowledges Meta's webhook immediately (HTTP 200) then processes the message asynchronously
• src/claude.ts runs the agent loop: pushes the user turn onto conversation history, calls Claude with the tool list and a cached system prompt, executes any requested tools, and loops (capped at 6 steps) until Claude returns a final text reply
• src/tools.ts defines the four tools Claude can call (search_products, get_order, create_checkout, handoff_to_human) and dispatches them to the Shopify layer
• src/shopify.ts talks to Shopify's Admin GraphQL API for product search, order lookup by name, and building a cart permalink for checkout; falls back to mock data automatically when no SHOPIFY_ADMIN_TOKEN is set, so the conversation flow can be tested with only an Anthropic key
• src/whatsapp.ts sends outbound text via the Cloud API and marks inbound messages read
• src/state.ts holds per-customer conversation history and opt-out state in memory (explicitly a local-dev placeholder), and tracks the 24-hour service window
• src/chat-cli.ts is a terminal harness that exercises the reply generator directly, without needing WhatsApp credentials at all

Tech stack

• Node.js, TypeScript, Express
• @anthropic-ai/sdk (Claude API)
• Meta WhatsApp Cloud API (Graph API)
• Shopify Admin GraphQL API
• tsx for local dev, dotenv for config

AI work

• Agent loop with Claude tool-calling: Claude decides when to search products, look up an order, build a checkout link, or hand off, instead of the code branching on intent
• Prompt caching (ephemeral cache_control) on the system prompt so repeat turns reuse the cached prefix
• Model routing is Haiku-first with a separate escalation model configured via env for harder cases
• System prompt enforces language mirroring (reply in whatever language the customer used), short WhatsApp-style replies, and a hard rule to never invent order details, prices, or stock, always call a tool or say so honestly

Engineering highlights

• WhatsApp compliance is treated as a first-class requirement: the 24-hour service window is enforced in state.ts and checked before every outbound send, and opt-out keywords across languages immediately stop messaging
• Checkout stays on Shopify's hosted page; the bot never collects card numbers or passwords, it only ever returns a cart permalink
• Webhook handler acknowledges Meta with a 200 before processing, avoiding Meta's retry-on-non-200 behavior
• Mock-mode fallback in shopify.ts lets the full conversation and tool-calling flow be tested end-to-end before any Shopify credentials exist
• Human handoff is pluggable by design: the handoff tool logs and flags a reason today, leaving room to wire in staff notification (WhatsApp, email, or a dashboard) later without changing the agent loop
• WHATSAPP_COMPLIANCE.md documents the Meta policy rules the bot must obey (service window, opt-in/opt-out, template categorization, prohibited content, webhook signature verification) and maps each to where it is enforced in code