Chatshore — Telegram-powered chat widget SaaS

A live chat widget that website owners embed with one script tag. Every visitor conversation is relayed into a Telegram group as its own topic, so replies from the group land back in the visitor's chat window.

Single Next.js app — the marketing page, customer dashboard, admin panel and API (Route Handlers) are one deployable unit, run by a single always-on Node server (server.ts, which also hosts Socket.io).

Structure

app/
  page.tsx, login/, register/          Marketing page + auth
  dashboard/                           Customer dashboard
    page.tsx                             Metrics overview (funnel, activity, usage)
    chatbots/                            List, setup wizard, per-bot install/metrics/settings
    billing/                             Plan, usage meters, available plans
  admin/                               Admin panel (users, plans, platform overview)
  api/
    auth/{register,login,me}             Auth
    chatbots/                            CRUD, /verify (Telegram preflight),
                                         [id]/rotate-key, [id]/analytics
    analytics/                           Account-wide metrics
    plans/                               Public plan list
    admin/{users,plans,overview}         Admin-only endpoints
    widget/[apiKey]/{config,messages,track}   Public widget endpoints
    telegram/webhook/[chatbotId]         Telegram calls this on group replies
lib/                                   Prisma, JWT/session, plans, Telegram API, analytics, CORS
public/widget.js                       The embeddable widget (shadow DOM, no dependencies)
prisma/schema.prisma, seed.mjs         Data model + default plans / first admin
prisma.config.ts                       Prisma CLI config (schema path, seed command)

How it works

1. An admin creates the customer's account and assigns a paid plan (or the customer signs up and is placed on the Free tier until an admin upgrades them).
2. The customer runs the setup wizard: it verifies the bot token, group access, Topics being enabled, and the bot's "Manage Topics" permission before saving anything.
3. The chatbot is created with a publishable API key, already baked into the embed snippet.
4. When a visitor sends their first message, a Telegram forum topic is created for them and the mapping (chatbotId + visitorId ↔ topicId) is stored; the message is relayed into it.
5. Telegram calls the webhook route when someone replies inside that topic; the widget picks the reply up on its next poll.

API keys

Each chatbot has a key like cw_live_a1b2… that ships inside the customer's page markup. It identifies a chatbot rather than authenticating a trusted caller — the same model as Stripe publishable keys or an Intercom app ID. The actual access controls are:

• Allowed domains — a per-chatbot hostname allowlist checked against the request Origin.
• Account state — keys stop working the moment the owner is suspended, their plan expires, or they're moved to an unpaid tier.
• Rotation — "Regenerate" issues a new key and invalidates the old one immediately.

Only accounts on a paid, unexpired plan can create chatbots or hold working keys.

Realtime: Socket.io, with HTTP polling as a fallback

server.ts is a custom Node server that runs Next.js and a Socket.io server in one process. The widget uses the socket for presence heartbeats and instant replies, and falls back to polling GET /api/widget/:apiKey/messages every ~3 seconds if the socket can't connect (blocked CDN, strict CSP). This needs an always-on Node server — serverless platforms such as Vercel can't hold the socket connections open.

Metrics

WidgetStat keeps a daily per-chatbot rollup of impressions, so "how many people saw the widget" is answerable without storing a row per page view. From that plus conversations and messages, the dashboard derives the visitor funnel (seen → opened → chatted → replied), a daily activity series, reply rate, and average first-reply time. Day bucketing uses UTC.

Plans

Plans live in the database, not in code — admins change pricing and limits from /admin/plans and they take effect immediately for every account on that plan.

Plan	Monthly	Yearly (≈/mo)	Chatbots	Visitors/month	Live visitors	Dashboard chat
Free	₹0 — a 3-day trial, no card	—	1	500	2	No
Basic	₹499	₹399	5	3,000	10	No
Pro	₹999	₹799	10	10,000	100	Yes

Free trial and upgrades (no payment gateway)

Every signup gets a 3-day trial on the Free plan, with no payment details collected (TRIAL_DAYS in lib/plans.ts). The dashboard shows an onboarding checklist, which is worked out from real data (bot connected → widget seen → first chat → first reply), and a trial countdown. When the trial ends, the account is locked everywhere except Billing. There the customer requests a plan. The request shows up under Plan requests in /admin, and approving it moves the account onto that plan for one billing period. Invoicing happens outside the app.

"Unlimited" is stored as 2147483647 (Postgres int4 max) so limit checks stay plain numeric comparisons — see lib/plans.ts.

Admin panel

At /admin, for users with role = ADMIN:

• Overview — accounts, live chatbots, chats this month, and monthly recurring revenue.
• Users — create accounts with a password and plan, change plan/expiry/role, suspend or restore access, delete. An admin can't demote, suspend or delete themselves.
• Plans — create and edit plans (price, limits, paid/unpaid tier, public visibility). A plan with accounts on it can't be deleted.

This is the beginning of the README. Read the rest at the original. Read the full README ↗