---
title: 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

```mermaid
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

| Choice | Decision | Why |
|--------|----------|-----|
| Agent management | Rivet actors (not in-process pool) | Durability, distribution, free concurrency |
| Agent runtime | Pi Agent Core (Python) | Mature tool calling, streaming, multi-LLM |
| Sandbox | AgentOS (V8 isolates) | 92× faster cold starts than containers |
| E-commerce | Official @shopify/dev-mcp | First-party, Storefront-scoped, cart/checkout built-in |
| Messaging | WhatsApp Cloud API | Official, scalable, webhooks |
| State | Rivet Durable State | Built-in persistence, survives restarts |
| Language | Python 3.12+ | Async-native, rich ecosystem |

## 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

```mermaid
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

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-07-26 | Use Official `@shopify/dev-mcp` | Shopify's first-party MCP: Storefront-scoped, cart/checkout built-in |
| 2026-07-26 | Pi Agent Core (Python) over building from scratch | Mature agent runtime with tool calling, streaming |
| 2026-07-26 | Rivet actors over in-process pool | Durability, distribution, free concurrency management |
| 2026-07-26 | AgentOS (V8 isolates) over containers | 92× faster cold starts, 47× less memory |
| 2026-07-26 | FastAPI thin gateway | No agent logic in gateway, just routing |
| 2026-07-26 | Durable state in Rivet | Built-in persistence, no manual save/restore |

## Architecture Documents

| Document | Scope |
|----------|-------|
| [Architecture](/architecture) | High-level system overview |
| [Agent Architecture](/agent-architecture) | Agent stack and layers |
| [Rivet Actor Model](/rivet-actor-model) | **Actor implementation (canonical)** |
| [Agent Lifecycle](/agent-lifecycle) | Message → actor flow |
| [AgentOS Configuration](/agentos-configuration) | Sandbox setup |
| [Pi Agent Setup](/pi-agent-setup) | Pi Agent Core installation |
| [Pi Agent Core API Reference](/pi-agent-core-api-reference) | Python API reference |
| [Building Pi Extensions](/building-pi-extensions) | Extension development |
| [Concurrency & Security](/concurrency-security) | Rate limiting, injection |
| [Shopify Integration Research](/shopify-integration-research) | MCP decision |
| [WhatsApp Business Cloud API](/whatsapp-business-cloud-api) | WhatsApp integration |
| [Integration Guide](/integration-guide) | End-to-end wiring |

## 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