Documentation
Build with Convertss.
Everything you need to install the chatbot, configure offline conversion tracking, manage the knowledge base, and integrate via API.
Getting started
Create your account
Sign up at convertss.com, set your industry URL — your client slug is auto-derived (e.g. ixorabb.com → ixorabb).
Connect your first ad platform
Dashboard → Ads → Offline Conversion → Credentials. Add your Google Ads customer ID, run "Test connection", then load existing conversion actions or create a new one.
Embed the chatbot
Dashboard → AI Chatbot → Configuration. Copy the one-line <script> snippet onto every page of your site, just before </body>.
Chatbot widget
Embed snippet
<script src="https://convertss.com/admin-script.js?serve=YOUR_SLUG" async></script>. That's it. The widget renders inside a Shadow DOM so your site CSS is unaffected.
Pre-chat form
Toggle Name / Email / Phone requirements per tenant. Visitor info is captured before the first message and used for email alerts.
Agent takeover
When a dashboard user sends a reply via the Inbox, the conversation auto-flips agentTakeover=true and the AI stops responding. Click "Resume AI" to hand control back.
Theme customisation
Primary / text colors, header copy, welcome message, bot name, brand name, position (bottom-right / bottom-left) — all editable from the dashboard Configuration tab.
Knowledge base & retrieval
Add a knowledge chunk
Dashboard → Knowledge Base → Knowledge Chunks (AI). Paste long-form text (policy, FAQ, product description). Convertss auto-chunks at paragraph boundaries and generates embeddings via OpenRouter.
Test retrieval
Use the Test retrieval search box to see exactly which chunks rank highest for a given visitor question. The same retrieval feeds the live chatbot.
Three-tier fallback
Vector search ($vectorSearch, cosine, 1536-dim) → Atlas $search text → $regex. The system degrades gracefully if any layer is unavailable.
Offline conversion tracking
How clicks are captured
Our forms and chatbot capture gclid, gbraid, wbraid, fbclid, _fbp, _fbc, ttclid, _ttp, msclkid, and 5 more click IDs from URL params and ad-pixel cookies. They persist for 90 days in browser storage.
How conversions are pushed
For each lead, Convertss routes to every enabled platform: Google Ads (uploadClickConversions), Meta CAPI (Graph v19), TikTok Events API v1.3, Bing (CSV export). Per-platform state is stored on each lead.
PII hashing
Email and phone are SHA-256 hashed before sending to Meta and TikTok, matching their CAPI requirements. We never transmit raw PII to ad platforms.
Forms
Build a form
Dashboard → Formstack → Form Builder. Drag fields, set required, configure post-submission redirect or thank-you message.
Embed
Direct link (/form/[formId]) or iframe. The page captures every click ID + UTM combination automatically.
Spam filtering
AI-based spam detection runs once per lead via OpenRouter, persisted forever. Manual override available on every row.
REST API
Authentication
Cookie-based JWT for dashboard endpoints. The chatbot widget endpoints are CORS-open (no auth, slug-scoped).
POST /api/ads/push
Bulk-push specific lead IDs to all enabled ad platforms. Body: { leadIds: string[] }. Returns per-platform success/failure counts.
GET /api/ads/analytics
Fetch conversion / cost / ROAS metrics from Google Ads with two-query GAQL join.
POST /api/chatbot/start
Public CORS endpoint to open a chat session. Body: { slug, visitorId?, visitor? }.
Security & infra
Storage
MongoDB Atlas with vector search. Per-tenant data isolation via ownerId.
Auth
bcrypt password hashing, JWT (httpOnly + sameSite=strict), separate super-admin token with a different secret.
LLM provider
OpenRouter only. Configurable default + fallback model chain. Health probe via /api/genai/health.
Admin operations
Sign in as a client
/admin → Clients → Sign in. Mints a user JWT with impersonatedBy claim; the dashboard shows a Return to admin banner.
Assign products / mark payments
Per-client detail page: tick products, edit subscription, click any month-cell to cycle Unpaid → Paid → Pending.
Single super-admin credential
Set SUPER_ADMIN_EMAIL and SUPER_ADMIN_PASSWORD in .env. There is no super-admin signup form by design.
Need something deeper?
We don't believe in opaque enterprise contracts. Reach the engineering team directly at hello@convertss.com.