The Complete Guide to Migrating from Intercom to Tidio

Switching your customer communication platform is a significant decision that promises new features and better workflows. When moving from a robust tool like Intercom to Tidio, the challenge lies not just in moving data but in translating it.

These two platforms speak slightly different languages when it comes to how they store your customer interactions.

This guide walks you through the technical steps to bridge that gap. We will look at how to take your rich history from Intercom and reshape it to fit Tidio's streamlined architecture.

By following this structure, you ensure that when your team logs into Tidio on day one, they have the context they need to keep supporting your customers without missing a beat.

Pre-Migration Checklist

Before touching any code, walk through this list:

• Export a full inventory of your Intercom data: contact count, ticket count, conversation count, article count
• Identify all custom Data Attributes in Intercom that you want to preserve
• Create Operator accounts in Tidio for every Intercom Admin who needs ticket assignment
• Define all Custom Properties in the Tidio panel (see "Prepare Tidio" section below)
• Confirm you have API keys with appropriate scopes for both Intercom and Tidio
• Review rate limits for both APIs (see "Rate Limits" section below)
• If you handle EU customer data, confirm your Data Processing Agreements (DPAs) cover the transfer of PII between Intercom and Tidio
• Decide on a rollback strategy before starting (see "Rollback and Validation" section)

Define Your Migration Scope

Before writing a single line of script, you must categorize your data. Not everything fits perfectly into a one-to-one box, so we have to decide what goes through the API, what requires manual effort, and what requires a creative workaround.

API Migration: We will use the API to move the core of your customer database. This includes your Contacts (Intercom calls them Users or Leads) and Tickets. We will also use the API to migrate Custom Attributes, Conversations, Notes, Companies, and Tags, though these require specific workarounds effectively "flattening" complex objects into properties or tickets in Tidio.

Manual Configuration: Your Admins (Operators) and Articles (Help Center content) generally require a manual touch. While APIs exist for reading this data from Intercom, setting up the human element and the knowledge base in Tidio is often faster and cleaner when done by hand or via specific AI importers.

Not API-migratable: Attachments and files embedded in conversations (images, PDFs, file uploads) do not transfer automatically through either API. You will need to download these from Intercom separately and re-upload them manually if they are critical. Similarly, Intercom integrations (Slack, Salesforce, etc.) and webhooks cannot be migrated — you will need to reconfigure equivalent integrations directly in Tidio.

Field Mapping Reference

This table covers the key fields you will encounter during migration. Use it as a quick reference when building your migration script.

Prepare Tidio for Data Import

You cannot simply dump data into a new system without preparing the container first. There are two critical configurations you must rebuild in Tidio before the migration script runs.

First, you need to set up your Operators. In Intercom, you have Admins. Tidio calls them Operators.

Since you will likely want to assign imported tickets or historical conversations to specific team members, those team members must exist in Tidio first. Create their accounts manually in the dashboard so their IDs are available for assignment.

Second, you must define your Custom Properties in the Tidio panel. Intercom is very flexible with "Data Attributes".

Tidio also supports properties, but for the API to update them successfully, it is best practice to have these properties already defined in the Tidio interface.

Look at your Intercom data schema, identify the custom attributes you want to keep (like "Subscription Plan" or "Signup Date"), and create corresponding properties in Tidio.

Rate Limits

Both APIs enforce rate limits that will directly affect how fast your migration runs. Check the current limits in each platform's documentation before you start:

• Intercom: Review the Intercom API rate limits in their developer docs. Build pagination and backoff logic into your export scripts.
• Tidio: Review the Tidio API rate limits in their developer docs. Since you are pushing data in batches, hitting rate limits on the write side is the more common bottleneck.

Build retry logic with exponential backoff into your migration script. Log every rate-limit response so you can tune batch sizes and delays between requests.

Migrate Objects

The order in which you move objects matters immensely because some data types depend on others existing first.

1. Contacts (Users and Leads): Everything in Tidio revolves around the Contact. You must migrate these first. Intercom separates people into Users and Leads, but Tidio treats them all as Contacts identified by an email or phone number.

You will pull your list from Intercom and use the "Create multiple contacts" endpoint in Tidio to push them in batches. This is a direct one-to-one mapping. Ensure you map the standard fields like email, first_name, and last_name accurately.

2. Data Enrichment (Companies, Tags, and Segments): Here is where we start using workarounds. Intercom treats Companies, Tags, and Segments as separate objects that link to a user. Tidio's API focuses heavily on the Contact object itself.

To migrate this data, you should "flatten" it. Instead of trying to create a "Company" object in Tidio, you should take the company name and ID from Intercom and update the Contact in Tidio with custom properties named company_name and company_id.

Similarly, for Tags and Segments, you should concatenate the list of tags an Intercom user has into a single string (e.g., "VIP, Lead, Q3_Campaign") and save that string to a custom property in Tidio called "Intercom_Tags". This allows you to filter users in Tidio based on their old Intercom labels.

3. Tickets: Once your contacts are established, you can move your Tickets. Intercom tickets map directly to Tidio tickets.

You will retrieve the ticket details from Intercom, including the title, description, and status. You then use the "Create ticket (as Contact)" endpoint in Tidio. This associates the ticket with the email address of the contact you migrated in step one.

4. Conversations and Notes: Migration of Conversations requires a clever approach. Tidio does not have an API endpoint to "insert" a historical chat message with a past timestamp into the live chat stream.

However, you do not want to lose that history. The solution is to convert Intercom conversations and Notes into Tickets in Tidio. For each conversation in Intercom, retrieve the full transcript.

Then, create a Ticket in Tidio where the "Subject" is "Archived Intercom Chat" and the "Body" contains the full text transcript of the conversation.

You can then mark this ticket as "Solved." This ensures the history is searchable and attached to the correct contact, even if it doesn't appear in the visual chat timeline.

Post Migration Configuration

With the raw data moved, you need to make the system usable. The first step is handling your Articles. Intercom has a robust Article system. Tidio offers Lyro, an AI chatbot.

While you can manually copy-paste articles into Tidio's knowledge base, a powerful modern approach is to use the Lyro "Upsert AI assistant data source" endpoint. You can feed the text of your Intercom articles directly into Lyro, allowing the AI to answer questions based on your legacy help content immediately.

Next, you must rebuild your Workflows. Intercom's automation rules do not transfer via API. You will need to enter the Tidio dashboard and recreate your welcome messages, auto-responders, and routing rules to match the logic you previously had in place.

Rollback and Validation

Migrations fail. Plan for it.

Before you start: Take a snapshot of your Tidio account state (contact count, ticket count) so you have a clean baseline. If your Tidio account is brand new, this is simple — everything created after migration start is migration data.

Validation checks after each phase:

• Compare contact counts: Intercom export total vs. Tidio contact total
• Spot-check 10–20 contacts to verify field mapping accuracy (email, name, custom properties)
• Verify that company_name and intercom_tags custom properties populated correctly on a sample set
• Compare ticket counts: Intercom export total vs. Tidio ticket total
• Spot-check ticket-to-contact associations — open a few tickets and confirm they are linked to the right contact
• Verify archived conversation tickets are marked as "Solved" and contain full transcripts
• Confirm Lyro can answer questions based on imported article content

If something goes wrong: Tidio's API supports contact deletion. If a batch imports corrupted data, you can delete those contacts and re-import. For tickets, you may need to use the Tidio dashboard to bulk-delete and retry. The key is catching problems early — validate after each migration phase, not at the end.

Insider Secrets

Having performed migrations like this, there are a few nuances that documentation rarely mentions.

Watch the Batch: When using Tidio's batch endpoint to create contacts, it operates on an "all or nothing" strategy. If you send a batch of 100 contacts and just one has a malformed email address, the entire batch of 100 will fail.

You must validate your Intercom data strictly before sending it, or write your script to retry failed batches one by one to identify the culprit.

The Timestamp Trap: When you create a Ticket or Contact in Tidio via API, the system often defaults the "Created At" timestamp to the moment of the API call, not the original date from 2021. To preserve your history, do not rely on the system timestamp.

Create a custom property called original_created_at and map the Intercom timestamp there. This gives your support team a reference point for how long a customer has actually been with you.

Search Latency: Intercom's API for searching contacts has a known delay; recently created contacts might not appear in search results instantly. If your migration script creates a user in Intercom (perhaps for testing) and immediately tries to read it back to send to Tidio, it might fail. Always build a slight buffer or delay into your testing scripts.

Post-Migration Checklist

• All contact counts match between source export and Tidio
• All ticket counts match between source export and Tidio
• Custom properties (company, tags, segments, original_created_at) are populated correctly
• Operators are set up and can log in
• Archived conversation tickets are searchable and linked to the right contacts
• Lyro is trained on imported article content
• Workflows (welcome messages, auto-responders, routing rules) are rebuilt and tested
• Intercom integrations (Slack, Salesforce, etc.) have been reconfigured in Tidio where applicable
• Team has been briefed on where to find historical data (archived tickets vs. live chat)

Summary

Migrating from Intercom to Tidio is a process of simplifying and restructuring. You are moving from a multi-object architecture to a streamlined, contact-centric model.

By moving your contacts first, flattening complex data like companies and tags into custom properties, and treating historical conversations as archived tickets, you preserve the integrity of your customer relationships.

The result is a clean slate in Tidio, populated with all the context your team needs to succeed.

Further reading:

• Intercom API Reference
• Tidio API Reference