How to migrate from Intercom to Chatwoot

Move Intercom to self-hosted Chatwoot: import contacts and history with its own importer, rebuild routing and the help centre, then swap widget and channels.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

In short

  • Chatwoot’s Intercom importer copies contacts and conversations, filing the history as resolved conversations in separate import inboxes; attachments are skipped, with a note on each message that had them.
  • The importer is in Chatwoot’s MIT code and in the -ce images, behind the account’s Data Import feature, which current releases leave off by default on a self-hosted instance.
  • Teammates, teams, routing, automations, Messenger settings and help-centre articles are not imported: they are rebuilt in Chatwoot, and articles are copied between the two APIs.
  • The live move is the widget swapped on every site and app, and each email address, WhatsApp number and social account reconnected one at a time and tested with a real message.
On this page (10)

Moving from Intercom to Chatwoot is a re-pointing of live channels, with an import of the history beside it. Chatwoot has its own Intercom importer: it copies contacts and conversations, and files the history as resolved conversations in separate import inboxes, where agents can read it without it mixing into live work. Everything that keeps support running is set up again in Chatwoot: the widget on every site and app, the email addresses, the WhatsApp numbers and social accounts, the teams, routing and automations, and the help centre. This guide covers the order we run it in, and the places it usually goes wrong.

Why teams move from Intercom to Chatwoot

Three reasons come up again and again.

  • The conversation history is stored where you chose. Conversations, contact records and attachments sit in PostgreSQL and a bucket in the location you picked. The website widget stays on that infrastructure from end to end; a WhatsApp message still passes through Meta and a Telegram message through Telegram, whoever hosts the inbox.
  • An MIT-licensed core. Everything in Chatwoot outside its enterprise directory is MIT, and the -ce images leave that directory out. The shared inbox, the widget, automation rules, macros, the help centre and satisfaction surveys come without a licence fee per agent.
  • A dashboard on your private network. The widget, the help centre and the channel webhooks have to face the internet. The dashboard, the agent API and the super admin console do not, so they answer only on your private network.

What you give up is real. Fin, Intercom’s AI agent, has no equivalent in the free edition: Captain, Chatwoot’s assistant, needs a paid plan. Intercom’s outbound tools go further than Chatwoot’s campaigns, which cover proactive messages on your website and one-off sends to a list of contacts. SAML sign-in and SLA policies need Chatwoot’s Enterprise Edition plan. And someone has to run it, which is the part Pilae takes on.

Step 1: list every channel, and export what the importer leaves out

The channel list is the cutover plan. For each line, write down the team that answers it.

  1. Messenger installs. Every website, web app and mobile app that loads the Intercom Messenger, and whether it identifies signed-in users.
  2. Email. Each support address, the rule that forwards it to your workspace’s inbound address at Intercom, and the DKIM and return-path records that let Intercom send as your domain.
  3. Messaging and social. Each WhatsApp number, Facebook page, Instagram account and SMS number.
  4. People and rules. Teammates, teams, assignment rules and workflows, macros, tags, attributes, office hours and SLAs.
  5. The Help Center. Collections and articles in each language, and the domain it answers on.
  6. Integrations. Apps from the Intercom App Store, webhooks, and every script that calls the Intercom API.

Then take Intercom’s own exports. The importer copies history; these are your record, and they hold what it leaves out.

  • Contacts as CSV. In Contacts, select the users, then More, Export users, with all columns. Intercom emails a short-lived link, and recent exports can be downloaded again under Settings, Data, Imports and exports. The file holds the columns of your user list, but of companies only the name and ID of each person’s latest one. Archived users cannot be exported at all, so export before archiving anyone.
  • Conversation data as CSV. Reports, Dataset export gives reporting metadata, such as IDs, timestamps, attributes and metrics, but no message content.
  • Conversation content. The Conversations API returns each conversation in full. The Inbox exports text or PDF transcripts in limited batches, without internal notes; for anything larger, Intercom points to the API.

Step 2: switch on Chatwoot’s importer

The importer lives in Chatwoot’s MIT-licensed code, not in its enterprise directory, so it is part of the -ce images. Chatwoot’s Intercom migration article says it is available on Chatwoot’s paid plans. On a self-hosted instance, the code checks two things: that the user is an account administrator, and that the account has the Data Import feature.

On current releases, Data Import is off by default, and the -ce images have no switch for account features in the super admin console. It is turned on from a Rails console in the Chatwoot container, with the account ID from the dashboard’s address (/app/accounts/<id>/...):

docker exec -it <chatwoot-rails-container> sh -c 'RAILS_ENV=production bundle exec rails c'
Account.find(1).enable_features!('data_import')

Settings, Data then appears for administrators. As of 14 November 2026, Chatwoot’s development branch turns Data Import on by default and switches it on for every existing account during the upgrade; once a release carries that change, this step is already done.

Step 3: import contacts and conversation history

  1. Create the token. In Intercom’s Developer Hub, create a private app for the workspace with two permissions, Read and list users and companies and Read conversations, and copy its Access Token from Configure, Authentication. Intercom limits a private app’s token to the conversations its installing teammate can see, meaning whoever installed the app or last regenerated the token. That teammate needs access to all conversations, which is the default.
  2. Start the import. In Chatwoot, open Settings, Data, and start a new import. Select Intercom, paste the token into Intercom access key, tick Contacts, Conversations or both, and wait for Access key validated before you click Import. It runs in the background, and only one import runs in an account at a time.
  3. Check it. The import page shows counts for contacts, conversations and messages. Compare them with Intercom, download the error and skip logs as CSV, and ask each team lead to open a sample of conversations. A stalled import can be retried, and an active one abandoned.

What the Intercom importer brings across

Imported

  • Contacts: name, email, phone and the user ID your app gave Intercom
  • Conversations, resolved, in import inboxes by source such as Messenger, Email or WhatsApp
  • Messages with their original timestamps, as plain text
  • Internal notes, as private notes
  • Assignments and state changes, as activity lines

Not imported

  • Attachments: a note on each message gives the count skipped
  • Contact custom attributes, tags and companies
  • Teammates, teams, assignments and routing rules
  • Automations, apps and Messenger settings
  • Help Center articles

A few details matter when agents start reading the history.

  • Contacts are matched, not duplicated. Chatwoot looks for an existing contact by user ID, email address or phone number before it creates one, and keeps Intercom’s IDs in custom attributes. Custom attributes, tags and company data from Intercom go in separately through Chatwoot’s contacts API, from the CSV export, where they still matter.
  • Messages lose their formatting. Bodies arrive as plain text, without formatting or line breaks. Teammates’ replies are not linked to Chatwoot agents; the Intercom author is kept in each message’s metadata.
  • Very long conversations are cut. Intercom’s API returns only the most recent parts of a conversation, up to a limit set in its API reference, and the importer does not page back through older ones. When a conversation has more, Chatwoot imports what it received and records the conversation in the error log as incomplete.
  • Nobody is notified. Historical imports send no messages or notifications to customers.

Step 4: rebuild teams, routing and replies

Intercom Chatwoot
Messenger on websites Website inbox and its widget
Messenger in mobile apps One of Chatwoot’s mobile SDKs
Email channel Email inbox, over IMAP and SMTP or Microsoft and Google OAuth
WhatsApp, Facebook, Instagram, SMS An inbox of the same kind
Teammates Agents, with the administrator or agent role
Teams Teams
Assignment and routing in workflows Inbox auto-assignment and automation rules
Macros Macros, and canned responses for text alone
Tags Labels
Contact and conversation attributes Custom attributes
Office hours Business hours and an out-of-office reply, per inbox
Conversation ratings Satisfaction surveys, per inbox
SLAs SLA policies, with the Enterprise Edition plan
Fin AI Agent Captain, with a paid plan

Agents. Teammates are invited to Chatwoot by email, as administrators or agents. Custom roles and per-agent capacity limits come with Chatwoot’s Premium Support plan.

Routing. Each inbox can assign new conversations to its agents in turn. Automation rules do the rest: they run when a conversation is created, updated, opened or resolved, or when a message arrives, check conditions such as inbox, team, labels, content, email address, country or priority, and then assign a team or an agent, add a label, send a message, email a team, change the priority, snooze or resolve. Where an Intercom workflow branched on data from other systems, the rule’s webhook action can hand the conversation to n8n, which answers through Chatwoot’s API.

Replies. A Chatwoot macro is a set of actions an agent runs in one click: send a message, add a label or a private note, assign, change status or priority, snooze or resolve. An Intercom macro that replies and applies actions becomes a Chatwoot macro; text with no action attached becomes a canned response, inserted by its short code.

Sign-in. Chatwoot’s free edition signs agents in with a password and a two-factor code, or with Google. Sign-in through Keycloak or Entra ID is SAML only, and SAML is in the Enterprise Edition plan; Chatwoot has no OpenID Connect or LDAP sign-in. Without the plan, the dashboard stays on your private network and a leaver is removed in Chatwoot as well as in your directory.

Step 5: copy the help centre

The importer leaves help-centre articles out, so they are copied from one API to the other.

  1. Set up the portal. In Chatwoot’s help centre, create a portal with a category for each Intercom collection, in each language you publish.
  2. Read the articles. Intercom’s API lists them at GET /articles and the collections at GET /help_center/collections, for a token with the Read and List articles permission.
  3. Write them. Chatwoot creates each one with POST /api/v1/accounts/{account_id}/portals/{portal_slug}/articles, with its title, content, category, author, status and locale. Chatwoot renders article content as Markdown, and Intercom’s API returns bodies as HTML, with a Markdown version as well. Upload images again rather than leaving them on Intercom’s servers.
  4. Keep the links working. Chatwoot’s help centre can answer on your own domain. If Intercom’s did, point that domain at the portal and redirect each old article address to its new one.

The portal’s articles can also be embedded in the Chatwoot widget, so visitors find answers before they write.

Step 6: swap the widget and reconnect the channels

Move one channel at a time, each tested with a real message before the next.

The widget. Create a website inbox, copy its script, and replace the Intercom snippet with it in the same release, site by site. Chatwoot advises removing Intercom’s code as close as possible to the launch, so there is no gap in coverage. Where your app identifies signed-in users, call window.$chatwoot.setUser with the same user ID your app gave Intercom: the imported contact carries that ID, so new chats join the person’s history. With identity validation switched on, pass an identifier_hash as well, an HMAC-SHA256 of that ID keyed with the inbox’s own token and computed on your server. Mobile apps that embed the Intercom SDK need a release of their own with one of Chatwoot’s mobile SDKs.

Email. Pilae does not operate mail: Chatwoot reads your existing mailboxes. Connect each one over IMAP and SMTP where your mail server allows it, so no inbound mail route has to be published; Microsoft 365 and Google mailboxes connect over OAuth, which a self-hosted instance enables with an app you register with Microsoft or Google. Then remove the forwarding to Intercom. Chatwoot reads the inbox from the previous day onwards and leaves messages on the server, so mail from the day before the connection that is still in the mailbox comes in too, including what Intercom already answered: resolve it. Keep Intercom’s DKIM and return-path records until Intercom has sent its last reply.

WhatsApp. Intercom’s own FAQ says that a number removed from Intercom stays tied to the WhatsApp Business Account used with it, and that using it elsewhere means migrating it to a new account. Plan each number’s move through Meta’s migration flow, then connect it to Chatwoot through the WhatsApp Cloud API and send a test message both ways.

Facebook and Instagram. On a self-hosted instance these connect through a Meta app registered for the instance, and Instagram’s messaging permissions go through Meta’s App Review. Start that review early: it is on Meta’s timetable, not yours.

Step 7: cut over and close Intercom

Chatwoot’s help article describes its import as a one-time migration rather than a sync, and does not document running it twice. Its code does recognise what an earlier run brought in, though: a second run reads every conversation again, skips the records already imported, notes them in the skip log, and adds the conversations and messages that are new since. Because that is how the code behaves rather than a documented feature, we try it on a copy before the cutover depends on it. That second run is what makes a short cutover possible.

The cutover, in order

  1. Import early: The first import runs weeks ahead, and team leads review the history in the import inboxes.
  2. Rebuild: Agents, teams, inboxes, rules and the help centre are in place and tested.
  3. Switch: The widget, the mailboxes, the numbers and the social accounts move one at a time.
  4. Top up: A second import run, once nothing new arrives in Intercom, adds what came in since the first.
  5. Close: The token is revoked, and Intercom stays readable until the subscription ends.

Conversations still open in Intercom on the day are resolved history in Chatwoot. Agents finish them in Intercom, or reply from Chatwoot through the new channel. Once the counts match and the logs are read, revoke the access token or delete the private app, download any attachments you must keep, and end the subscription at the next renewal.

Running Chatwoot in production

Part of Chatwoot faces the internet by design, which shapes how it is run.

  • PostgreSQL with pgvector, the only database Chatwoot supports. Current releases need the extension to upgrade.
  • Redis for the background job queue and cached settings, and a Sidekiq worker apart from the web server. A stalled worker leaves the dashboard up while email stops arriving and replies stop going out.
  • An S3-compatible bucket for attachments, reachable from outside, because visitors who open an attachment are redirected to a signed URL on it.
  • The environment file, which holds the keys that sign cookies and encrypt two-factor secrets: a restore needs it as much as the database and the bucket.
  • Monthly releases, most of which migrate the database.

Pilae operates Chatwoot this way, with the -ce image, telemetry switched off, and a gate that publishes only the widget, help-centre and webhook paths, so the dashboard answers only on your private network. Probes check the web server and the worker every 60 seconds. The database, the bucket and the environment file are backed up daily, encrypted, to an offsite location in the country your contract names, and on Enterprise a restore test every month is recorded in the console. The Pilae Agent runs each release on a copy first, then in your window once you approve it. It runs on your premises or on dedicated machines in Pilae Cloud.

Let Pilae run the move

Pilae runs Intercom to Chatwoot migrations at a fixed price: the channel inventory and exports, the import of contacts and history, the rebuild of teams, routing and replies, the help-centre copy, and the switch of every widget, mailbox, number and account. Where your requirements need a paid Chatwoot plan, it is named in the proposal and held in your name. Then we operate Chatwoot for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us which channels you answer on Intercom and we will scope it.

Questions

Can Chatwoot import our Intercom history?

Yes. Chatwoot has its own Intercom importer. Given an access token that can read contacts and conversations, it copies both and files the history as resolved conversations in separate import inboxes, one per source such as Messenger or email, so it is there for context and never mixed into live work. Attachments do not come across: each affected message carries a note saying how many were skipped.

Is the Intercom importer in the free edition?

Yes. It sits in the MIT-licensed part of Chatwoot, not in its enterprise directory, so it is in the -ce images we deploy. It is behind the account's Data Import feature, which current releases leave off by default on a self-hosted instance; we switch it on for the migration.

What happens to teammates, routing and automations?

They are rebuilt. The importer does not recreate Intercom teammates, teams, assignments, routing rules, automations, apps or Messenger settings, and it leaves help-centre articles out. Agents are invited to Chatwoot, teams and automation rules are set up again, and articles are copied from Intercom's API to Chatwoot's.

Is there an equivalent of Fin?

Not in the free edition. Captain, Chatwoot's assistant that replies to customers on its own, needs a paid Chatwoot plan. AI Assist in the reply box, for rewrites, summaries and suggested replies, is in the MIT build and can point at a model you host.

Is Chatwoot open source?

Mostly. Everything outside its enterprise directory is MIT, and the -ce images leave that directory out, so the Chatwoot code we deploy by default is all MIT. The enterprise directory is source-available under the Chatwoot Enterprise License and needs a paid plan per agent seat in production. The Captain assistant, custom roles, audit logs, SLA policies and SAML sign-on live there.

How long does an Intercom to Chatwoot migration take?

It depends on how many places the Messenger is installed, how many numbers and accounts move, and how much routing and automation is worth rebuilding, more than on the size of the history, which imports in the background. The channel inventory in step 1 settles it, and Pilae quotes the move at a fixed price once it is done.

Let us run the move for you

An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.

Start with one workload

  • Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
  • CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.