Skip to content
A
AskGPT
Docs/how it works

How it works (complete reference)

A full, technical walkthrough of the AskGPT platform — every major subsystem and exactly how it works, end to end.

Architecture at a glance

AskGPT is a Next.js 14 (App Router) application backed by four data services. The app handles the dashboard, public marketing pages, the embeddable widget, and all API routes.

  • →Next.js 14 + TypeScript — SSR, API routes, edge middleware
  • →MongoDB (Mongoose) — users, chatbots, conversations, appointments, complaints, channel connections, rate-limit state
  • →Qdrant — vector search over embeddings (one collection per chatbot: chatbot_{id})
  • →Gemini (primary) + OpenAI (fallback) — embeddings and chat generation
  • →Stripe — subscriptions and credit packs; AWS S3 / MinIO — file storage; Brevo SMTP — email; Web Push (VAPID); Sentry — errors
Visitor ─▶ widget.js ─▶ /api/chatbots/{id}/chat (SSE) │ Mongo ◀── conversation ──────┤ Qdrant ◀── vector search ────┤ Gemini/OpenAI ◀── generate ──┘

Training pipeline (crawl → embed → index)

When you create a chatbot from a URL, an SSRF-hardened crawler discovers pages from the sitemap, extracts and chunks text, embeds each chunk, and stores the vectors in Qdrant plus the raw chunks in MongoDB.

URL ▶ sitemap discovery ▶ fetch pages (protocol+DNS+IP guarded) ▶ strip HTML ▶ chunk (~700 chars, 100 overlap) ▶ embed each chunk (gemini-embedding-001, 3072-dim) ▶ upsert to Qdrant + save KnowledgeChunk to Mongo ▶ status: ready
💡Training costs 10 credits per crawl job + 1 credit per chunk embedded. Re-training wipes old vectors/chunks before writing new ones.

Chat & retrieval (RAG)

Every visitor message runs the same retrieval-augmented flow. History is rebuilt from the server-side conversation record — the client-supplied history is ignored to prevent prompt-injection via forged turns.

POST /api/chatbots/{id}/chat 1. rate-limit (30/min per widget+IP) 2. reserve 1 credit atomically (gate: credits >= -50) 3. embed the message ▶ Qdrant top-6 (cosine >= 0.5) 4. build context + website hint + indexed-page list 5. (optional) one tool-calling round — actions/appointments 6. stream reply over SSE (Gemini/OpenAI) 7. save conversation + analytics; refund credit if aborted/errored 8. auto-flag a complaint if unresolved / customer unhappy
💡Knowledge-base text is wrapped in strict delimiters and 'defused' so scraped content can't act as instructions to the model.

Credits & billing

Credits are the platform's unit of usage, decremented from the chatbot owner's balance per AI action.

  • →Chat reply — 1 credit (reserved atomically, refunded on failure)
  • →Embedding — 1 credit; Site analysis — 10; FAQ generation — 5
  • →Overdraft floor: requests are allowed until the balance is below -50, then rejected with 402
  • →Stripe webhooks (idempotent) activate plans, add credit packs, and replenish monthly credits

AI Actions (Functions)

Actions let the assistant call your own REST API mid-conversation. You configure a base URL + auth header and define actions (name, description, path, method, parameters). During chat the model decides whether to call one.

  • →Single tool-calling round per message (Gemini function-calling / OpenAI tools)
  • →SSRF-hardened: host locked to your base URL, public HTTPS only, no redirects, 8s timeout
  • →Triggers: always / on user request / after lead captured / on human handoff
POST {baseUrl}{path} { "action": "<name>", "params": { ...AI args }, "session": { "visitorId", "lead" } }

Appointments (built-in scheduler)

Set weekly availability (timezone, slot length, lead time, window). The assistant offers free slots and books them via built-in actions, with confirmation emails to both sides.

  • →get_available_slots / book_appointment are offered as tools when booking is enabled
  • →Slots computed in your timezone, minus already-booked times; a unique index prevents double-booking
  • →Google Calendar two-way sync is on the roadmap

FAQs

Generate FAQ drafts from the indexed knowledge base, edit them, and promote the good ones into training.

  • →Generate reads real KnowledgeChunk content and drafts Q&A pairs
  • →Promote embeds the Q&A and upserts it into Qdrant, so it's retrieved during chat like crawled content
  • →Editing a promoted FAQ re-embeds it; removing/deleting takes it out of retrieval

External channels

Connect Telegram, WhatsApp, Discord, and Slack. Channel chats run the same RAG flow and appear in Conversations. Connecting validates credentials with the provider; secrets are encrypted at rest.

  • →Telegram — token validated, webhook auto-registered; fully working
  • →WhatsApp — Meta Cloud API; you paste the shown callback URL + verify token into Meta
  • →Discord — token validated/stored; inbound needs a gateway worker (roadmap)
  • →Slack — requires a platform OAuth app + Events API setup

Conversations & complaints

Every chat is stored and viewable in the Conversations tab with full history, lead details, IP/country, AI summary, tags, and sentiment.

  • →Email the full transcript to the customer; add admin-only internal notes (never seen by the AI/customer)
  • →Complaints auto-open when the bot couldn't answer or the customer sounded unhappy
  • →Complaints are managed on the Support page and notify the owner by email + push

Security & safety

Security is enforced across the stack.

  • →Auth — NextAuth session cookies + custom Bearer JWT, verified at the edge middleware; per-route tenant isolation
  • →Distributed rate limiting & login lockout — shared MongoDB TTL store (holds across replicas)
  • →SSRF hardening — crawler and action calls block private/loopback/internal IPs
  • →CSP with per-request nonce; per-chatbot CORS allowlist for the widget
  • →Secrets (2FA, channel tokens, action secrets) encrypted at rest (AES-256-GCM)
  • →Prompt-injection defenses — delimiter defusing + server-authoritative history
Account setup

Need more help?

Contact support and we'll get back to you within 24 hours.