WhatsApp Shopping Bot

WhatsApp Shopping Bot

Project Overview

AI-powered WhatsApp bot for shopping sites. Uses Rivet durable actors for per-user isolation, AgentOS for sandboxed execution, Pi Agent Core for LLM orchestration, and @shopify/dev-mcp for e-commerce integration.

Each user automatically gets a dedicated actor on first message — no registration, no signup. The actor is durable, sleeps when idle, and survives restarts.

High-Level System View

graph TB
    subgraph "User Layer"
        USER[WhatsApp User] --> WA[WhatsApp Cloud API]
    end

    subgraph "Gateway Layer"
        WA -->|webhook| GW[FastAPI<br/>Thin Router]
    end

    subgraph "Actor Layer (Rivet)"
        GW -->|get_actor| R[Rivet Runtime]
        R --> A1["Actor A<br/>(AgentOS + Pi Agent)"]
        R --> A2["Actor B<br/>(AgentOS + Pi Agent)"]
        R --> AN["Actor N<br/>(AgentOS + Pi Agent)"]
    end

    subgraph "Service Layer"
        A1 --> MCP["@shopify/dev-mcp"]
        A1 --> LLM[LLM Provider]
        A1 --> STATE[(Rivet Durable State)]
    end

    MCP --> SHOP[Shopify Storefront]
    A1 -->|reply| WA
    WA --> USER

    style R fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px
    style A1 fill:#c8e6c9,stroke:#388e3c
    style A2 fill:#c8e6c9,stroke:#388e3c
    style AN fill:#c8e6c9,stroke:#388e3c

Key Design Choices

Current Phase

Stage 1: Shopify integration

Core Requirements

• Not a general chatbot — executes tools to send WhatsApp messages
• Isolates actors per user (Rivet durable actors)
• Natural language product discovery (via MCP tools)
• Runs inside AgentOS V8 isolates
• Uses WhatsApp Cloud API for messaging
• Defense in depth: rate limits, injection detection, sanitization

User Journey

sequenceDiagram
    actor U as User
    participant W as WhatsApp
    participant G as Gateway
    participant R as Rivet
    participant A as Actor
    participant P as Pi Agent
    participant S as Shopify

    U->>W: "Show me laptops under $1000"
    W->>G: Webhook POST
    G-->>W: 200 OK (instant)
    G->>R: get_actor(user_id)

    alt First message
        R->>A: Create + on_init()
    end

    R-->>G: actor
    G->>A: on_message(text)
    A->>P: agent.prompt(text)
    P->>S: search_shop_catalog(query)
    S-->>P: 5 products
    P-->>A: Response
    A-->>G: Response
    G->>W: Send reply
    W-->>U: Display products

    U->>W: "Tell me more about the Dell XPS"
    W->>G: Webhook POST
    G-->>W: 200 OK
    G->>R: get_actor(user_id)
    R-->>G: actor (same one)
    G->>A: on_message(text)
    Note over A: Has full conversation history
    A->>S: get_product_details(handle)
    S-->>A: Full specs
    A-->>G: Response
    G->>W: Send reply
    W-->>U: Display specs

    Note over A: Sleeps after 5min idle

Key Decisions Log

Architecture Documents

Next Steps

1. ✅ Shopify integration research
2. ✅ Integration approach selected (Official MCP)
3. ✅ Architecture designed (Rivet actors)
4. 🔲 Clone + study Shopify/shop-chat-agent reference
5. 🔲 Set up Shopify Partner account + dev store
6. 🔲 Set up WhatsApp Business API access
7. 🔲 Build minimal actor with one MCP tool
8. 🔲 Add security layers (rate limit, injection)
9. 🔲 Integrate with WhatsApp webhook
10. 🔲 End-to-end prototype