Getting Started
Build a useful chatbot before putting it on your site. The core sequence is create → add content → review → test → customize → integrate.
1. Create an Account and Project
Sign in to the ChattyBox dashboard, select New Chatbot, and give the project a name and optional Website URL. After creation, the workspace opens Knowledge → Import & refresh. Opening a project without a selected tab defaults to Overview. Creation alone does not start an import.
See pricing for current chatbot, account-page, and usage limits.
2. Configure Your Content Source
In Knowledge → Import & refresh, connect the public website, review discovered pages, adjust the recommended or custom selection, and start the selected-page import or refresh. Changes to source settings save automatically: check the save status and resolve validation errors or retry a failed save before continuing. Advanced source settings also offer a separate Scrape Now action using the configured discovery mode. Include/exclude rules and crawl depth are available through configuration as code, not dashboard controls.
ChattyBox extracts readable HTML content and queues changed content for indexing. Discovery and autosave do not themselves start the import. It does not render JavaScript or enforce robots.txt; use public pages you are authorized to index and deliberately select the launch scope. Timing depends on discovery, page count, and indexing work.
Use Add and refresh content when you need sitemap, manual URL, crawl, multilingual, or re-scraping guidance.
3. Review Indexed Content
Open Knowledge → Pages and compare the actual pages with your expected sources. Open the scrape job to review counts and partial-content warnings, and check the separate embedding job before evaluating answers. A completed scrape does not guarantee that every requested page or every section was indexed. See progress and partial indexing.
4. Test Answer Quality
Open Test chatbot and ask representative questions that real visitors will use. Check that answers:
- use the indexed documentation rather than unsupported assumptions;
- link to useful source pages;
- handle missing information with the intended fallback;
- work for important languages and terminology.
Improve the source content or source selection when an answer is weak, then refresh when the plan's cooldown allows it. Free refreshes are at most weekly; paid refreshes are at most daily. Test chatbot uses the owner's message allowance and saves conversations. Test interactions can appear in analytics and, when detected as unanswered, content gaps; billing and gap recording depend on the outcome. Do not install the chatbot merely because the first scrape completed.
5. Tune the Experience
Use Customize → Behavior to choose Helpful Assistant, Sales Representative, Technical Support, Sarcastic Bot, or Custom Persona and edit the instructions. Changes save automatically; check the save status before continuing. Editing a preset switches it to Custom. These instructions supplement ChattyBox's built-in grounding and formatting rules; retrieved content is appended automatically, so do not paste your knowledge base into the prompt.
Persona text does not replace the enforced no-context/content-gap fallback. The separate assistant.fallbackMessage setting is available through configuration as code, not a Persona form field. Test both supported questions and fallback behavior after saving.
If you plan to use the hosted widget, use Customize → Appearance to preview its title, welcome message, colors, icon, position, and language behavior. Changes save automatically; check the save status before continuing. Fixed mode and script overrides affect widget UI language, not which language pages get indexed; see language troubleshooting. Free includes styling but requires ChattyBox branding; Starter and higher can hide it.
These choices come after content testing so visual setup does not hide retrieval or documentation problems.
6. Choose an Integration
| Goal | Next step |
|---|---|
| Mount ChattyBox's maintained interface from application code | JavaScript SDK |
| Build and maintain your own interface | Headless JavaScript SDK |
| Let an AI coding assistant integrate the npm package | AI-assisted integration |
| Manage project configuration from Git and CI | CLI and configuration deployment |
| Use the maintained interface without npm or a build step | Hosted widget script |
| Add the maintained widget to WordPress without theme edits | WordPress plugin |
| Add the maintained widget to Drupal 10 or 11 with Composer | Drupal module |
Browser integrations need a public widget API key. Check its origin settings: a key prepared for a website can already be restricted to that origin; keys created without restrictions work across origins. Under Install → Keys & domains, use Edit origins to manage optional restrictions and add the production, preview, staging, and localhost origins you need. Restricted origins match exactly by scheme, hostname, and port (for example, https://example.com and http://localhost:3000 are different origins). Under Website installation, select the key and copy the generated snippet and API URL.
Public widget keys are designed to appear in browser code. Config deployment tokens and other management credentials are private and must never be added to a website.
To recover an existing public key, enter an HTTP(S) website URL in Website installation and select the key in the snippet. The selector offers unexpired keys that are unrestricted or allowed for that URL's origin. To select a restricted key, enter an allowed origin; use Manage keys & allowed domains to inspect its restrictions. If the installation form is unavailable, complete the setup step shown in the dashboard first. To rotate a key, create a new key, update and test your installation, then delete the old key. Deletion immediately stops installations that still use it. A key belongs to one chatbot; naming it "staging" or "production" does not enforce an environment boundary. Origin restrictions are optional hardening, not visitor authentication.
7. Validate Before Launch
Install the selected integration on a preview or staging site first. Test the deployed origin, navigation between routes, citations, fallback behavior, mobile layout, and browser console before publishing broadly.
Complete the launch checklist, then use Conversations → History on any plan, or Analytics and Unanswered questions on Pro and Business, to improve the documentation after real questions arrive.
Dashboard Map
Open a project at /chatbot/<projectId>. Tabs use the tab query parameter, not separate subpages:
| Workspace view | Query value | What to do there |
|---|---|---|
| Overview | overview | Review setup progress and recent activity |
| Knowledge → Import & refresh | settings | Discover, select, import and refresh pages; adjust source settings |
| Knowledge → Pages | content | Review pages and scrape jobs, delete content, rebuild embeddings |
| Test chatbot | test | Ask questions and revisit saved conversations |
| Conversations → History | logs | Read saved conversations and delete individual or all conversations |
| Conversations → Analytics | analytics | Review the last 30 days of recorded interactions, capped at 5,000 records; Pro/Business |
| Conversations → Unanswered questions | gaps | Review and resolve detected unanswered questions; Pro/Business |
| Customize → Behavior | prompts | Choose or edit assistant instructions |
| Customize → Appearance | appearance | Preview and adjust hosted-widget appearance and language |
| Install → Keys & domains | keys | Create/delete public widget keys and edit optional origin restrictions |
| Install → Website installation | embed | Prepare an installation and copy a key's snippet |
| Chatbot settings | manage | Manage chatbot details, deployment tokens and config lock, or delete the chatbot |
All chatbots returns to /dashboard. The account overview is /dashboard/overview; Account & Billing is /settings/account, with profile, plan, message usage, billing portal, and PAYG controls. /settings and /settings/billing redirect there. /settings/keys provides a project selector for public key creation/deletion; optional origin editing is in the chatbot's Keys & domains view.
Permissions and Config Lock
Dashboard project access is owner-only (or the owning user of a legacy workspace). A public widget key does not grant access to project settings or stored conversation history; organization membership alone does not grant these project permissions.
For Git/CI management, Chatbot settings exposes config deployment tokens with development, preview, and/or production scopes, optional expiry, and revocation. Unlike public widget keys, a deployment token's full value is shown only at creation. The section also shows deployment history.
Enable config lock is irreversible. It blocks dashboard configuration writes and manual content operations, including Persona saves and Scrape Now, even where a control remains visible. Deploy configuration through the CLI workflow instead. Public-key management, conversation cleanup, and the plan-permitted branding preference remain separate from those locked configuration fields. Token environment scopes authorize deployments; they do not create separate chatbots or browser-key environments.
Configuration as code also exposes widget.enabled. Setting it to false disables public chat, including the headless SDK, not just the floating widget. There is no corresponding enable/disable switch in the current appearance form.
Plans and Budgets
| Plan | Chatbots | Account pages | Messages per month |
|---|---|---|---|
| Free | 1 | 10 | 100 |
| Starter | 3 | 150 | 1,000 |
| Pro | 10 | 5,000 | 10,000 |
| Business | 25 | 25,000 | 50,000 |
Messages and included stored pages are owner-level allowances shared by the owner's chatbots, including Test Chat. Monthly page-refresh work and refresh cooldowns are distinct limits; review refresh budgets before a large import or rebuild. See Pricing for the documented shared plan allowances and Account & Billing for your account's current usage and available allowance.
PAYG for messages, pages, and sites is optional on Pro/Business and off by default. In Account & Billing, set monthly overage budgets per feature or explicitly choose No spend cap. A zero budget keeps that feature hard-capped; no spend cap permits uncapped usage charges. PAYG does not unlock features on Free/Starter or bypass crawler refresh cooldowns. Profile name is editable there; email is managed through your sign-in provider's account settings.