Chatwoot

Chatwoot is an open source customer support platform that brings messages from website live chat, email, Facebook, WhatsApp, Telegram and more into one inbox. FlashPanel installs Chatwoot as a standalone website on your server.

Requirements

• The server must be on a paid plan. The Chatwoot item shows a lock icon if the server has not been upgraded.
• The server has a web server (Nginx or Apache) installed. FlashPanel automatically installs PostgreSQL 16 and Redis if they are missing.
• Minimum hardware: 4 CPU cores and 4 GB RAM (8 cores and 8 GB are recommended for high conversation volumes).
• A new website dedicated to Chatwoot (for example chat.domain.com). The website's existing source code will be overwritten.
• A free port for Chatwoot. It must not be the Proxy Port of another website on the server and cannot be 80, 443 or 2022.

Installation

1. Create a new website, then click the website name in the list to open its management page.
2. Click the Install Source Code menu, then click the Chatwoot icon.
3. Enter the Port Chatwoot will run on (defaults to the website's Proxy Port or 3000).
4. Read the warning, check Yes, Do it!, then click Install Chatwoot.

Installation takes quite a while. Follow its progress in the website's Events menu. When it finishes, open the website and fill in the form to create the administrator account.

TIP

Install SSL on the website before embedding Chatwoot in other websites, because the embed code should use an https:// address.

Usage

Add live chat to a website

1. In Chatwoot, open Settings > Inboxes and click the button to add a new inbox.
2. Select the Website channel, fill in the details and click Create Inbox.
3. Choose who can reply in the inbox and click Add Agents.
4. Chatwoot shows an embed code (also available in the inbox's Configuration tab) like this:

<script>
  (function(d,t) {
    var BASE_URL="https://chat.domain.com";
    var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
    g.src=BASE_URL+"/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g,s);
    g.onload=function(){
      window.chatwootSDK.run({
        websiteToken: '*****',
        baseUrl: BASE_URL
      })
    }
  })(document,"script");
</script>

5. Paste the code into the website that needs live chat, usually right before the </body> tag.

Send logged-in user details

By default, visitors who send messages appear with a random name. For websites with logged-in users, add the following (after the embed code) so Chatwoot shows the sender's name, email and so on:

<script>
window.addEventListener("chatwoot:ready", function () {
    window.$chatwoot.setUser("user-id", {
        name: "John Doe", // User name
        email: "[email protected]", // User email
        avatar_url: "", // Avatar URL
        phone_number: "", // Phone number
        identifier_hash: "", // Verification hash, see below
    });
});
</script>

The identifier_hash field proves that user-id was generated by your server and prevents impersonation. Copy the HMAC token from User Identity Validation in the inbox's Configuration tab, then generate the hash on your server, for example in PHP:

hash_hmac('sha256', 'user-id', 'chatwoot-inbox-hmac-token');

Enable Enforce User Identity Validation in the same tab so Chatwoot rejects requests that cannot be verified.

Upgrade Chatwoot

When a new version is available, the Action table at the top of the website's Home page shows an upgrade button (note Upgrade chatwoot to the latest stable version with the version number). Click it to upgrade.

Manage from the command line

Other tasks (viewing logs, restarting, opening the Ruby console) are done with the bundled cwctl command-line tool. Connect to the server over SSH as root, then run the command. The command name is cwctl + the website ID, for example cwctl123456 where 123456 is the ID shown in the information card on the website's Home page.

Command	Purpose
cwctl123456 --restart	Restart all Chatwoot services
cwctl123456 --logs web	View the Chatwoot web server logs
cwctl123456 --logs worker	View the background worker logs
cwctl123456 --console	Open the Chatwoot Ruby console (advanced)
cwctl123456 --upgrade	Upgrade to the latest stable version
cwctl123456 --help	List all options

Press Ctrl + C to stop viewing logs.

Uninstall

1. Click the website's Home menu.
2. In the Danger Zone group, click Remove Code.
3. Check Delete Database and Delete Database User if you also want to delete all Chatwoot data (conversations, contacts, accounts).
4. Check Restore default page? to delete the Chatwoot files and return the website to the default page.
5. Check Yes, Do it!, then click Remove Code.

Chatwoot is stopped and removed from the server's background services. PostgreSQL and Redis remain installed on the server.

Notes

• When Chatwoot is installed, the website's web directory is set to /public and the website's Nginx configuration is adjusted automatically for Chatwoot. These Nginx changes are reverted when you uninstall.
• The cwctl command requires root. If you log in as another user, switch to root before running it.