chatwoot/chatwoot instruction manual

1. Purpose, scope, and Claude Code classification

Chatwoot is a public, Ruby-based customer-support platform intended as an open-source, self-hosted alternative to Intercom, Zendesk, and Salesforce Service Cloud. Its central purpose is to collect customer conversations into a support inbox, give agents collaboration and customer-management tools, publish self-service content, and report on support operations. The repository metadata identifies `develop` as the default branch and describes the project as live chat, email support, and an omnichannel desk.

**Claude Code classification: unclassified.** None of the supplied first-party files documents a Claude Code plugin, skill, hook, MCP server, command package, configuration file, or integration workflow. Captain is described as Chatwoot’s own AI support agent, not as an extension to Claude Code. It would therefore be unreliable to classify this repository as a Claude extension, companion, or alternative based on the supplied evidence.

This manual is limited to the provided repository files. The main README points to the official Help Center for broader product documentation, but external pages were not supplied and are not used here to infer additional behavior. Likewise, metadata topics such as Docker, Helm, Rails, WhatsApp, and Vue identify the project’s ecosystem but do not, by themselves, establish operational commands. The only shell commands reproduced below are those explicitly documented in the supplied Playwright testing README.

2. Customer-support and self-service functions

**Captain AI agent.** Captain automates support responses, handles common questions, and reduces routine agent workload so human agents can focus on more complex conversations. The supplied enterprise code also shows that Captain has a V2-only playground configuration capable of testing scenarios, response guidelines, guardrails, and temporary knowledge.

**Omnichannel desk.** Chatwoot centralizes conversations from website live chat, email, Facebook, Instagram, Twitter, WhatsApp, Telegram, Line, SMS, and other stated channels into one inbox.

**Help Center Portal.** Teams can publish help articles, FAQs, and guides so customers can find answers without opening repetitive support requests.

**Collaboration and productivity.** Private notes and `@mentions` support internal discussion. Labels classify conversations; custom views and filters organize inbox work. Keyboard shortcuts and a command bar speed navigation, while canned responses accelerate repeated replies. Auto-assignment routes conversations according to agent availability, teams and automation scale workflows, and agent-capacity management balances workload. Business hours and auto-responders set response expectations. Multilingual support serves customers in multiple languages.

**Customer data and outreach.** Contact management combines profiles with interaction history. Contact segments and notes support targeted work; custom attributes store additional data. Pre-chat forms collect customer details before a conversation starts. Campaigns provide proactive customer engagement.

These are product-level functions stated in the README. The supplied files do not document exact screen procedures, role matrices, channel setup steps, or environment variables for each function, so this manual does not invent them.

3. Integrations, reporting, deployment, and first-run onboarding

**Integrations.** Chatwoot documents Slack-based conversation management, Dialogflow chatbot automation, embedded Dashboard Apps, Shopify order viewing and management, real-time Google Translate for customer messages, and creation and management of Linear tickets inside Chatwoot.

**Reports and monitoring.** Live View shows ongoing conversations. Separate conversation, agent, inbox, label, and team reports provide operational visibility. CSAT reports measure customer satisfaction, and downloadable reports support offline analysis.

**Deployment choices.** The README provides a Heroku one-click deployment button targeting the repository’s `master` branch, a DigitalOcean one-click Kubernetes marketplace deployment, and an official deployment page for other supported options. It warns that relevant environment variables must be set or features may break. No first-party shell deployment command or complete variable list was supplied, so use the documented buttons or official deployment documentation rather than improvising commands.

**Initial onboarding.** The onboarding page is available only while the Redis installation-onboarding key exists; otherwise both access paths redirect to `/`. The form requires full name, company name, work email, and a password whose placeholder says six or more characters. The release-notes/newsletter/product-survey checkbox is selected by default. Submitting creates a confirmed super-admin and account through `AccountBuilder`. On success, `finish_onboarding` deletes the Redis onboarding key and redirects home. If subscription remains selected, it registers the company, name, and email with `ChatwootHub`; if unchecked, registration is skipped. Any creation exception redirects home with the error and leaves onboarding enabled so it can be retried.

4. Captain web-ingestion configuration

`Firecrawl::Configuration` centralizes the enterprise Firecrawl settings used by Captain. `INSTALLATION_CONFIG_KEY` names the stored setting as `CAPTAIN_FIRECRAWL_API_KEY`. `configured?` returns whether that key resolves to a present value. `api_key` looks up the installation configuration by name and returns its value.

`client` retrieves the key and creates `Firecrawl::Client` with it. If the key is blank, it raises `Firecrawl::FirecrawlError` with a message stating that `CAPTAIN_FIRECRAWL_API_KEY` is not configured. This means callers get an explicit failure instead of a client with missing credentials.

`default_scrape_options` constructs Firecrawl scrape options. It requests Markdown output, limits extraction to main content, and excludes iframes, `.sidebar`, `.cookie-banner`, and elements with navigation, banner, or content-info roles. Its default maximum age is seven days in milliseconds, but the method accepts a different `max_age` value from its caller. These defaults indicate an attempt to obtain reusable, content-focused text while omitting common page chrome.

The supplied file establishes only configuration and option construction. It does not document where to enter the API key in the user interface, which Firecrawl plan is required, how requests are billed, or the exact Captain workflow that invokes scraping. Accordingly, there is no source-supported setup command to copy. Treat the key as a credential and configure it only through a documented Chatwoot installation-config surface described by first-party deployment documentation.

5. Captain V2 playground configuration and validation

`Captain::Playground::Configuration` validates and assembles a playground run. `reject_v1!` always raises a structured error because the playground is Captain V2-only. `initialize` normalizes parameters, resolves scenarios, rules, and knowledge, then raises `Invalid` when any collected error exists. The `Invalid` exception retains an `errors` map and uses the message “Invalid playground configuration.”

`scenarios` combines saved selections with temporary scenarios; `temporary?` identifies temporary objects; `agent_name_for` returns a scenario’s assigned agent name. `prompt_context_for` merges response guidelines, guardrails, optional playground knowledge, and—when the target is the assistant—a scenario summary into existing context. `handler_for` maps an agent name to scenario metadata or falls back to the assistant handler.

Parameter normalization accepts a hash or Rails unsafe-hash-compatible object. Scenario IDs default to enabled assistant scenarios unless explicitly supplied. IDs must parse as positive, unique integers and must belong to the assistant. Temporary scenarios must be objects with a nonblank, unique `client_id`; each is built with title, description, instruction, account, assistant, and enabled status. Tool IDs are extracted from its instruction. Model-validation errors are copied to indexed playground error keys. Temporary agent names use the first 16 hexadecimal characters of a SHA-256 digest of `client_id`; saved scenarios use their handoff key.

Rule resolution accepts arrays only. Every response guideline and guardrail must be a string; whitespace is trimmed, blanks are errors, and duplicates are removed. Knowledge must be a string or null and cannot exceed 10,000 characters. Array-shape errors yield an empty list. `scenario_prompt_context` emits title, key, and description; `assistant_handler` identifies the base assistant; `add_error` accumulates messages.

6. SAML security-settings interface

The security route is `accounts/:accountId/settings/security`, built through the project’s frontend URL helper. Both the parent route and its index require the `administrator` permission and Cloud or Enterprise installation type. The child route also requires the SAML feature flag. The wrapper uses a shield icon, a translated security-settings title, and no “new” button.

In the page component, `allowedLoginMethods` reads `window.chatwootConfig.allowedLoginMethods` and defaults to `['email']`. `isSamlSsoEnabled` checks whether that list includes `saml`. `shouldShowSaml` asks policy logic whether the SAML feature is permitted for administrators on Cloud or Enterprise, then also requires SAML to be an allowed login method. `showPaywall` asks policy logic whether SAML should be paywalled.

Rendering follows a clear order: show the SAML paywall when `showPaywall` is true; otherwise show SAML settings when `shouldShowSaml` is true; otherwise show a translated disabled message. The header links its help treatment to the `saml` feature name.

The paywall component determines whether the current user is a `SuperAdmin`, obtains the current account ID and Cloud status, and selects either the Cloud `PAYWALL` translation or `ENTERPRISE_PAYWALL`. Its upgrade action routes to `billing_settings_index` for the current account. These files document visibility and navigation behavior, not the actual SAML identity-provider fields or setup sequence; no SAML configuration values should be inferred.

7. End-to-end testing workflow

The supplied testing guide describes a Playwright end-to-end framework organized with a Component Object Model. Install dependencies and Playwright browsers, then copy the example environment file:

pnpm install
npx playwright install
cp .env.example .env

Edit `.env` with the URL and credentials of the Chatwoot instance to test. The full variable list is in `.env.example`; it was not supplied here, so no variable names or example secrets are invented.

Run the documented tasks as follows:

# Run all tests
pnpm run playwright:run

# Run tests in UI mode
pnpm run playwright:open

# Lint tests and page objects
pnpm run lint

# Generate test code
pnpm run playwright:codegen

The structure separates `components/api/` for API interaction components from `components/ui/` for page objects. End-to-end tests live under `tests/e2e/api/` for pure API tests and `tests/e2e/ui/` for browser-facing tests. Shared utilities and helpers are in `utils/` and `helpers/`; API response schemas are in `response-schemas/`; reusable test data is in `fixtures/`.

The onboarding request specs illustrate expected behavior: GET succeeds only while onboarding is enabled; successful POST deletes the Redis key; subscription controls instance registration; and builder failure preserves the key. The Playwright README points to `tests/playwright/DOCS.md` for complete patterns, conventions, and troubleshooting, but that file was not supplied, so this manual does not claim its contents.

8. Versions, translation, fixture provenance, and security reporting

**Branches and versions.** Development follows git-flow with `develop` as the base branch. The README directs users seeking a stable version to `master` or tags shaped like `v1.x.x`. The security policy is stricter about maintenance: only the latest version is supported; anything older is unsupported.

**Translation.** Web and mobile translations are managed through Chatwoot’s Crowdin service at `https://translate.chatwoot.com`. The README links an official translation guide for contributors. No local translation command is supplied.

**Freshdesk test fixtures.** The fixture note says the examples contain no production credentials, signed attachment URLs, or personal data. Their shapes come from Freshdesk API v2 documentation, sanitized public-repository examples, and a sanitized trial-account Web Chat response. The fixtures cover an incoming ticket description, public agent reply, private note with attachment metadata, and later customer reply. The web-chat fixture additionally covers source `15`, structured bodies, generated greeting, repeated initial message, later replies, and real attachment metadata keys; identifying values and attachment URLs were replaced or removed.

**Vulnerability reporting.** Report vulnerabilities privately through the repository’s GitHub Security Advisory form, not a public issue or social media. Use `security@chatwoot.com` only for process questions. Reports should explain clear, realistic impact. Test only a self-hosted instance—never Chatwoot production services. Priority classes include remote command execution, SQL injection, authentication bypass, privilege escalation, XSS, unauthorized limited-admin actions, and CSRF. Generally excluded items include scanner-only reports, theoretical attacks, social engineering, denial of service, brute force, missing security headers, SPF/DKIM or DNSSEC issues, weak protocols, physical attacks, and already-compromised-device scenarios. If scope is uncertain, submit a private report.