Total Chat Documentation

Total Chat is an SDK-first AI chat product that deeply integrates into your web application. It provides screen-aware, auto-navigating customer support and lead generation — all with flat monthly pricing.

Key Capabilities

• Screen-Aware AI — Understands current page, modals, filters, and form state
• Auto-Navigation — Highlights and clicks through UI elements automatically
• Self-Evolving KB — Drafts knowledge articles from real conversations
• Lead Generation — Fingerprinting, UTM tracking, and IP-based enrichment
• Bug Routing — Sends bug reports with full context to developer agents
• CRM/Ticketing — Webhooks for HubSpot, Zendesk, Jira, and more

Quickstart

Get Total Chat running in your app in 3 steps:

1. Register Your App

curl -X POST https://totalchat-api.onrender.com/api/onboarding/register \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "My App",
    "appUrl": "https://myapp.com",
    "ownerEmail": "[email protected]"
  }'

Save the appId and apiKey from the response.

2. Add the Script Tag

<script
  src="https://totalchat-api.onrender.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-mode="external"
  data-position="bottom-right"
  data-primary-color="#6366f1"
></script>

3. Scan Your Codebase (Optional)

npx @totalchat/cli scan --target ./src --app-id YOUR_APP_ID

This generates a micro-function map of every route, feature, and interactive element in your app — giving Total Chat deep knowledge of your UI.

Installation

There are two ways to add Total Chat to your app:

<script
  src="https://totalchat-api.onrender.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-mode="external"
  data-position="bottom-right"
  data-primary-color="#6366f1"
  data-greeting="Hi! How can I help?"
></script>

npm install @totalchat/sdk

import { TotalChat } from '@totalchat/sdk';

const chat = new TotalChat({
  appId: 'YOUR_APP_ID',
  mode: 'internal',          // or 'external'
  position: 'bottom-right',
  theme: {
    primaryColor: '#6366f1',
    greeting: 'Hi! How can I help?',
  },
  // Deep integration options
  router: {
    type: 'nextjs',          // or 'react-router', 'custom'
    navigate: (path) => router.push(path),
  },
  user: {
    id: currentUser.id,
    email: currentUser.email,
    name: currentUser.name,
  },
});

chat.init();

Script Tag Integration

The script tag is the simplest way to add Total Chat. Perfect for marketing sites, landing pages, or any site where you want lead capture and support without a build step.

Available Attributes

React / Next.js SDK

The npm SDK provides deep integration with your React or Next.js app. It connects to your router, understands your component tree, and can navigate users through your app.

Next.js App Router

// app/providers.tsx
'use client';

import { TotalChatProvider } from '@totalchat/sdk/react';
import { useRouter } from 'next/navigation';

export function Providers({ children, user }) {
  const router = useRouter();

  return (
    <TotalChatProvider
      appId={process.env.NEXT_PUBLIC_TOTALCHAT_APP_ID}
      mode={user ? 'internal' : 'external'}
      router={{ type: 'nextjs', navigate: router.push }}
      user={user ? { id: user.id, email: user.email, name: user.name } : undefined}
    >
      {children}
    </TotalChatProvider>
  );
}

SDK Methods

Configuration

Configure Total Chat behavior via the dashboard or API.

Full Configuration Object

interface TotalChatConfig {
  appId: string;
  mode: 'internal' | 'external';
  position: 'bottom-right' | 'bottom-left';

  theme: {
    primaryColor: string;
    greeting: string;
    logo?: string;           // URL to custom logo
    widgetTitle?: string;    // Custom widget header title
  };

  router?: {
    type: 'nextjs' | 'react-router' | 'custom';
    navigate: (path: string) => void;
  };

  user?: {
    id: string;
    email: string;
    name?: string;
  };

  features?: {
    autoNavigation: boolean;   // Enable screen-aware navigation
    leadCapture: boolean;      // Enable lead capture (external mode)
    bugReporting: boolean;     // Enable bug report button
    satisfaction: boolean;     // Show satisfaction rating after resolution
  };

  escalation?: {
    emailTo?: string;          // Human escalation email address
    webhookUrl?: string;       // Custom escalation webhook
  };
}

Screen Awareness

Total Chat monitors the user's current screen state in real time. Every message sent to the AI includes context about:

• Current route — e.g., /dashboard/settings
• Active modals — any open dialogs or popups
• Active filters — search queries, date ranges, etc.
• Form state — which fields are filled, validation errors
• Visible elements — buttons, links, and interactive elements on screen

How It Works

The SDK uses a combination of:

1. Route monitoring — Hooks into your app's router to track page changes
2. MutationObserver — Watches for DOM changes (modals, dynamic content)
3. data-guide attributes — Explicit markers for important UI elements
4. Micro-function map — Pre-scanned knowledge of your app's features

Auto-Navigation

When a user asks "how do I export my data?", Total Chat doesn't just explain — it navigates them there. The navigation engine can:

• Highlight the exact button or link to click
• Click through multi-step workflows automatically
• Navigate across pages using your app's router
• Pause if the user interacts mid-walkthrough

data-guide Attributes

Add data-guide attributes to important elements for better navigation accuracy:

<!-- The scanner suggests these automatically -->
<button data-guide="export-data">Export</button>
<nav data-guide="main-navigation">...</nav>
<form data-guide="settings-form">...</form>

Run npx @totalchat/cli scan to get prioritized recommendations for where to add data-guide attributes in your codebase.

Knowledge Base

Total Chat's knowledge base uses semantic search (pgvector embeddings) to find relevant answers even when users phrase questions differently.

Auto-Drafted Articles

When Total Chat answers a question that isn't in the KB, it automatically drafts a new article based on the conversation. You'll receive an email notification to approve, edit, or reject it.

KB Search API

GET /api/kb/search?q=how+to+export&appId=YOUR_APP_ID&limit=5

Returns semantically similar articles ranked by relevance score.

Lead Capture

In external mode, Total Chat captures visitor information for your sales pipeline.

What's Captured

• Digital fingerprint — First-party cookies + localStorage (privacy-friendly)
• UTM parameters — Source, medium, campaign, content, term
• Referrer — Where the visitor came from
• IP enrichment — Company, location, industry (via EM MCP)
• Email — Collected via configurable prompt
• Conversation context — What they asked about, pages visited

CRM Delivery

Leads are automatically pushed to your configured CRM via webhooks. See CRM Webhooks.

Bug Routing

When a user reports a bug through Total Chat, the full conversation context, screen state, and error details are packaged into a structured report and sent to your configured destination.

Report Format

{
  "type": "BUG",
  "priority": "HIGH",
  "subject": "Export button returns 500 error",
  "description": "User on /dashboard clicked Export...",
  "context": {
    "conversationId": "conv_123",
    "pageUrl": "/dashboard",
    "screenState": { "route": "/dashboard", "activeModal": null },
    "errorLogs": ["TypeError: Cannot read property..."]
  },
  "reporter": {
    "email": "[email protected]",
    "userId": "usr_456"
  }
}

Routing Destinations

• Agent Hub — Routes to per-app developer agents that investigate the codebase
• Jira / Linear — Creates an issue with full context
• Zendesk / Freshdesk — Creates a support ticket
• Zapier / Make — Universal webhook fallback

Codebase Scanner

The scanner CLI analyzes your codebase and generates a micro-function map — a complete inventory of every route, feature, and interactive element.

# Install globally or use npx
npm install -g @totalchat/cli

# Scan a Next.js app
totalchat scan --target ./src --framework nextjs

# Scan and upload directly
totalchat scan --target ./src --app-id YOUR_APP_ID --upload

What Gets Scanned

1. Routes — All pages, dynamic params, auth requirements
2. Features — Buttons, forms, links, and interactive elements
3. Components — Your component inventory
4. Existing tours — Any product tours already in your app

Output

The scanner generates a totalchat-map.json file containing your micro-function map. Upload this to Total Chat and the AI immediately understands your app's entire feature set.

data-guide Attributes

These attributes help Total Chat identify and navigate to specific UI elements:

<!-- P1: Critical navigation elements -->
<button data-guide="export-data">Export</button>
<a data-guide="nav-settings" href="/settings">Settings</a>

<!-- P2: Important interactive elements -->
<input data-guide="search-input" placeholder="Search..." />
<select data-guide="filter-status">...</select>

<!-- P3: Supporting elements -->
<div data-guide="dashboard-chart">...</div>

The scanner CLI generates a prioritized list of recommendations showing exactly where to add these attributes. P1 items have the highest impact on navigation accuracy.

API: Conversations

Create Conversation

POST /api/conversations
Content-Type: application/json

{
  "appId": "YOUR_APP_ID",
  "mode": "EXTERNAL",
  "visitorId": "optional-fingerprint-id"
}

Get Conversation

GET /api/conversations/:id

API: Messages

Send Message

POST /api/conversations/:id/messages
Content-Type: application/json

{
  "role": "user",
  "content": "How do I export my data?",
  "pageContext": "/dashboard",
  "screenState": {
    "route": "/dashboard",
    "activeModal": null,
    "visibleElements": ["export-btn", "filter-bar"]
  }
}

The response includes the AI's answer plus any navigation instructions:

{
  "id": "msg_789",
  "role": "assistant",
  "content": "I can see you're on the Dashboard. Let me walk you through exporting your data!",
  "intent": "walkthrough",
  "navigation": {
    "steps": [
      { "action": "navigate", "target": "/settings/export" },
      { "action": "highlight", "selector": "[data-guide='export-btn']" },
      { "action": "click", "selector": "[data-guide='export-btn']" }
    ]
  }
}

API: Knowledge Base

Search KB

GET /api/kb/search?q=export+data&appId=YOUR_APP_ID&limit=5

Create Article

POST /api/kb/articles
Content-Type: application/json

{
  "appId": "YOUR_APP_ID",
  "title": "How to Export Dashboard Data",
  "content": "Navigate to Settings > Export...",
  "category": "data-management",
  "pageRoute": "/settings/export",
  "approved": true
}

API: Onboarding

Register App

POST /api/onboarding/register
Content-Type: application/json

{
  "appName": "My App",
  "appUrl": "https://myapp.com",
  "ownerEmail": "[email protected]",
  "framework": "nextjs"
}

Upload Function Map

POST /api/onboarding/:appId/function-map
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  // Output from totalchat scan
  "app": { "name": "My App", "framework": "nextjs" },
  "routes": [...],
  "features": [...],
  "stats": { "totalRoutes": 14, "totalFeatures": 47 }
}

API: Webhooks

Configure webhooks in your app settings to receive real-time events.

Event Types

CRM Webhooks

Total Chat can push leads to your CRM automatically. Configure in your app settings.

Supported CRMs

• HubSpot — Contacts + Deals
• Salesforce — Leads + Contacts
• GoHighLevel — Contacts + Opportunities
• Pipedrive — Persons + Deals
• Zapier / Make — Universal webhook (works with any CRM)

Lead Data Format

{
  "email": "[email protected]",
  "name": "Jane Doe",
  "company": "Acme Corp",
  "title": "VP Engineering",
  "phone": "+1-555-0123",
  "source": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "brand-awareness"
  },
  "enrichment": {
    "companySize": "50-200",
    "industry": "Technology",
    "location": "San Francisco, CA"
  },
  "conversation": {
    "firstMessage": "How does the SDK integrate with Next.js?",
    "pagesVisited": ["/", "/features", "/pricing", "/docs"]
  }
}

Ticketing Systems

Route support tickets and bug reports to your existing helpdesk.

Supported Systems

• Zendesk — Tickets with full context
• Freshdesk — Tickets with tags and priority
• Jira Service Management — Issues with custom fields
• Linear — Issues with labels and priority
• Help Scout — Conversations with threads
• Zapier / Make — Universal webhook fallback