TalkToWebsite Docs

TalkToWebsite is an AI customer support platform that lets businesses build intelligent assistants grounded in their own content. Instead of guessing answers, the assistant retrieves relevant information from your knowledge base using a production-grade RAG (Retrieval-Augmented Generation) pipeline.

You can import knowledge from PDF files, plain text files, and website URLs. Visitors interact through an embeddable chat widget on your site or a standalone chat page. Business owners manage assistants, knowledge sources, and conversations from a web dashboard.

TalkToWebsite is designed for teams who want 24/7 AI support without building their own RAG infrastructure from scratch. A production RAG pipeline — chunking, embeddings, vector search, incremental sync, and prompt engineering — typically takes 3 to 6 months of senior engineering. TalkToWebsite provides this out of the box.

Core capabilities:

1. AI Customer Support Chat — Answer visitor questions 24/7 using content from your knowledge base. Responses are grounded in your verified sources, not hallucinated guesses.

2. Knowledge Import — Upload PDF and TXT files, or crawl website URLs to automatically discover and index pages (up to 50 URLs per crawl). Content is chunked, embedded, and stored for semantic retrieval.

3. Embeddable Chat Widget — Add a single script tag to any website. The widget supports chat mode, voice mode, or both. Customize position (bottom-right or bottom-left), theme color, logo, welcome message, quick questions, and teaser popups.

4. Standalone Bot Page — Share a public link at /bot/[botName] for full-page chat and live voice conversations powered by Google Gemini.

5. Voice Support — Visitors can send voice messages through the widget, or use real-time voice chat on the standalone bot page via Gemini Live.

6. Conversation Inbox — View all visitor conversations in the dashboard. See message history, visitor metadata (device, location), and manage threads per assistant.

7. Multi-Language Support — Configure a default language for each assistant from 100+ supported languages.

8. Custom AI Behavior — Set a system prompt to control tone, scope, and how the assistant should respond. Customize greetings, quick-reply buttons, and escalation behavior.

9. Security Controls — Each assistant has a unique widget API key. Optionally restrict the widget to specific allowed origins (domains). Dashboard APIs require authenticated sessions.

10. Incremental Knowledge Sync — When knowledge sources change, only updated content is re-embedded. Unchanged sources are skipped via content hashing.

11. Source Attribution — RAG retrieval returns the most relevant chunks so answers can be grounded in specific knowledge sources.

12. Analytics-Ready Architecture — Track conversations, resolution patterns, and identify knowledge gaps through the conversation inbox.

Architecture overview:

KNOWLEDGE INGESTION When you add knowledge (upload or URL scrape): - Content is saved as a Knowledge Source in PostgreSQL - Text is split into chunks using LangChain RecursiveCharacterTextSplitter (default: 1000 tokens with 150 token overlap) - Each chunk is converted to a vector embedding using Gemini or OpenAI embedding models - Embeddings are stored in PostgreSQL alongside the chunk text - A SHA-256 content hash is saved so unchanged sources skip re-embedding on sync

QUERY PROCESSING (Text Chat) When a visitor sends a message: 1. The server validates the widget API key and optional allowed origin 2. The visitor is identified by a token stored in browser localStorage 3. The user query is embedded using the same embedding model 4. Cosine similarity search finds the top-K most relevant chunks (default: 5 chunks, 0.75 similarity threshold) 5. A prompt is built containing only the relevant chunks plus recent conversation history (last 10 turns) 6. Google Gemini generates a grounded response 7. The conversation is stored in the database

FALLBACK BEHAVIOR If no chunks match the similarity threshold, the system falls back to injecting the full knowledge source text into the prompt instead of retrieved chunks.

VOICE CHAT Voice messages (widget) and Gemini Live (standalone page) currently use the full knowledge base context rather than chunk-level RAG retrieval.

WIDGET EMBED FLOW 1. Your site loads the widget script from /api/widget/widget.js 2. The widget fetches assistant configuration from /api/widget/config/[botName] 3. Visitor messages are sent to POST /api/chat with botName, visitorToken, and widgetApiKey 4. Responses render inside a Shadow DOM chat UI

THREE-TIER AI ROUTING (Product Design) - Instant Answers (62%): Direct knowledge base lookup for common questions — zero latency - Pattern Matching (28%): Smart AI routing for routine questions — answers in under 1 second - Deep Reasoning (10%): Advanced AI models for complex questions — activated only when needed

TalkToWebsite setup time estimates:

FOR MOST TEAMS (SaaS — using TalkToWebsite hosted): - Sign up and create account: 1 to 2 minutes - Create your first assistant (name, system prompt, language): 2 to 3 minutes - Add knowledge (paste URL and scrape, or upload PDF/TXT): 3 to 5 minutes - Configure widget (mode, position, branding): 1 to 2 minutes - Copy embed script and add to your website: 1 to 2 minutes - TOTAL: Under 10 minutes to go live

KNOWLEDGE INDEXING TIME: - PDF/TXT upload: Usually instant to 30 seconds depending on file size - URL discovery (crawling for pages): 30 seconds to 2 minutes depending on site size - URL batch scraping: 1 to 5 minutes for up to 50 pages - RAG embedding sync: 30 seconds to 3 minutes depending on total content volume

FOR SELF-HOSTING (Developer setup): - Clone repo and install dependencies: 5 to 10 minutes - Configure environment variables: 10 to 15 minutes - Set up PostgreSQL database and run migrations: 10 to 20 minutes - Configure Gemini API key and auth secrets: 5 minutes - Optional: Google OAuth setup: 10 to 15 minutes - Build and deploy to Vercel or similar: 15 to 30 minutes - TOTAL: 1 to 2 hours for experienced developers

ONGOING MAINTENANCE: - Knowledge updates propagate automatically when you re-sync sources - No model retraining required when content changes - Regenerate widget API keys instantly from the dashboard if compromised

STEP-BY-STEP GUIDE FOR BUSINESS OWNERS:

Step 1 — Create an Account Go to the TalkToWebsite website and sign up with email/password or Google OAuth. Log in to access your dashboard at /dashboard.

Step 2 — Create an Assistant Click "Create Assistant" in the dashboard. Complete the 3-step wizard: - Step 1 (Basic Info): Set display name, bot slug (used in URLs like /bot/your-slug), description, system prompt, and default language - Step 2 (Knowledge Base): Upload PDF/TXT files or add website URLs. For URLs: paste your site URL, discover pages, select which pages to scrape, then save. Knowledge is automatically synced to the RAG pipeline - Step 3 (Widget Config): Choose chat mode (CHAT, VOICE, or BOTH), widget position (BOTTOM_RIGHT or BOTTOM_LEFT), allowed origin domains, and customize branding (logo, theme color, welcome text, quick questions, teaser message)

Step 3 — Embed on Your Website From the dashboard, copy the embed script tag. It looks like: <script src="https://your-domain.com/api/widget/widget.js" data-bot="your-bot-slug" data-api-key="ttw_..."></script> Paste this before the closing </body> tag on any page where you want the chat widget to appear.

Step 4 — Share Standalone Link (Optional) Share https://your-domain.com/bot/your-bot-slug with customers who prefer a full-page chat experience with voice support.

Step 5 — Monitor Conversations Go to Dashboard > Conversations to view visitor threads, read message history, and review how the AI is performing.

Step 6 — Update Knowledge Edit your assistant to add, remove, or update knowledge sources. Changed content is automatically re-synced via incremental hash-based sync.

FOR WEBSITE VISITORS: - Click the chat bubble on an embedded site or open the standalone bot link - Optionally enter name and email, or skip - Type questions in the chat or use voice mode if enabled - The AI answers based on the business knowledge base - Conversation history persists via a visitor token in localStorage

Prerequisites: - Node.js 18 or later - PostgreSQL database (Prisma Accelerate compatible) - Google Gemini API key (required) - Optional: Google OAuth credentials, OpenAI API key for embeddings

Installation: 1. cd frontend 2. npm install 3. Create a .env file with required variables (see Environment Variables section) 4. npm run db:generate 5. npm run db:migrate (or npm run db:push for development) 6. npm run dev — app runs at http://localhost:3000

Production build: - npm run build - npm start

Migrate existing knowledge to RAG (if upgrading): - npx tsx scripts/migrate-to-rag.ts

Required environment variables: - DATABASE_URL — PostgreSQL connection string (Prisma Accelerate format supported) - AUTH_SECRET — Secret for Better Auth session encryption - BETTER_AUTH_URL — Base URL for auth server (e.g. http://localhost:3000) - NEXT_PUBLIC_APP_URL — Public app URL used for API calls and widget script source - GEMINI_API_KEY — Server-side Gemini API key for chat, voice, and embeddings - GEMINI_TEXT_MODEL — Text generation model (default: gemini-2.0-flash) - GEMINI_MODEL — Multimodal/voice model

Optional environment variables: - GOVERNXONE_API_KEY, GOVERNXONE_PROJECT_ID, GOVERNXONE_ENDPOINT — GovernXOne monitoring credentials (fallback when user profile credentials are not set; users can save their own on /dashboard/profile) - GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET — Google OAuth login - OPENAI_API_KEY — Required if EMBEDDING_PROVIDER=openai - NEXT_PUBLIC_GEMINI_API_KEY — Client-side Gemini Live on /bot/[botName] - NEXT_PUBLIC_GEMINI_LIVE_MODEL — Live voice model name - NEXT_PUBLIC_GEMINI_LIVE_VOICE — Voice name (default: Zephyr) - ALLOWED_GLOBAL_ORIGIN — Bypass per-bot origin restriction for one origin (useful for dev/demo) - EMBEDDING_PROVIDER — gemini or openai (default: openai in code) - EMBEDDING_MODEL — e.g. gemini-embedding-2 or text-embedding-3-small - EMBEDDING_DIMENSIONS — 768 for Gemini, 1536 for OpenAI text-embedding-3-small - CHUNK_SIZE — Chunk size in tokens (default: 1000) - CHUNK_OVERLAP — Overlap in tokens (default: 150) - TOP_K — Number of chunks to retrieve (default: 5) - SIMILARITY_THRESHOLD — Minimum similarity score (default: 0.75)

Tech stack: - Next.js 16 (App Router), React 19, TypeScript - Tailwind CSS 4, Radix UI - PostgreSQL via Prisma 7 with Prisma Accelerate - Better Auth (email/password + Google OAuth) - LangChain for RAG pipeline - Google Gemini for LLM and embeddings - Crawlee + Playwright for URL scraping - Deployed as standalone Next.js output (Vercel-compatible)

Embed the TalkToWebsite chat widget on any website:

Basic embed script: <script src="https://YOUR_DOMAIN/api/widget/widget.js" data-bot="YOUR_BOT_SLUG" data-api-key="ttw_YOUR_API_KEY"></script>

Script attributes: - data-bot (required): Your assistant slug (botName) - data-api-key (required): Widget API key from dashboard (starts with ttw_) - data-theme (optional): auto, light, or dark - data-position (optional): bottom-right or bottom-left

Security: - Each assistant has a unique widget API key. Keep it secret in production — it is included in the embed script - Set allowedOrigin on your assistant to restrict which domains can use the widget - Use ALLOWED_GLOBAL_ORIGIN env var to whitelist a dev/demo origin globally

Widget modes (set in dashboard): - CHAT: Text chat only - VOICE: Voice messages only - BOTH: Text and voice

API endpoints used by the widget: - GET /api/widget/config/[botName] — Fetch assistant configuration - POST /api/chat — Send text messages (RAG-powered) - POST /api/chat/voice — Send voice messages - POST /api/chat/visitor/register — Register visitor profile - GET /api/chat/[botId] — Fetch conversation history

Dashboard routes and features:

/dashboard — Home. Lists all your assistants. Copy embed code, view bot details, delete assistants, edit allowed origins, regenerate API keys.

/dashboard/create — 3-step assistant creation wizard (basic info, knowledge base, widget configuration).

/dashboard/edit/[id] — Edit an existing assistant. Update settings, manage knowledge sources (upload, URL import, delete sources).

/dashboard/conversations — Select an assistant to view its conversations.

/dashboard/conversations/[id] — Visitor list for a specific assistant. Shows visitor metadata.

/dashboard/conversations/[id]/[visitorId] — Full message thread with a specific visitor.

/dashboard/profile — User profile settings.

Authentication: - Dashboard pages require login (email/password or Google OAuth) - API routes enforce session validation server-side via Better Auth

Adding knowledge to your assistant:

FILE UPLOAD - Supported formats: PDF, TXT - Upload via dashboard when creating or editing an assistant - Content is parsed, chunked, embedded, and stored automatically

URL IMPORT - Paste your website URL in the knowledge flow - System discovers up to 50 relevant pages via Crawlee/Playwright crawling - Select pages to scrape, then save - Scraped HTML is converted to text and synced to RAG

RAG SYNC API (for programmatic use): - POST /api/knowledge/import — Body: { "botId": "string" } — Full incremental sync - POST /api/knowledge/sync — Same as import - GET /api/knowledge/status?botId=string — Returns sourceCount, chunkCount, lastSyncedAt

How chunking works: - Default chunk size: 1000 tokens - Default overlap: 150 tokens - Uses LangChain RecursiveCharacterTextSplitter with markdown-aware parsing

How retrieval works: - Query is embedded with the same model used for knowledge chunks - Cosine similarity computed in application layer against all chunks for the bot - Top-K chunks above similarity threshold are injected into the LLM prompt - If no chunks qualify, full knowledge source text is used as fallback

Incremental sync: - Each knowledge source has a content hash (SHA-256) - Unchanged sources are skipped during sync - Changed sources are re-chunked and re-embedded - Deleted sources remove associated chunks

TalkToWebsite security features:

- Data encrypted at rest and in transit - Per-assistant widget API keys (ttw_ prefix) for embed authentication - Optional allowedOrigin restriction per assistant — widget only works on whitelisted domains - Dashboard API routes require authenticated Better Auth sessions - Tenant-isolated data — each user's bots and knowledge are scoped to their account - Visitor tokens stored in browser localStorage for conversation continuity - Widget API key regeneration available from dashboard if a key is compromised

Chat data: - All conversations are stored in PostgreSQL - Visitor metadata (device, geo) may be collected for inbox display - Business owners can review full conversation history in the dashboard

Q: Will the AI give wrong answers? A: TalkToWebsite uses RAG-grounded resolution from your verified knowledge base. When confidence is low, it can escalate to your team with full context. Answers are based on your content, not general internet knowledge.

Q: How long does setup take? A: Average team goes live in under 10 minutes. Paste your URL, let AI index your docs, and add one script tag.

Q: Why not build RAG in-house? A: A production RAG pipeline — chunking, embeddings, vector search, incremental sync, and prompt engineering — typically takes 3 to 6 months of senior engineering. TalkToWebsite built it so you do not have to.

Q: Can I customize the AI responses? A: Yes. Train on your docs, set tone of voice via system prompt, customize greetings, quick questions, and control widget appearance.

Q: Is chat data secure? A: Encrypted at rest and in transit. Per-assistant API keys, authenticated management routes, and tenant-isolated data.

Q: What integrations do you support? A: Embed on any website with a script tag. Standalone bot page for direct links. API access for custom integrations. Works with React, static sites, WordPress, and more.

Q: Does it read from my existing docs? A: Yes. Paste your website URL and TalkToWebsite automatically crawls your docs, FAQs, and help articles. You can also upload PDF and TXT files directly.

Q: What languages are supported? A: 100+ languages. Set a default language per assistant in the dashboard.

Q: Can I use voice chat? A: Yes. Enable VOICE or BOTH mode in widget settings. Standalone bot pages also support Gemini Live real-time voice.

Q: How do I update my knowledge base? A: Edit your assistant in the dashboard, add or remove sources, and changes sync automatically via incremental hash-based re-embedding.

Need help with TalkToWebsite? Contact the founder directly:

Email: satyabratdivedi29@gmail.com

When reaching out, please include: - Your account email - Assistant name or bot slug (if applicable) - A description of the issue or question - Screenshots or error messages if reporting a bug

Support topics we can help with: - Account and login issues - Assistant setup and configuration - Knowledge base import and RAG sync problems - Widget embed and troubleshooting - API integration questions - Feature requests and feedback - Billing and account management

Response time: We aim to respond within 24 to 48 hours on business days.