The Complete Guide to Migrating from Intercom to Kustomer

When you decide to move your support operations from Intercom to Kustomer, you are moving to a platform built around a unified customer timeline — every interaction, from historical conversations to custom behavioral events, visible in one place.

The process requires a methodical approach to ensure that your data relationships remain intact and that your agents can be productive from day one.

Define your migration scope

Before you begin the technical heavy lifting, you need to categorize your Intercom data into three distinct buckets to determine exactly how each piece will reach its new home.

What should be migrated via the API

The vast majority of your core data is perfect for API migration. This includes your Admins (which become Users in Kustomer), Teams, and Companies.

You should also plan to move Contacts (Users and Leads) into the Customer object. The structural content of your Help Center, such as Collections and Articles, along with their Versions, can be moved programmatically.

Most importantly, your entire interaction history: Conversations, Messages, Notes, Attachments, Tags, Snoozes, and Data Events should be migrated via the API to maintain a complete audit trail.

What has to be configured manually

Some elements are too tied to the specific logic or visual styling of a platform to move via a script. Your Knowledge Base Themes must be rebuilt manually because they involve custom CSS and HTML that is unique to Kustomer's rendering engine.

Similarly, Workflows and automated Series must be reconstructed by hand. While the data inside them is predictable, the conditional branching and logic of Kustomer's workflow engine require a manual touch to ensure your automations trigger correctly in the new environment.

What has to be archived

Not every piece of data needs to occupy space in your new live environment. You should archive historical Segments that are no longer in use, as these are dynamic filters rather than static data.

You may also find Intercom-specific app data or metadata that was only relevant to Intercom's internal features. Archiving this ensures your Kustomer instance stays clean and that your Custom Attributes are populated only with relevant information.

Prepare Kustomer for data import

Setting up the infrastructure in Kustomer before the data arrives is the secret to a smooth migration. Fields must exist before data can be written to them.

• Define Custom Attribute Metadata: You must establish the schema for all custom fields for Companies, Customers, and Conversations so the API has a destination for your unique Intercom data points.
• Establish Brands: If you support multiple product lines, create your Brands first to ensure data is partitioned correctly upon arrival.
• Create Business Schedules: Set up your support hours and holiday schedules to ensure that migrated conversation timestamps interact correctly with your reporting.
• Define Klasses for Custom Objects: A Klass is Kustomer's term for a custom data model (schema definition). If you are migrating Intercom Tickets, you must first define the Klass that describes their fields and relationships before any records can be written. Each Klass produces a corresponding KObject (a Kustomer Object instance) when records are imported.
• Set up Teams and Users: Create your organizational structure so that historical conversation owners can be mapped to active Users and Teams.

Migrate objects

Data Mapping

The order in which you move your data is critical. Because Kustomer relies on relational data models, moving objects out of order will result in failed requests or orphaned records. You cannot, for instance, attach a message to a conversation that doesn't exist yet.

The first phase involves creating your Users and Teams. Once your staff is represented in the system, you can upload your Custom Attribute Metadata, which prepares the platform to receive non-standard data.

Next, migrate your Companies. Only after the companies exist should you import Customers, as this allows you to link individuals to their respective organizations during the creation process.

The second phase focuses on content. You will move your Knowledge Base Categories (Collections) followed by the Articles and their associated Versions.

The third phase is the most data-intensive: the interaction history. You must create the top-level Conversation container first. Once the conversation ID is generated, you can populate it with individual Messages and their Attachments.

You can then layer on Notes, Tags, and Snoozes to complete the picture of that interaction. Finally, you will import Tracking Events and establish your Saved Searches and Custom Objects.

Post Migration Configuration

After the bulk of the data is in the system, you need to focus on the operational settings that make the platform functional for your team.

• Rebuild Workflows: Manually recreate your Intercom logic using Kustomer's visual builder to handle routing and tagging.
• Configure SLAs: Establish your Service Level Agreements based on your newly imported business schedules to start tracking performance.
• Design KB Themes: Use the theme editor to match your brand's aesthetic for the public-facing knowledge base.
• Assign Search Positions: Organize your Saved Searches (formerly Segments) into folders and set their display order for your agents.
• Setup Shortcuts: Import or manually create Shortcuts and Shortcut Categories to help agents respond quickly.

Insider Secrets

This section covers API-level behavior that is not obvious from reading documentation and represents the most common sources of migration failures and surprises.

1. Bypass rate limits with importedAt

When you include the importedAt field in your API request body for customers, conversations, or messages, Kustomer treats the request as a historical data import rather than a live write, and in practice this often bypasses standard rate limits, allowing for significantly faster data ingestion. Use this field whenever you are writing historical records.

2. The 500-part conversation cap

Kustomer's API retrieves only the 500 most recent parts (messages, notes, events) of a conversation. If your Intercom conversations exceed 500 parts, the older parts will not be accessible via the API. For extremely long conversations, document which threads are at risk and decide whether to truncate, summarize, or handle them as a manual exception.

3. Custom attribute naming suffixes

Kustomer enforces a specific naming convention for custom attribute field names. You must append the correct type suffix when defining metadata, or the import will fail or silently coerce the value. The full suffix table:

For example, a custom field storing a contract tier would be named contractTierStr. A field storing a renewal date would be renewalDateAt. Mismatched suffixes are one of the most common causes of silent data corruption during Kustomer imports.

4. externalId is your deduplication key

Always map Intercom's internal record ID to the externalId field in Kustomer. This serves two purposes: it gives you a stable lookup key for cross-referencing records after migration, and it prevents duplicate records if you need to re-run a migration batch. A 409 Conflict response on a POST request is typically a signal that the externalId already exists — treat it as a skip, not a hard failure.

5. Search indexing latency

There is often a delay of several minutes between creating a Customer or Conversation record and that record appearing in Kustomer's search results. This is an indexing lag, not a write failure. If a search query immediately after import returns zero results, verify the record exists via a direct GET /v1/customers/{id} lookup before concluding the write failed.

6. What Intercom data has no Kustomer equivalent

Not everything maps cleanly. Be aware of the following data loss risks before you begin:

• Intercom Messenger customizations (launcher position, colors, custom CSS on the Messenger widget itself) have no direct equivalent in Kustomer and must be rebuilt from scratch.
• Intercom Product Tours are an Intercom-specific feature with no native equivalent in Kustomer. If you rely on them, you will need a separate tool.
• Segment membership history — Segments in Intercom are dynamic filters, not static lists. The current members can be exported, but the history of who was in a segment at a given time is not portable.
• Intercom-specific app metadata (data written by third-party Intercom apps via the Intercom API) will not have a corresponding Klass in Kustomer unless you define one and map it explicitly.

7. Intercom pagination when exporting large datasets

Intercom's API uses cursor-based pagination. When exporting conversations or contacts at scale, each response includes a next cursor in the response body. You must implement a loop that reads the next value from each response and passes it as the starting_after parameter in the subsequent request. If you miss a cursor or reset pagination mid-run, you will get duplicate or incomplete records in your export. Always checkpoint your cursor position to a durable store (file or database row) so you can resume an interrupted export without starting over.

Common failure modes

These are the migration failures we encounter most often on Intercom-to-Kustomer projects:

1. Missing Klass definition — Importing Tickets before the target Klass exists produces a 400 Bad Request. Define all Klasses before starting Phase 3.
2. Wrong attribute suffix — A field named renewalDate instead of renewalDateAt will either be rejected or stored as a string. Audit your suffix usage before the first import run.
3. Out-of-order object creation — Creating Customers before Companies means organization links are lost and cannot be retroactively applied without re-importing the Customer records.
4. Cursor loss on Intercom export — Losing pagination state mid-export produces gaps in conversation history. Always persist your cursor.
5. importedAt omission — Writing historical records without importedAt causes them to appear as if they were created at migration time, corrupting timeline order.
6. Search latency misread as write failure — Triggering a re-import because search returns empty immediately after a write creates duplicates. Always verify via direct GET before re-running.
7. Conversation part count not audited — Discovering mid-migration that you have conversations with 600+ parts, with no exception plan, causes delays. Run a count query on your Intercom export before you start.

If you'd rather focus on your revenue instead of wrestling with mapping sheets and pagination loops, ClonePartner can handle the full migration for you. Every project gets a dedicated engineer who understands the nuances of both APIs and ensures zero downtime.

Further Reading:

• Kustomer
• Intercom