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, open the chatbot from the project list. Its default tab is Content, where stored pages and scrape jobs will appear; creation alone does not start a scrape.
See pricing for current chatbot, account-page, and usage limits.
2. Configure Your Content Source
Open the chatbot's Settings tab. Under General Settings, add the public Website URL and select Save Changes. Under Scraping Configuration, choose a discovery mode, maximum pages, and optional refresh schedule, then select Save Config. These are separate forms. Include/exclude rules and crawl depth are available through configuration as code, not dashboard controls.
Run Scrape Now. ChattyBox discovers the selected pages, extracts readable HTML content, and queues changed content for indexing. 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
Return to Content 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 Chat 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 scrape again when the plan's cooldown allows it. Free refreshes are at most weekly; paid refreshes are at most daily. Test Chat uses your message allowance and contributes to the same conversation logs, analytics, and content gaps as public chat. Do not install the chatbot merely because the first scrape completed.
5. Tune the Experience
Use Persona to choose Helpful Assistant, Sales Representative, Technical Support, Sarcastic Bot, or Custom Persona, edit the instructions, and select Save Changes. 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 Embed to preview its title, welcome message, colors, icon, position, and language behavior, then Save Widget Settings. Settings also exposes the same project language settings. 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. Public keys work from production, previews, staging, and localhost by default. For optional defense-in-depth hardening, open Public Keys > Edit origins, enable Restrict this key to specific origins, and add each permitted browser origin. Restricted origins match exactly by scheme, hostname, and port (for example, https://example.com and http://localhost:3000 are different origins). Return to Embed to 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.
You can recover an existing public key by selecting it in Embed and copying the snippet. To rotate it, 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 Logs on any plan, or Analytics and Content Gaps 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:
| Tab | Query value | What to do there |
|---|---|---|
| Content | content | Review pages and scrape jobs, delete content, rebuild embeddings |
| Test Chat | test | Ask questions and revisit saved conversations |
| Logs | logs | Read saved conversations and delete individual or all conversations |
| Analytics | analytics | Review the last 30 days of recorded interactions, capped at 5,000 records; Pro/Business |
| Content Gaps | gaps | Review and resolve detected unanswered questions; Pro/Business |
| Persona | prompts | Choose or edit assistant instructions |
| Public Keys | keys | Create/delete public widget keys and edit optional origin restrictions |
| Embed | embed | Save hosted-widget appearance/language and copy a key's snippet |
| Settings | settings | Save general/source settings, start scrapes, manage deployment tokens and config lock, delete the chatbot |
All projects returns to /dashboard. Workspace 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 Public Keys tab.
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, Settings > Config deployment tokens creates project-scoped secret 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 Embed 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. The owner-pooled page allowance is part of the forthcoming rollout; until it reaches the public dashboard, labels and enforcement there can still reflect the prior per-chatbot behavior.
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.