Converso AI — Bilingual AI Front Desk & Sales Assistant
Most website visitors leave without asking the question that would have led to a sale.
This is the front desk that asks it for you.
The problem it solves
A service business website is a brochure. It answers the questions someone thought to look for, and nothing else.
- A visitor with a specific question — do you handle this, how soon, how much — finds no way to ask, and leaves.
- Contact forms convert badly because they ask for commitment before answering anything.
- Staffing a live chat means paying someone to wait, mostly for nothing.
What it does for the business
- Answers visitor questions on the website, in English or Spanish, using the business's own information.
- Qualifies who is serious and captures booking intent while the person is still interested.
- Escalates the high-intent ones to a human rather than treating every visitor the same.
- Onboards and bills without CushLabs doing the setup by hand, which is what makes it self-serve.
Who it's for
- Service businesses that get web traffic and convert too little of it.
- CushLabs, as the self-serve tier of the assistant range.
Technical reference
Everything below is implementation detail. The business case is above.
Multi-tenant SaaS platform for service businesses to deploy a bilingual (EN/ES), on-brand AI assistant that answers questions, qualifies leads, captures booking intent, and escalates high-intent prospects to live agents.
Overview
Converso AI is a white-label chatbot platform built for service businesses that operate in bilingual markets. Each tenant gets a fully customizable AI assistant backed by their own knowledge base, with automatic language detection and seamless handoff to human agents when conversations require a personal touch.
The platform combines retrieval-augmented generation (RAG) with a visual playbook builder, giving non-technical business owners the tools to script complex conversational flows without writing code. An embeddable widget drops into any website with a single script tag.
The admin dashboard provides full control over knowledge ingestion, lead management, live chat queues, and billing — all tenant-isolated with role-based access control.
The Challenge
Service businesses in bilingual markets face a common problem: they lose leads outside business hours, can't staff bilingual receptionists around the clock, and generic chatbots give wrong answers because they don't know the business.
Existing solutions either require technical expertise to configure, lack real bilingual support (auto-translate is not the same as native language understanding), or charge enterprise prices that small businesses can't justify.
The platform needed to solve three things simultaneously:
- Knowledge accuracy — answers must come from verified business content, not hallucinations
- Language fluency — natural responses in both English and Spanish without translation artifacts
- Operational simplicity — a business owner, not a developer, configures and manages everything
The Solution
Deterministic RAG architecture ensures every answer traces back to uploaded content. The system retrieves relevant knowledge chunks before the LLM call and injects them into the system prompt, so the model answers from facts rather than imagination. Source URLs are automatically attributed in responses.
Native bilingual design detects the user's language from their first message and maintains that language throughout the conversation. System prompts, starter questions, and playbook flows all support dual-language configuration.
Self-service admin dashboard provides a single interface for knowledge management (file uploads, website scraping, manual entry), conversation playbook design (visual flow builder), lead tracking with scoring, live chat handoff queues, and Stripe-powered billing.
Embeddable widget deploys with one script tag. Widget appearance, behavior, and starter questions are configured from the admin panel — no code changes needed on the host site.
Technical Highlights
- Multi-tenant isolation — every database query scopes to
businessId; knowledge, conversations, settings, and billing are fully isolated between tenants
- HNSW vector indexes on pgvector embedding columns for sub-linear similarity search across knowledge bases
- Streaming responses via Vercel AI SDK with real-time token delivery to the chat UI
- RBAC with Clerk — owner/admin/member roles enforced at the API route level via
requirePermission() middleware
- Visual playbook builder using React Flow — business owners design multi-step conversation flows with conditional branching, data capture, and live agent handoff
- Webhook-driven billing — Stripe checkout sessions, subscription lifecycle events, and usage tracking all handled via verified webhooks
- Security headers in proxy.ts — CSP, HSTS, X-Frame-Options applied at the edge via Next.js 16's proxy layer (replaces middleware.ts)
- Sentry error monitoring — client, server, and edge runtime error tracking with source map uploads and
/monitoring tunnel route
- Upstash Redis rate limiting — distributed sliding-window rate limiter that works across Vercel serverless instances (in-memory fallback for dev)
- Runtime env validation — Zod schema validates all required environment variables at startup, fails fast in production
- Vercel Analytics + Speed Insights — page view tracking and Core Web Vitals monitoring
- Bundle optimization — admin tab content lazy-loaded with
next/dynamic, presentational components converted to server components
Getting Started
Prerequisites
- Node.js >= 18
- pnpm >= 9.12
- PostgreSQL database with pgvector extension enabled
- OpenAI API key
- Clerk account (publishable + secret keys)
- Stripe account (for billing features)
Installation
# Clone and install
git clone https://github.com/RCushmaniii/ai-chatbot-saas.git
cd ai-chatbot-saas
pnpm install
# Run database migrations
pnpm db:migrate
# Seed pricing plans
pnpm seed:plans
# Start development server
pnpm dev
Environment Variables
Create a .env.local file at the project root. See .env.example for the full template.
| Variable | Description |
|---|
POSTGRES_URL | PostgreSQL connection string with pgvector |
OPENAI_API_KEY | OpenAI API key for GPT-4o and embeddings |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Clerk publishable key |
CLERK_SECRET_KEY | Clerk secret key |
CLERK_WEBHOOK_SECRET | Clerk webhook signing secret |
STRIPE_SECRET_KEY | Stripe secret key |
STRIPE_WEBHOOK_SECRET | Stripe webhook signing secret |
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | Stripe publishable key |
NEXT_PUBLIC_APP_URL | Public app URL (e.g., https://yourdomain.com) |
UPSTASH_REDIS_REST_URL | Upstash Redis REST URL (rate limiting) |
UPSTASH_REDIS_REST_TOKEN | Upstash Redis REST token |
SENTRY_DSN | Sentry error reporting DSN |
Security
Testing
Playwright E2E and route tests cover:
- Chat API — message creation, streaming, cross-user isolation, resume streams
- Onboarding — full wizard flow (steps 1-4), API validation, redirect logic
- Session — auth state, sign-in/sign-up redirects, sign-out
- Admin Settings — CRUD, partial updates, cross-tenant isolation
- Admin Contacts — create, list, search, filter, pagination, tenant isolation
- Admin Knowledge — list, input validation, tenant isolation
- Embed Widget — script generation, CORS, capture/chat validation, rate limiting
- Health — endpoint availability
pnpm test # Run all tests
Project Structure
ai-chatbot-saas/
├── app/
│ ├── (auth)/ # Clerk sign-in/sign-up routes
│ ├── (chat)/ # Chat UI, admin dashboard, chat API
│ │ ├── api/chat/ # Streaming chat endpoint
│ │ └── admin/ # Admin panel page
│ ├── api/
│ │ ├── admin/ # 15+ admin CRUD endpoints
│ │ ├── embed/ # Widget embed endpoints
│ │ ├── stripe/ # Checkout + portal
│ │ ├── webhooks/ # Stripe + WhatsApp webhook handlers
│ │ └── clerk/ # Clerk webhook handler
│ └── embed/chat/ # Embeddable widget page
├── components/ # React components
│ ├── admin-*/ # Admin panel modules
│ ├── elements/ # Chat message primitives
│ └── ui/ # shadcn/ui component library
├── lib/
│ ├── ai/ # Models, prompts, providers, tools
│ ├── channels/ # Multi-channel bot (WhatsApp via Chat SDK)
│ ├── db/ # Drizzle schema, queries, migrations
│ ├── i18n/ # Translations and language hooks
│ ├── ingestion/ # CSV and DOCX processors
│ ├── playbook/ # Playbook execution engine
│ ├── env.ts # Runtime env validation (Zod)
│ └── rate-limit.ts # Upstash Redis rate limiter
├── sentry.*.config.ts # Sentry client/server/edge configs
├── instrumentation.ts # OpenTelemetry + Sentry + env validation
├── proxy.ts # Security headers + Clerk auth (Next.js 16)
├── migrations/ # Custom SQL migrations
├── scripts/ # Seed, ingest, and maintenance scripts
├── tests/ # Playwright E2E + route tests
└── docs/ # Architecture and planning docs
Deployment
The app deploys to Vercel. The build command runs migrations before building:
pnpm build:migrate
Ensure all environment variables are configured in the Vercel dashboard. The Stripe and Clerk webhooks must point to your production URL.
Results
This platform demonstrates end-to-end SaaS product architecture — from multi-tenant data isolation and role-based access control to Stripe billing integration and embeddable widget distribution.
| Capability | Implementation |
|---|
| Knowledge ingestion | Website scraping, PDF/DOCX/CSV upload, manual entry |
| Vector search | pgvector with HNSW indexes, cosine similarity |
| Conversation flows | Visual playbook builder with 7 node types |
| Lead management | Contact scoring, activity tracking, CSV import/export |
| Live chat | Agent queue with priority routing and AI summaries |
| Billing | Stripe subscriptions with usage-based metering |
| Widget | One-tag embed with configurable appearance |
| Multi-channel | WhatsApp support via Vercel Chat SDK |
| Monitoring | Sentry error tracking, Vercel Analytics, Speed Insights |
| Rate limiting | Upstash Redis distributed limiter |
Contact
Robert Cushman
Business Solution Architect & Full-Stack Developer
Guadalajara, Mexico
[email protected]
GitHub | LinkedIn | Portfolio
License
(c) 2025 Robert Cushman. All rights reserved. See LICENSE.
Last Updated: 2026-04-05
