How Far You Can Actually Customize Chatwoot (Self-Hosted)

How much can you actually change in Chatwoot when you run it on your own server (self-hosted)? Just about everything. You can redesign the little chat window on your website and change how it behaves, put your own brand on the whole thing, plug your own apps right into the screen your support agents use, automate almost any task by wiring it up to other tools, pull data straight out of the database, and — because the software is open-source (meaning the underlying code is free for anyone to read and change) — even rewrite parts of the code itself. The rented version, Chatwoot Cloud, only lets you change the handful of things the company decided to make adjustable.

Most comparisons of customer support tools end the same tired way: pick a rented service, live with whatever it can and can’t do, and pay a monthly fee for every person on your team, forever. This article goes the other direction. When you run Chatwoot on your own server, the question stops being “what did the company let me change?” and becomes “what does my team actually need?” I’ve been running it day to day for real clients long enough to know where the real limits are — so here’s an honest map of how far you can take it.

There’s a specific reason I keep steering people toward Chatwoot instead of a closed product like Intercom, and it has nothing to do with price. With a rented service, the most you can ever change is whatever the company chose to put on their settings screen — that’s your ceiling. When you host Chatwoot yourself, you have the actual code, the database, and the server it all runs on, so your ceiling is basically “whatever you’re willing to build.” This article is a down-to-earth tour of that gap. If you want the wider comparison of cost and features, see Chatwoot vs Intercom; this one is only about how far you can customize.

With a rented service, the most you can ever change is whatever the company put on the settings screen. When you host Chatwoot yourself, the only real limit is what you can build — and that single difference is what this whole article is about.

One note before we get into the technical stuff: everything I describe below is backed by Chatwoot’s own official guides for developers at developers.chatwoot.com. I work with this system every day, but I’d rather you trust the official source than just take my word for it — so if something here is important for your project, double-check it against their guides.

1. Widget Customization

The little live-chat window that pops up on your website is the part your visitors see the most, and it’s also the easiest thing to change. To put it on your site, you paste in a small piece of Chatwoot’s code (their SDK — a ready-made bundle that loads the chat window for you) and, just above it, a short list of your preferences. Here’s what that looks like — the top part is where you set your preferences, and the bottom part is the code that actually loads the window:

<script>
  window.chatwootSettings = {
    locale: "en",            // any locale Chatwoot ships, e.g. "he", "ar", "fr"
    position: "right",       // "left" or "right"
    type: "expanded_bubble", // "standard" or "expanded_bubble"
    launcherTitle: "Chat with us",
    darkMode: "auto",        // "light" or "auto"
  };

  (function (d, t) {
    var BASE_URL = "https://app.chatwoot.com"; // your self-hosted URL
    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: "YOUR_WEBSITE_TOKEN",
        baseUrl: BASE_URL,
      });
    };
  })(document, "script");
</script>

The window’s color and its little profile picture are set from a normal settings page, so someone who doesn’t write code can change them by just clicking around. Beyond that, Chatwoot also gives you a few short commands you can add to your website’s code to tell the chat window who the visitor is — and that’s the moment it stops being a generic pop-up and starts feeling personal. Here are the handy ones:

// Identify the logged-in user so conversations attach to the right contact
window.$chatwoot.setUser("USER_IDENTIFIER", {
  name: "Jane Doe",
  email: "jane@example.com",
});

// Attach structured context that shows up on the agent side
window.$chatwoot.setCustomAttributes({
  plan: "business",
  signup_date: "2026-01-15",
});

// Route or segment by setting a conversation label
window.$chatwoot.setLabel("vip");

// Switch locale at runtime (e.g. when the user changes site language)
window.$chatwoot.setLocale("he");

The middle one, setCustomAttributes, is the quiet hero: any details you send with it show up right next to the conversation on the agent’s screen. So your support person can see, for example, which plan the customer is on, how long they’ve been a customer, or what’s sitting in their shopping cart — without ever having to ask. On a rented platform you’d be stuck with only the details the company happens to support; here, you simply decide what information you want to see and send it along.

Here’s where hosting it yourself completely changes things: the actual words in the chat window and the little button that opens it live inside the software’s own code. On one setup I run, Chatwoot’s built-in wording assumed a whole team was answering — “we’re online” — but the business is a single person, so it really should say “I’m online.” On the rented version, all you can do is ask the company to add that option and then wait, maybe forever. Because I host it myself, I just changed the wording and swapped in a different button icon. And to make sure my changes never get wiped out, I added a small automatic step that re-applies them every time the software restarts — so they stick even after a version update, and I never have to redo them by hand. That’s the real gap between merely adjusting a product and truly owning it.

2. White-Label / Rebranding

This is the clearest example of something you can only do when you host it yourself. Chatwoot keeps its name and web address in a few simple settings you can edit — the ones below. Fill them in with your own company’s details:

# Replaces the product name across the dashboard and system emails
INSTALLATION_NAME="Acme Support"

# Brand name + URL used in branding references
BRAND_NAME="Acme"
BRAND_URL="https://acme.example.com"

Fill those in, restart the software, and suddenly the main screen, the page titles, and every automatic email it sends out all carry your brand instead of Chatwoot’s. If you’re an agency selling customer support as a service under your own name, or simply a company that doesn’t want some other product’s name showing up in front of your staff and customers, this is a big deal. Put it together with your own web address and the chat-window tweaks from before, and your client never has to know there’s a free, open project doing the work behind the scenes.

To be clear about where the line falls: fully rebranding it as your own only works when you host it yourself. The rented Chatwoot Cloud always keeps the Chatwoot name — which is completely fair, since it’s their product running on their servers. So if putting your own brand on everything is a must-have for you, that one requirement alone settles it: you’ll need to host it yourself.

3. The Three Chatwoot APIs: Application, Client, and Platform

This is where a lot of people get confused, and it’s worth sorting out, because it decides what you’re able to automate. First, the word itself: an API is just the doorway that lets one piece of software talk to another. Chatwoot’s official guides describe three separate doorways, each for a different job:

Application APIs are designed for interacting with a Chatwoot account from an agent/admin perspective. Client APIs are intended for building custom messaging experiences over Chatwoot. Platform APIs are used to manage Chatwoot installations at the admin level.

For the kind of customizing this article is about, two of those three doorways do almost all the work — the Application API and the Platform API. The third one, the Client API, only matters in the rare case where you throw out Chatwoot’s chat window completely and build your own from scratch.

The Application API works inside one single workspace, and to use it, another tool signs in with a personal access key tied to a user. This is the everyday workhorse for connecting Chatwoot to your other tools — it can read and start conversations, send messages, manage your contacts, tag conversations, and pull reports. The example below shows the simplest version of this: a small instruction that tells Chatwoot to post a reply into a conversation. And here’s how that reply lands for the customer in the chat:

curl -X POST \
  "https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages" \
  -H "api_access_token: USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thanks for reaching out — an agent will be with you shortly.",
    "message_type": "outgoing"
  }'

The Platform API works one level higher up, above all the individual workspaces. It signs in with its own separate, higher-level key, and it’s what you use to create and manage whole workspaces, users, and bots across your entire setup. This is the doorway you reach for when you’re onboarding new clients — for example, automatically spinning up a fresh workspace for each new client and adding their first administrator. The instruction below creates a brand-new workspace:

curl -X POST "https://app.chatwoot.com/platform/api/v1/accounts" \
  -H "api_access_token: PLATFORM_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Client Workspace" }'

The easy way to keep them straight: the Application API works inside a workspace; the Platform API manages the workspaces themselves. Almost all of your everyday automation runs through the Application API. The Platform API is the one you use to run many separate clients at once — and the fact that it exists at all is a big part of why Chatwoot can grow from “a single inbox for one business” into “a whole platform you operate on behalf of many clients.” You’ll find both explained in the Chatwoot API reference.

4. Webhooks and Automation

Webhooks are the glue that holds all your integrations together. The idea is simple: the moment something happens in Chatwoot, it automatically sends a little message about it to another system of your choosing. You just give Chatwoot a web address to send those messages to, and pick which events should trigger them — a new conversation starting (conversation_created), a new message arriving (message_created), a conversation being closed or reopened (conversation_status_changed), a conversation being updated (conversation_updated), and more. That’s the mechanism that lets your other tools instantly react to whatever is happening in your inbox.

The setup I use all the time is a simple round trip: Chatwoot sends out a message, n8n does the thinking, and then the answer comes right back into Chatwoot. Here’s how it works, step by step:

1. A new message arrives, so Chatwoot fires off its message_created alert and n8n catches it.
2. n8n looks at everything in that alert — who sent it, what they wrote, which conversation and inbox it’s from — and then does whatever the client needs: figure out what the person is asking about, look them up in the customer database, or hand the question to an AI to draft an answer.
3. n8n then sends the result back to Chatwoot through the Application API — posting the reply, tagging the conversation, or updating a detail on the contact.

That little loop is how you build a bot that answers customers the second they write in, or that quietly copies every conversation into your customer database, or that routes messages far more cleverly than any settings page ever could — and all without needing a special add-on. Because the whole thing is just those automatic alerts and standard web requests, the exact same approach connects Chatwoot to n8n, to Make, to your own system, or to all of them at once. If you want to see this AI-on-top-of-Chatwoot idea worked out in full, the chatbot customer service guide covers how to design the conversations, the business automation guide shows where the support piece fits into a bigger picture, and the self-hosted n8n guide walks through running the automation engine on your own server too.

Automation rules and macros (no code required)

Not everything calls for the setup above. Chatwoot comes with two built-in tools that already handle a lot on their own, no coding involved:

• Automation rules — plain “if this happens, then do that” instructions you set up by clicking through a settings page. For instance, the moment a new conversation starts, Chatwoot can hand it to the right team, tag it, fire off a ready-made reply, or fill in a detail — all based on conditions you choose.
• Macros — a saved little routine that an agent can run with a single click. Think “send the refund template, tag it billing, and mark it done,” all in one go. Perfect for the repetitive, multi-step stuff agents do over and over.

A good rule of thumb: use automation rules and macros for anything that happens inside Chatwoot, and only bring in the automatic alerts and the API when you need information from outside or some real decision-making.

5. Custom Integrations and Dashboard Apps

This is the feature that surprises people the most when they come from a closed platform. Chatwoot lets you take your own web app and tuck it right inside the screen your agents work in — this is called a Dashboard App. You just hand Chatwoot the web address of your app, and it shows up in a panel right beside the conversation. Better still, Chatwoot automatically hands your app the details of the conversation and the customer the agent is currently helping.

Here’s how that works in practice: your app simply waits for Chatwoot to send those details over, and then uses them. The code below does exactly that — it catches the customer’s details as Chatwoot sends them in:

// Inside your embedded dashboard app
window.addEventListener("message", function (event) {
  // Chatwoot posts the conversation + contact context here
  try {
    var data = JSON.parse(event.data);
    if (data.event === "appContext") {
      // data.data.conversation and data.data.contact are available
      renderCustomerPanel(data.data);
    }
  } catch (e) {
    /* ignore non-Chatwoot messages */
  }
});

Now your agents see your own tools — a customer’s order history, their subscription details, internal notes kept in some other system — sitting right next to the chat, so they never have to leave Chatwoot to look things up. With a rented service, you’d be stuck waiting for the company to build an official connection, or hunting for one in their app store. Here, you just build the panel you actually want and tell Chatwoot where to find it.

6. Why Self-Hosted Unlocks What Cloud/SaaS Can’t

The reason all of this is even possible comes down to one thing: Chatwoot is truly open-source, meaning its code is public and free for anyone to use and change. It’s a serious, well-supported project — 33,000+ GitHub stars, 7,900+ forks, and an MIT license (one of the most permissive kinds, which flat-out gives you the right to use the software, change it, and run your own version however you like) (chatwoot/chatwoot). That license is exactly what lets you read the code, tweak it, and run your own version without asking anyone’s permission. The rented Chatwoot Cloud, on the other hand, is a hands-off service that costs anywhere from $0/agent/month on the free tier up to $99/agent/month at the Enterprise tier — very convenient, but the most you can ever change is whatever the company decided to make adjustable. (For a point-by-point comparison against a rented competitor, see Chatwoot vs Intercom.)

Here’s that same choice laid out side by side, so you can see exactly what each option gives you across everything we’ve covered:

Let me tie it all together — here’s exactly what opens up for you once the whole thing runs on your own server:

• You can reach straight into the data. Chatwoot keeps every conversation, contact, and setting in a PostgreSQL database (a well-known, free type of database). If you want reports that go beyond Chatwoot’s built-in charts, you can pull the raw numbers straight out yourself, or hook the database up to a reporting tool like Metabase or Grafana that turns that data into dashboards. A rented service only lets you export the slices it chooses to hand you.
• You can change the code and keep your own version. Since it’s open-source, if some behavior just doesn’t suit you, you can rewrite it and run your own edited copy (a fork). The tweaks to the chat window’s wording and its button icon I mentioned earlier are exactly this kind of thing — small, focused changes that simply aren’t possible on a rented product.
• Nothing throttles you. When you host it yourself, the only limit on how much your systems can talk to Chatwoot is your own server’s muscle — there’s no company-imposed cap. So heavy data syncs and busy bots never slam into a “you’ve hit your plan’s limit” wall.
• You can feed in messages from almost anywhere. On top of the channels that come built in, Chatwoot’s API channel lets you funnel messages from any source into a Chatwoot inbox and send replies straight back out — so even an unusual or homegrown messaging system just becomes another inbox your team works from. This is also how a WhatsApp Business API number — an official WhatsApp line for businesses — gets plugged into Chatwoot as a proper, first-class channel.
• You can brand the whole thing as yours. Just as I described earlier — your name and look, from top to bottom.
• You decide where the data lives. Every single conversation sits on servers you picked. For regulated industries, or anywhere with strict rules about protecting customer data, that’s often not optional — it’s a hard requirement.

None of this is meant to put down the rented option. It’s just a different deal: with Cloud, you give up flexibility and in return you never have to maintain anything; when you host it yourself, you take on the upkeep and in return you get total control. Which one is “right” comes down to a single question — are the customizations above just nice extras for you, or are they things you genuinely can’t do without?

A Realistic Word of Caution

Customization is a capability, not a to-do list. The most common mistake I see is treating “we can change everything” as “we should change everything.”

Every fork you maintain is a thing you have to re-test on every upgrade, and every webhook is a thing that can fail at 2 a.m. The discipline that makes self-hosted Chatwoot pay off is restraint, not reach.

In plain terms, that means working from the simplest option up: start with the normal settings pages, lean on the built-in automation rules and macros before you write any code, keep any code changes you do make small and dependable (so they re-apply themselves cleanly every time you update), and only rewrite the actual code when the built-in settings genuinely can’t get you where you need to go. Do it that way and your customizing becomes a real asset. Do it carelessly and it just turns into an endless upkeep bill.

About the Author

I’m Achiya Cohen, founder of Achiya Automation. I build WhatsApp bots and business automation, and I run Chatwoot on my own servers for real clients, customized to fit them — hooked up to WhatsApp, connected to n8n, rebranded as theirs, and looked after from start to finish. If you want open-source customer support shaped around how your business actually works, without paying a monthly fee for every seat, here’s where to start:

• Business automation services — what we build and how
• Pricing — delivery scope and tiers
• Get in touch — tell us what you need

And if managed Cloud is the better fit for you, start here for 5% off with code ACHIYACUST (affiliate link). Either path is a good one — the point is to pick the one that matches your need, not the one that locks you in.