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

Originally published on achiya-automation.com.

Most "customer support platform" comparisons end the same way: pick a SaaS, accept its limits, pay per seat forever. This one doesn't. Chatwoot is open-source, and when you self-host it, "customization" stops meaning "which toggles did the vendor expose" and starts meaning "what does your team actually need." I've been running Chatwoot in production for clients long enough to know where that line really is — so here's the honest map of how far you can push it.

There's a specific reason I keep recommending Chatwoot over a closed platform like Intercom, and it isn't price. It's that with a closed SaaS, your customization ceiling is whatever the vendor decided to put in the settings page. With self-hosted Chatwoot you have the source code, the database, and the deployment — so the ceiling is essentially "what can you build." This article is a practical tour of that gap.

TL;DR

Widget — colors, position, locale, behavior, and custom CSS are all configurable; on self-hosted you can patch the widget strings and launcher icon directly
White-label — INSTALLATION_NAME, BRAND_NAME, BRAND_URL remove Chatwoot branding (self-hosted only)
Two APIs — the Application API works inside one account (conversations, contacts, messages); the Platform API manages accounts, users, and bots across the whole install
Webhooks — events like conversation_created and message_created push to n8n / your CRM / custom logic
Dashboard apps — embed your own web app inside the agent inbox via an iframe, with conversation context passed in
Self-hosted unlocks — direct DB access, custom code/forks, no API rate limits, custom channels, full rebranding

A note before the technical part: every fact below maps to Chatwoot's official developer documentation at developers.chatwoot.com. I run this stack daily, but I'd rather you trust the docs than trust me — so check anything load-bearing for your project against them.

1. Widget Customization

The website live-chat widget is the most visible surface, and it's also the easiest to bend. The standard embed is the Chatwoot SDK script plus a settings object you define before the script loads:

<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 widget color and avatar come from the inbox settings in the dashboard, so non-developers can change them without touching code. Beyond that, the SDK gives you runtime methods to make the widget aware of who's chatting — which is where it stops being a generic bubble:

// 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");

That setCustomAttributes call is the underrated one: whatever you pass shows up next to the conversation for the agent, so support sees the customer's plan, account age, or cart value without asking. On a closed platform you'd be limited to whatever attributes the vendor supports; here it's just key-value data you define.

Where self-hosting changes the game: the widget strings and the launcher icon are part of the source. On the installs I run, the default widget copy assumed a team ("we're online"), but the business is a solo operator — so the right phrasing was singular ("I'm online"). On Cloud you'd file a feature request and wait. On self-hosted I patched the locale file and swapped the launcher SVG with an idempotent script that re-applies automatically on every container start, so it survives version upgrades with zero manual steps. That's the difference between configuring and owning.

2. White-Label / Rebranding

This is the cleanest example of "self-hosted only." Chatwoot exposes branding through environment variables:

# 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"

Set those, restart, and the dashboard, the page titles, and the transactional emails reflect your brand instead of Chatwoot's. For an agency reselling support-as-a-service, or a company that simply doesn't want a third-party product name in front of staff and customers, this matters. Combined with a custom domain and the widget tweaks above, a client never has to know which open-source project is underneath.

To be precise about the boundary: full rebranding is a self-hosted capability. Chatwoot Cloud keeps its own branding — which is fair, it's their hosted product. If white-label is a hard requirement, that requirement alone decides self-hosted for you.

3. Application API vs Platform API

This distinction trips people up, so it's worth getting right because it determines what you can automate.

The Application API (you'll also see it called the Client/Agent API) is authenticated with a user access token and operates inside a single account. It's the workhorse for integrations — listing and creating conversations, sending messages, managing contacts, applying labels, reading reports. Example: posting an outgoing message into a conversation:

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 sits a level above accounts. It's authenticated with a Platform App access token and is used to create and manage accounts, users, and agent bots across the whole installation. This is what you reach for when you're provisioning tenants — for example, spinning up a fresh account for every new client and creating their first admin user programmatically:

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 mental model: Application API = act within an account; Platform API = manage the accounts themselves. Most day-to-day automation lives in the Application API. The Platform API is the multi-tenant / provisioning layer — and having it at all is part of why Chatwoot scales from "one inbox" to "a platform you run for many clients."

4. Webhooks and Automation

Webhooks are the integration backbone. Chatwoot can fire an HTTP POST on account events — conversation_created, message_created, conversation_status_changed, conversation_updated, and more — to any URL you register. That's the hook that lets external logic react to what's happening in the inbox.

The pattern I use constantly: Chatwoot → n8n → back into Chatwoot.

A message_created webhook hits an n8n webhook node.
n8n inspects the payload (sender, content, conversation, inbox), runs whatever logic the client needs — classify intent, look something up in a CRM, call an LLM.
n8n calls the Application API to post the reply, add a label, or update a contact attribute.

That loop is how you build an AI first-responder, a CRM sync, or a routing rule that's smarter than anything a settings page offers — without a vendor-specific "app." Because it's just webhooks and REST, the same approach connects Chatwoot to n8n, Make, your own backend, or all three.

Automation rules and macros (no code required)

Not everything needs a webhook. Chatwoot ships two built-in tools that cover a lot of ground:

Automation rules — event-driven if/then logic configured in the dashboard. On conversation creation you can auto-assign to a team, add a label, send a canned reply, or set an attribute based on conditions. No code.
Macros — a saved sequence of actions an agent runs with one click (e.g. "send the refund template, label it billing, resolve"). Great for repetitive multi-step handling.

The rule of thumb: use automation rules and macros for in-app workflow, and reach for webhooks + the API when you need external data or real logic.

5. Custom Integrations and Dashboard Apps

This is the feature that most surprises people coming from closed platforms. Chatwoot lets you embed your own web application inside the agent dashboard as a Dashboard App. You register a URL, and Chatwoot renders it in an iframe in a panel beside the conversation — and it passes the current conversation and contact context to your app via a postMessage event.

Concretely: your app listens for the context Chatwoot sends 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 tooling — order history, a subscription manager, internal notes from another system — right next to the chat, without leaving Chatwoot. On a closed SaaS you'd be waiting for an official integration or a marketplace app. Here you build the panel you actually want and point Chatwoot at it.

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

Pulling the thread together — here's what specifically becomes possible once you own the deployment:

Direct database access. Chatwoot stores everything in PostgreSQL. For reporting beyond the built-in dashboards, you can query the database directly or pipe it into a BI tool. Closed SaaS exposes only what its export API allows.
Custom code and forks. It's open-source. If a behavior doesn't fit, you can change it and run your fork. The widget-string and launcher patches I described above are exactly this — small, surgical, and impossible on a hosted product.
No API rate limits. Self-hosted, the API is bounded by your server, not by a vendor's throttle. Heavy syncs and high-volume bots don't hit a per-plan ceiling.
Custom channels via the API channel. Beyond the built-in channels, Chatwoot's API channel lets you pipe messages from any source into a Chatwoot inbox and send replies back out — so a proprietary or niche messaging system becomes just another inbox.
Full white-label. As covered above — your brand, end to end.
Data residency and control. Every conversation lives on infrastructure you choose. For regulated industries or strict data-protection regimes, that's often non-negotiable.

None of this is a knock on hosted products. It's a description of a different trade: Cloud trades flexibility for zero maintenance; self-hosted trades maintenance for total control. Which one is "right" depends entirely on whether the customizations above are nice-to-haves or requirements for you.

The fork in the road: Cloud or self-hosted?

Both are legitimate. Pick by what you're optimizing for:

You want it managed, with zero maintenance → Chatwoot Cloud is the pragmatic choice — the vendor handles updates, backups, and uptime, and you still get the API, webhooks, and automation rules. Readers here get 5% off Chatwoot Cloud: chatwoot.com (5% off), coupon UJR5GXWK. > Affiliate disclosure: that's an affiliate link — if you subscribe through it, I may earn a commission at no extra cost to you (the coupon gives you 5% off either way). I recommend Chatwoot because I run it in production, not because of the link.
You need the customizations in this article — white-label, custom code, dashboard apps, direct DB access, no rate limits → that's self-hosted, and it's exactly what I set up and manage for clients. One-time setup, no recurring SaaS seat fees.

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 upgrade; every webhook is a thing that can fail at 2 a.m. The discipline that makes self-hosted Chatwoot pay off is restraint: start with the dashboard settings, use automation rules and macros before you write code, keep custom patches small and idempotent, and only reach for a fork when configuration genuinely can't get you there. Done that way, customization is an asset. Done carelessly, it's a maintenance bill.

I'm Achiya Cohen, founder of Achiya Automation. I build WhatsApp bots and business automation, and I run self-hosted, customized Chatwoot in production for clients. If you want open-source customer support tailored to how your business actually works — get in touch. And if managed Cloud fits you better, start here for 5% off with code UJR5GXWK (affiliate link).

推荐订阅源

DEV Community