Getting Started
Botversion is an AI-powered customer engagement platform that lets you deploy a smart chatbot on your website, automate your social media replies — all from a single dashboard.
Setting up Botversion is a four-step process. Follow the steps below in order and your AI agent will be live in minutes.
No paid plan required to get started. You can complete the full setup and test your AI agent on the free plan. Upgrade anytime to unlock additional features and higher limits.
Setup checklist:
- Create a Project Your workspace for the AI agent, settings, and integrations.
- Generate & Install the SDK Get your unique SDK code and add it to your website.
- Scan Endpoints & Frontend Routes Let Botversion discover your backend API and your website's pages, so the AI agent can take real actions and guide users visually.
- Add Your Website for Crawling Let Botversion learn your site structure for guided assistance.
- Build Your Knowledge Base Feed the AI with information about your business.
Create a Project
A project is your workspace in Botversion. It holds your AI agent configuration, SDK, knowledge base, and integrations. You need at least one project before you can generate an SDK code.
How to create a project:
- Click Create Project in the navbar Navigate to the Create Project page from your dashboard.
- Project Name Enter an internal name for the project — this is only used to identify it inside your dashboard.
- Business Name & Description Enter your official business name and a short description of what your business does. This helps the AI agent represent your business accurately.
- Frontend & Backend URLs Enter your website's frontend URL (e.g.
https://yourapp.com) and backend URL (e.g.https://api.yourapp.com). These are used later to scan your endpoints and pages. - Agree to Terms Check the box to agree to the Terms and Conditions.
- Create the Project Click Create New Project. Your project is created immediately, and a free trial is activated automatically — no payment required to get started.
You can create multiple projects — for example, one per website or client. Each project gets its own unique keys and settings.
Install the SDK
Installing the SDK is a two-part process: embedding a small widget script on your website, and initializing the backend SDK in your server code. Both pieces are generated for you — with your real project keys already filled in — on the Integration page in your dashboard.
Where to get your code:
- Open Integration Click Integration in the left sidebar of your dashboard.
- Select Your Language Choose JavaScript, Python, or PHP — whichever your backend is written in.
- Select Your Framework Pick the specific framework you use (for example Express, Next.js, FastAPI, Django, Laravel, Symfony, and many more are supported). The page will generate the exact code for that framework.
- Copy Each Step's Code The page will show three ready-to-use code blocks — install command, widget embed script, and backend initialization snippet — each with a Copy button.
What you'll add to your project:
- Install the Package A single install command for your language — for example
npm install botversion-sdk,pip install botversion-sdk, orcomposer require botversion/sdk. - Embed the Widget A script tag containing your project's public key. Paste it into your website's
<head>section or just before the closing</body>tag. This is what makes the chat widget appear on your site. - Initialize the Backend SDK A short code snippet added to your main backend file, tailored to your framework — for example inside
bootstrap()for NestJS, orinstrumentation.jsfor Next.js. This is what allows Botversion to discover your API endpoints, as covered in the next section.
Placement matters. For most frameworks, the backend SDK must be initialized after your routes are defined, so it can detect them. The Integration page shows a framework-specific warning with the exact placement to use — follow it closely.
Once both pieces are added, the Botversion chat widget will automatically appear on your website, and the AI agent will start responding to visitor queries using your knowledge base.
Scan Endpoints & Frontend Routes
Botversion discovers two things about your project automatically: your backend API endpoints (so the AI agent can take real actions for your users) and your frontend pages (so the AI agent can visually guide users around your app). Both are found through a single scan — you do not need to list either manually.
An SDK package (available for Node.js, Python, and PHP) is installed in your project. It automatically detects your framework and finds your API routes and, where applicable, your frontend pages for you.
How to run your first scan:
- Install the SDK Install the Botversion SDK package that matches your backend language (Node.js, Python, or PHP), and add the short initialization snippet to your main server file, as shown on the Embedding Code page.
- Go to Scan In your dashboard, open Workspace in the left sidebar, then click Scan.
- Click Scan Press the Scan button. Botversion will connect to your live project, detect your framework, and register all discovered endpoints and frontend pages automatically.
- Review the Results Once the scan finishes, you'll be taken to the Endpoints page where you can see every API route and page that was found.
Everything stays up to date automatically. Once installed, the SDK also watches live traffic on your server. If you add a new endpoint or page later, it will be detected the next time someone visits or calls it — you do not need to re-install or reconfigure anything.
If your backend is serverless
Some backends (for example, apps deployed on Vercel, Netlify, or AWS Lambda) don't run as a long-lived server, so there is no live process for the dashboard's Scan button to reach. In that case, the dashboard will show an error after you click Scan, and you'll need to run the endpoint scan as a build-time step instead. Add the matching command below to your build process, based on your backend language:
"scripts": {
"build": "botversion-scan-endpoints && your-existing-build-command"
}pip install -r requirements.txt && botversion-scan-endpoints
"scripts": {
"post-install-cmd": ["vendor/bin/scan-endpoints.php"]
}Only add the build command for the language your backend is actually written in. Your endpoints will be registered automatically on your next deploy — no need to trigger the Scan button again once this is set up.
If your frontend is statically hosted
Some frontends (for example, sites built with static site generators and deployed to platforms like Vercel, Netlify, or a CDN) only produce static files at build time — there is no live server for the dashboard to reach when scanning for pages. In that case, add the command below to your frontend's build script so pages are detected on every deploy:
"scripts": {
"build": "botversion-scan-frontend && your-existing-build-command"
}botversion-scan-frontend is only needed for static-hosted frontends. If your app is a full-stack framework running on a live server (for example, Next.js on a Node server), the dashboard's Scan button already covers your frontend pages — no extra step is required.
Add Your Website for Crawling
To enable the visual guide and AI agent features, Botversion needs to understand your website's structure. This is done by crawling your site and scanning interactive elements on each page.
How to add your website for crawling:
- Go to Crawl Click Crawl in the left sidebar.
- Enter Your Website URL Type or paste your full website URL (e.g.
https://yourwebsite.com) into the input field. - Click Crawl Hit the Crawl button. Botversion will automatically begin crawling your pages and scanning interactive elements.
DOM scanning is always on. When any visitor opens a page on your site, it is automatically scanned for interactive elements (buttons, links, inputs). New pages are scanned on first visit. Previously scanned pages are re-evaluated if changes are detected. No action is required from you after the initial setup.
Build Your Knowledge Base
The knowledge base is where you give the AI information about your business — your products, services, FAQs, policies, or anything else you want the AI to know when responding to visitors.
How to add data to your knowledge base:
- Go to Knowledge Base Click Knowledge Base in the left sidebar.
- Choose Your Input Method Select how you want to add content — either Upload File or Paste Text.
- Upload a File If uploading, select a .txt or .pdf file from your device. Botversion will extract and index the content automatically.
- Paste Text If pasting, type or paste your content directly into the text field and save. You can add multiple entries over time.
The more relevant content you add to your knowledge base, the more accurately the AI will respond to your visitors. You can add, update, or remove entries at any time.
Supported file formats:
- .txt Plain text files — ideal for FAQs, policies, and product descriptions.
- .pdf PDF documents — great for brochures, manuals, or detailed guides.
Managing Your Project
After a project is created, you can update its details at any time — or permanently delete it — from the project's settings page.
Editing a project:
- Project Details Update the internal project name, then click Update to save.
- Business Details Update your business name or description, then click Update to save. Both fields are required.
- App URLs Update your frontend or backend URL if either has changed, then click Update to save. Both fields are required.
Each section saves independently — you don't need to update every field at once. Only the section you click Update on will be saved.
Deleting a project:
- Open Danger Zone Scroll to the Danger Zone section at the bottom of the Project General page.
- Click Delete Project This opens a confirmation dialog.
- Type to Confirm Type
Delete this projectexactly as shown, then click Delete.
This action is permanent. Deleting a project immediately removes all associated data, including its endpoints, frontend routes, knowledge base, and AI agent configuration. This cannot be undone.
If this was your only project, you'll be redirected to create a new one. If you have other projects, your dashboard will automatically switch to another existing project.
Upgrading Your Plan
Botversion offers a free plan to get you started. To unlock higher message limits, additional projects, advanced features, and priority support, you can upgrade to a paid plan at any time.
How to upgrade:
- Click Upgrade In the left sidebar, click Upgrade.
- Choose a Plan Review the available plans and select the one that fits your needs.
- Complete Payment You will be redirected to our secure payment page powered by Paddle. Enter your billing details and confirm.
- Instant Access Your new plan features are activated immediately after payment.
All payments are processed in USD via Paddle, our Merchant of Record. Subscriptions renew automatically each billing cycle. You can cancel anytime from your account settings.
FAQ
Do I need a paid plan to use Botversion?
No. You can create a project, install the SDK, add a knowledge base, and test the AI agent on the free plan. Paid plans unlock higher limits and advanced features.
Can I install the SDK on more than one website?
Each project has its own SDK code tied to a unique workspace key. Create a separate project for each website and install the respective SDK on each one.
What file types can I upload to the knowledge base?
Currently supported formats are .txt and .pdf. You can also paste text directly without uploading a file.
The dashboard says it can't scan my backend — why?
This usually happens when your backend is deployed on a serverless platform (like Vercel, Netlify, or AWS Lambda) that doesn't run a long-lived server for the dashboard to reach, or the SDK hasn't been initialized in your main file yet. See the "Scan Your API Endpoints" section above for the build-time command to use instead.
Does DOM scanning slow down my website?
No. DOM scanning is lightweight and only captures interactive elements. It runs in the background and has no measurable impact on your website's performance or load time.
Do I need a Business account to connect Facebook or Instagram?
Yes. Only Facebook Business Pages and Instagram Business accounts are supported. Personal accounts cannot be connected.
Are refunds available?
All payments are final and non-refundable. Please review our Terms & Conditions for full details on our billing policy.
How do I get help if something isn't working?
Email us at support@botversion.com and we'll get back to you within 5 business days.
Social Media Integration
Connect your Facebook or Instagram Business account to let Botversion's AI automatically reply to incoming messages on your behalf. You must have an active Business account on the platform you wish to connect.
How to connect:
You can disconnect your social media accounts at any time from the same Social Media page. Upon disconnection, the AI will immediately stop processing messages from that account.