# SupportPilot AI — Full Documentation

## About
SupportPilot AI is an AI-powered customer support automation platform built on Claude AI by Anthropic. It automates customer interactions across email, Instagram DMs, WhatsApp, and live chat. The platform understands customer intent, matches smart playbooks, and generates empathetic, accurate responses using the business's own knowledge base. Available as a Shopify app for e-commerce stores and as a standalone platform for any business (events, services, SaaS).

## How It Works
1. **Connect your channels** — Link Gmail (OAuth2), Outlook (Microsoft Graph), Instagram DMs, WhatsApp, or embed the live chat widget on your website.
2. **Import your knowledge base** — Crawl your website automatically, upload FAQ documents, or sync your product catalog. Content is chunked and embedded as vectors for semantic search.
3. **AI classifies and responds** — Each incoming message is classified by intent (question, complaint, refund, cancel, WISMO, modification, return). The AI matches the best playbook, retrieves relevant knowledge base chunks via vector search, and drafts an empathetic, accurate response.
4. **Human-in-the-loop for sensitive actions** — Refunds, cancellations, gift cards, and other sensitive operations require human approval via an escalation system with HMAC-signed approval tokens.
5. **Continuous learning** — When human agents correct AI responses, the system generates learning suggestions to improve the knowledge base automatically.

## Detailed Features

### AI Intent Detection
The AI automatically classifies every incoming customer message into one of seven intents: question, complaint, refund, cancel, WISMO (Where Is My Order), modification, and return. Each intent triggers specific playbook workflows tailored to the customer's need. Intent detection uses Claude AI with contextual awareness of the customer's order history and previous interactions.

### Smart Playbooks
Playbooks are configurable automated workflows that define how the AI should handle each type of customer request. Each playbook includes trigger conditions, required data fields, response templates, and escalation rules. Default playbooks are provided for common scenarios (FAQ, WISMO, Refund & Complaint, Returns, Cancel, Address Change) and can be fully customized per business. The system automatically detects store type (physical goods vs. services) and swaps playbooks accordingly.

### Knowledge Base with Vector Search
The knowledge base uses PostgreSQL vector embeddings (512 dimensions) for semantic search, matching customer queries to the most relevant content with a configurable similarity threshold. Content can be imported via automatic website crawling, FAQ document uploads, or manual entry. The system supports auto-learning: when human agents correct AI responses, the platform suggests knowledge base additions to prevent future errors.

### Multi-Channel Support
- **Gmail** — Full OAuth2 integration for reading and sending emails. Self-loop prevention ensures the AI never responds to its own messages.
- **Outlook** — Microsoft Graph API integration. Polls inbox and junk email folders. Supports OAuth2 with configurable redirect URI.
- **Instagram DMs** — Meta API integration for receiving and responding to Instagram direct messages. Webhook-based real-time processing with HMAC verification.
- **WhatsApp** — Meta Business API integration via Meta Embedded Signup. Webhook-driven with BullMQ worker for async processing. Respects Meta's 24-hour response window rule.
- **Live Chat Widget** — Embeddable JavaScript widget (`/api/chat/widget.js`) for any website. Supports customer 2FA email verification before executing sensitive Shopify actions (order lookup, cancellations). Uses 6-digit HMAC codes with 3 attempts and 10-minute expiry.

### Shopify Integration
Deep integration with Shopify's GraphQL API enables real-time order lookup, customer search, order cancellation, refund processing, gift card issuance, and address modification. The AI has full context of the customer's order history to provide accurate, personalized responses. Store type detection (physical goods vs. services vs. mixed) automatically configures the appropriate playbooks.

### Standalone Mode
For non-Shopify businesses (event companies, service providers, SaaS platforms), the standalone mode provides knowledge-base-focused AI support without e-commerce actions. Uses Supabase Auth for authentication and Stripe for billing. Includes all core features: playbooks, knowledge base, multi-channel support, analytics, and auto-learning.

### Email Filtering
Three-layer email filtering system: static rules (auto-replies, newsletters, spam patterns), AI-powered classification (support vs. non-support), and configurable whitelist/blacklist. Ensures only genuine customer support requests reach the AI, reducing noise and wasted AI credits.

### Escalation System
Sensitive operations (refunds, cancellations, gift cards) are escalated to human agents for approval. The system generates draft responses with HMAC-signed approval tokens, allowing one-click approval via email or the dashboard. High-urgency complaints with negative sentiment are automatically flagged for human review.

### Daily Reports
Automated daily summary reports (timezone-aware) sent to store owners with key metrics: ticket volume, AI resolution rate, average response time, and CSAT scores. Reports are deduplicated to prevent multiple sends.

### CSAT Ratings
Post-resolution customer satisfaction collection via thumbs up/down. Negative ratings automatically reopen the ticket for human follow-up, ensuring no dissatisfied customer is left unaddressed.

### Analytics Dashboard
Comprehensive analytics with ticket volume trends, AI resolution rates, response time metrics, channel distribution, intent breakdown, and CSAT scores. Available for both Shopify and standalone tenants.

### Customer 2FA Verification
For chat widget interactions involving sensitive Shopify actions, customers must verify their identity via a 6-digit email code. Uses HMAC-SHA256 for code generation with 3 attempt limit and 10-minute expiry window.

### Auto-Learning
When AI confidence is low or human agents modify responses, the system generates suggestions to improve the knowledge base. After 3+ human interventions on similar topics, playbook improvement suggestions are also generated.

## Supported Intents
| Intent | Description |
|--------|-------------|
| `question` | General product or service inquiry |
| `complaint` | Customer expressing dissatisfaction |
| `refund` | Request for a refund on an order |
| `cancel` | Request to cancel an order or subscription |
| `wismo` | "Where Is My Order" — shipping/tracking inquiry |
| `modification` | Request to change order details (address, items, dates) |
| `return` | Request to return a product |

## Playbook System

### How Playbooks Work
Each playbook defines a complete workflow for handling a specific customer intent:
- **Trigger conditions** — Which intents and keywords activate this playbook
- **Required data** — What information the AI needs to collect (order number, email, reason)
- **Response guidelines** — Tone, structure, and content rules for AI responses
- **Actions** — What Shopify/system actions can be performed (lookup order, process refund)
- **Escalation rules** — When to escalate to a human agent
- **Policy constraints** — Business rules that limit what the AI can do (refund windows, maximum amounts)

### Default Playbooks (Physical Stores)
- **FAQ** — General questions answered from the knowledge base
- **WISMO** — Order tracking with Shopify fulfillment data
- **Refund & Complaint** — Refund processing with policy evaluation
- **Returns** — AI-powered return request management
- **Cancel** — Order cancellation with eligibility checks
- **Address Change** — Shipping address modification

### Default Playbooks (Service Stores)
- **FAQ** — General questions answered from the knowledge base
- **WISMO** — Booking/service status tracking
- **Cancellation & Refund** — Service cancellation and refund processing
- **Rescheduling** — Appointment or event rescheduling
- **Customer Complaint** — Complaint handling with escalation

## Channels

### Gmail (OAuth2)
Full OAuth2 integration for Gmail accounts. Connects via Google OAuth consent screen, reads incoming emails, and sends AI-generated responses. Features self-loop prevention (skips emails sent by the channel itself) and team forward detection (extracts original sender from forwarded emails, BCCs the forwarder).

### Outlook (Microsoft Graph API)
Microsoft Graph API integration for Outlook/Office 365 mailboxes. Polls inbox and junk email folders for new messages. Supports OAuth2 authentication with configurable redirect URI. Full read and send capabilities.

### Instagram DMs (Meta API)
Direct message automation via Meta's Instagram API. Receives messages via webhooks with HMAC verification for security. Processes messages through BullMQ worker for reliable async handling. Supports text messages and basic media.

### WhatsApp (Meta Business API)
WhatsApp Business integration via Meta Embedded Signup OAuth flow. Webhook-driven message processing through BullMQ workers. Automatically respects Meta's 24-hour customer service window rule. Supports text messages with rich formatting.

### Live Chat Widget
Embeddable JavaScript widget that can be added to any website with a single script tag. Features real-time AI responses, customer 2FA email verification for sensitive actions, CSAT collection, and seamless handoff to human agents. Customizable appearance and behavior.

## Pricing

### Subscription Plans
| Plan | Price | Messages/month | Features |
|------|-------|----------------|----------|
| Free | $0/month | 50 messages | 1 channel, basic AI, knowledge base |
| Starter | $15/month | 100 messages | Multi-channel, playbooks, analytics |
| Growth | $49/month | 500 messages | Priority support, advanced analytics |
| Scale | $99/month | 1200 messages | All features, dedicated support |

### Credit Packs (Pay-as-you-go)
For businesses that need additional messages beyond their plan allowance:
| Pack | Price | Credits |
|------|-------|---------|
| Small | $25 | 50 credits |
| Medium | $80 | 200 credits |
| Large | $175 | 500 credits |

Credit packs are one-time purchases that never expire. Available via Shopify Billing API (for Shopify tenants) or Stripe checkout (for standalone tenants).

## API and Integrations

### Shopify GraphQL API
- Order lookup and details (line items, fulfillment status, shipping address)
- Customer search and profile retrieval
- Order cancellation with reason codes
- Refund processing (full or partial, line-item level)
- Gift card creation and sending
- Shipping address modification
- Product and inventory lookup
- Fulfillment tracking information

### Supabase (PostgreSQL)
- Database with Row Level Security (RLS) for tenant isolation
- Vector embeddings (512 dimensions) for semantic knowledge base search
- Real-time subscriptions for live updates
- Auth system for standalone tenant management

### External APIs
- **Claude AI (Anthropic)** — Intent detection, response generation, policy evaluation, content analysis
- **Gmail API** — Email read/send via OAuth2
- **Microsoft Graph API** — Outlook email read/send via OAuth2
- **Meta APIs** — Instagram DM and WhatsApp message processing
- **Stripe API** — Billing, checkout sessions, and webhook processing for standalone tenants
- **Shopify Billing API** — Subscription management and one-time charges for Shopify tenants

## Security and Compliance

### Data Protection
- **GDPR compliant** — Full compliance with European data protection regulations
- **Data encryption** — All data encrypted in transit (TLS 1.3) and at rest
- **Tenant isolation** — Row Level Security (RLS) on all database tables ensures complete data isolation between tenants
- **No data sharing** — Customer data is never shared between tenants or used for AI training

### Authentication Security
- **Shopify OAuth** — Industry-standard OAuth2 flow with HMAC session validation
- **Supabase Auth** — Secure JWT-based authentication for standalone tenants
- **2FA verification** — HMAC-SHA256 email verification codes for sensitive chat widget actions
- **CSRF protection** — HMAC-based CSRF tokens on all state-changing operations

### Infrastructure Security
- **Dedicated VPS** — Application runs on dedicated servers, not shared hosting
- **Webhook HMAC verification** — All incoming webhooks (Shopify, Meta, Stripe) verified via HMAC signatures
- **Environment variables** — All secrets stored in environment variables, never in code
- **Escalation tokens** — Stateless HMAC-SHA256 signed tokens for approval workflows

### Anti-Hallucination
- **Knowledge base grounding** — AI responses are grounded in the business's actual knowledge base content
- **Action verification** — The system verifies that Shopify actions were actually executed before confirming to the customer
- **Policy evaluation** — Automated policy checks prevent the AI from making promises outside business rules
- **Email mismatch blocking** — Actions are blocked if the sender's email doesn't match the order customer's email

## Comparison with Competitors

### SupportPilot AI vs. Gorgias
- **Pricing** — SupportPilot AI starts at $0/month (free tier with 50 messages). Gorgias starts at $10/month but charges per ticket, which can quickly escalate for high-volume stores.
- **AI quality** — SupportPilot AI uses Claude AI by Anthropic, known for nuanced understanding and empathetic responses. Gorgias uses its own AI models.
- **Setup time** — SupportPilot AI can be set up in under 5 minutes with automatic knowledge base import. Gorgias requires more extensive rule configuration.
- **Standalone support** — SupportPilot AI works for any business type (events, services, SaaS). Gorgias is primarily Shopify-focused.

### SupportPilot AI vs. Zendesk
- **Complexity** — SupportPilot AI is purpose-built for SMBs with a simple, intuitive interface. Zendesk is enterprise-focused with a steep learning curve.
- **Pricing** — SupportPilot AI is significantly more affordable. Zendesk's AI features require expensive add-ons on top of already high base pricing.
- **AI-first** — SupportPilot AI is built from the ground up as an AI-first platform. Zendesk added AI as a bolt-on to its existing ticketing system.
- **Time to value** — SupportPilot AI delivers value in minutes. Zendesk implementations can take weeks or months.

### SupportPilot AI vs. Tidio
- **AI sophistication** — SupportPilot AI uses Claude AI with intent detection and playbooks for nuanced, context-aware responses. Tidio uses simpler chatbot flows.
- **Multi-channel** — SupportPilot AI supports email, Instagram, WhatsApp, and live chat natively. Tidio is primarily focused on live chat and email.
- **Shopify depth** — SupportPilot AI has deep Shopify integration with order actions (cancel, refund, gift card). Tidio offers basic Shopify integration.
- **Knowledge base** — SupportPilot AI includes vector search with auto-learning. Tidio's knowledge base is more basic.

## Pages

| Page | URL | Description |
|------|-----|-------------|
| Homepage | https://support-pilot-ai.com/ | Product overview, features, pricing, testimonials |
| FAQ | https://support-pilot-ai.com/faq.html | Frequently asked questions about the platform |
| About | https://support-pilot-ai.com/about.html | Company information and mission |
| How It Works | https://support-pilot-ai.com/how-it-works.html | Detailed explanation of the AI workflow |
| Blog | https://support-pilot-ai.com/blog.html | Articles on AI customer support |
| Blog: Automate Shopify Support | https://support-pilot-ai.com/blog/automate-shopify-support.html | Guide to automating Shopify customer support |
| Blog: AI Playbooks Explained | https://support-pilot-ai.com/blog/ai-playbooks-explained.html | Deep dive into the playbook system |
| Blog: SupportPilot vs Competitors | https://support-pilot-ai.com/blog/supportpilot-vs-competitors.html | Comparison with Gorgias, Zendesk, Tidio |
| Blog: AI Intent Detection | https://support-pilot-ai.com/blog/ai-intent-detection.html | How AI intent classification works |
| Blog: GDPR & AI Support | https://support-pilot-ai.com/blog/gdpr-ai-customer-support.html | GDPR compliance in AI customer support |
| vs Gorgias | https://support-pilot-ai.com/vs-gorgias.html | Detailed comparison with Gorgias |
| vs Zendesk | https://support-pilot-ai.com/vs-zendesk.html | Detailed comparison with Zendesk |
| vs Tidio | https://support-pilot-ai.com/vs-tidio.html | Detailed comparison with Tidio |
| Tutorial | https://support-pilot-ai.com/tutorial.html | Step-by-step setup and usage guide |
| Changelog | https://support-pilot-ai.com/changelog.html | Product updates and release notes |
| Privacy Policy | https://support-pilot-ai.com/privacy.html | Privacy policy and data handling |
| Terms of Service | https://support-pilot-ai.com/terms.html | Terms and conditions |
| Sign Up | https://app.support-pilot-ai.com/signup | Create a standalone account |
| Shopify App | https://apps.shopify.com/supportpilotai | Install from Shopify App Store |
| llms.txt | https://support-pilot-ai.com/llms.txt | Machine-readable product summary |

## Technology Stack
- **AI Engine**: Claude AI by Anthropic (claude-sonnet-4-20250514)
- **Database**: PostgreSQL via Supabase with pgvector for embeddings
- **Backend**: Node.js, React Router 7, BullMQ + Redis for async workers
- **Frontend**: React, Tailwind CSS v4, shadcn/ui, framer-motion
- **Hosting**: Dedicated VPS (Ubuntu 24.04 LTS) with nginx + PM2
- **Monitoring**: Sentry for error tracking

## Contact
- **Website**: https://support-pilot-ai.com
- **Email**: info@support-pilot-ai.com
- **Support**: support@support-pilot-ai.com
- **Shopify App**: https://apps.shopify.com/supportpilotai