The Complete Guide to Migrating from Tidio to Intercom

Switching customer support platforms is a significant milestone for any growing business. You are moving from Tidio, a tool great for immediate live chat and straightforward ticketing, to Intercom, a robust ecosystem designed for customer relationships and intricate automation.

This guide explores how to map your data effectively and ensure that your customer history remains intact during the Tidio to Intercom migration. By following a structured approach, you can maintain the context your support team needs to delight your users from day one.

Define Your Migration Scope

Before writing a single line of code or running a script, you must decide what data provides value and what constitutes digital clutter. Not everything can or should be migrated programmatically.

What to migrate via API: You should focus your automated efforts on the core data models that preserve customer context. This includes Contacts (your users and leads), Conversations (chat history), Tickets (complex support requests), and Tags (segmentation markers). These objects carry the historical weight of your relationship with your customers.

What to configure manually: The structural elements of your support organization usually require a human touch. Operators in Tidio map to Admins or Teammates in Intercom.

Since API endpoints often restrict the creation of users with administrative privileges for security reasons, it is best to invite your team members manually via the Intercom dashboard.

Similarly, Departments in Tidio should be manually recreated as Teams in Intercom to ensure your routing logic works correctly after the switch.

What to archive: Consider leaving behind very old data that no longer serves a purpose. For instance, Tidio allows you to delete contacts and tickets. If a contact has been inactive for years or a ticket was closed without resolution long ago, you might choose to export this data to a CSV for cold storage rather than cluttering your new Intercom workspace.

Pre-Migration Checklist

Before touching any API, walk through this list:

1. Audit your Tidio data. Count your contacts, conversations, tickets, and tags. Know the volume you are working with.
2. Purge dead data in Tidio. Delete or archive inactive contacts and resolved tickets that have no future value.
3. Invite all Admins in Intercom. Your team members must exist before you can attribute data to them.
4. Create Teams in Intercom. Map your Tidio Departments to Intercom Teams.
5. Define all custom Data Attributes in Intercom. Any Tidio property that doesn't have a standard Intercom equivalent must be created before import.
6. Build your operator-to-admin lookup table. Map every Tidio Operator ID to the corresponding Intercom Admin ID.
7. Set up a test environment. If your Intercom plan supports a sandbox or test workspace, run a small batch migration first before committing to production.
8. Back up everything. Export your full Tidio dataset to CSV before you start. This is your rollback safety net.

Prepare Intercom for Data Import

Successful data migration relies on preparing the destination environment to receive the data. You cannot import a conversation and assign it to an agent if that agent does not exist in Intercom yet.

Rebuild your team structure: Start by manually creating your Admins. In Tidio, you have Operators who handle inquiries. In Intercom, you must invite these users and assign them the appropriate roles.

Once your people are in place, you need to group them. Tidio uses Departments to organize operators. In Intercom, you should create corresponding Teams.

This mapping is vital because when you migrate historical conversations, you will want to attribute them to the correct teams and team members.

Define Data Attributes: Tidio uses properties to store specific details about a contact, such as their phone number or custom preferences. Intercom calls these Data Attributes.

While Intercom comes with standard fields, you must pre-define any custom attributes in Intercom that match your Tidio configuration. If you try to push data into a field that doesn't exist, the API may reject it or simply ignore that valuable context.

Entity Mapping Reference

This table summarizes how Tidio concepts translate to Intercom:

Migrate Objects

This section outlines the logical sequence for moving your data. You must respect the order of operations to maintain data integrity. You generally want to create the "owner" of the data before creating the data itself.

The high-level flow looks like this:

Tidio API ──Extract──▶ Transform ──Load──▶ Intercom API
                          │
                   ┌──────┴──────┐
                   │ Lookup Table │
                   │ (Operator →  │
                   │  Admin IDs)  │
                   └─────────────┘

Migration order:
  Contacts → Tickets → Conversations → Tags

1. Contacts: The foundation of your migration is the Contact object. In Tidio, contacts are identified by email or a unique ID and contain various properties. You will extract these contacts and map them to Intercom Contacts.

When moving contacts, pay close attention to the properties. Tidio allows you to update specific properties like name and email. You must map these to the equivalent attributes in Intercom.

If you have "Leads" in Tidio (visitors without full accounts), these will also become Contacts in Intercom, but you can define them with a specific role. Ensure you import the user_id or email correctly, as this will be the key used to link conversations later.

2. Tickets: Tidio handles complex inquiries as Tickets, often used for issues that cannot be resolved in a single chat session. Intercom now has a dedicated Tickets object as well.

You should iterate through your Tidio tickets and create corresponding tickets in Intercom. You will map the Tidio ticket title, description, and status (Open, Pending, Solved) to the Intercom Ticket fields.

It is crucial to associate the ticket with the correct Contact ID you created in Step 1. If the ticket in Tidio was assigned to a specific Operator, map that assignment to the corresponding Admin ID in Intercom.

3. Conversations: Migrating Conversations is the most complex part of the process. You first retrieve the message history for a contact from Tidio. You then recreate these conversations in Intercom.

A conversation is not just a block of text; it is a timeline. When you create the conversation in Intercom, you must ensure you are attributing the message to the correct source.

If the message came from the customer in Tidio, the author in Intercom must be the Contact. If the message came from a Tidio Operator, the author in Intercom must be the Admin.

You must also migrate the timestamps accurately so the conversation history appears in chronological order.

4. Tags: Finally, apply your segmentation. Tidio objects often have associated metadata or tags. Intercom uses Tags extensively to organize contacts and conversations.

You can iterate through your Tidio contacts and tickets, check for specific identifiers, and apply the corresponding Tag in Intercom.

Pseudocode: Migration Script Structure

Here is a simplified view of what your migration script should do:

# 1. Build the operator-to-admin lookup table
lookup = {}
for operator in tidio.get_operators():
    admin = intercom.find_admin_by_email(operator.email)
    lookup[operator.id] = admin.id
 
# 2. Migrate contacts
contact_map = {}  # tidio_contact_id -> intercom_contact_id
for contact in tidio.get_contacts():
    ic_contact = intercom.create_contact(
        email=contact.email,
        name=contact.name,
        custom_attributes=map_properties(contact.properties),
        created_at=contact.created_at  # preserve original timestamp
    )
    contact_map[contact.id] = ic_contact.id
 
# 3. Migrate tickets
for ticket in tidio.get_tickets():
    intercom.create_ticket(
        contact_id=contact_map[ticket.contact_id],
        title=ticket.title,
        description=ticket.description,
        status=map_status(ticket.status),  # Open/Pending/Solved
        admin_id=lookup.get(ticket.operator_id),
        created_at=ticket.created_at
    )
 
# 4. Migrate conversations
for contact_id in contact_map:
    messages = tidio.get_messages(contact_id)
    conversation = intercom.create_conversation(
        contact_id=contact_map[contact_id],
        body=messages[0].body,
        created_at=messages[0].timestamp
    )
    for msg in messages[1:]:
        if msg.author_type == "operator":
            intercom.reply_as_admin(
                conversation_id=conversation.id,
                admin_id=lookup[msg.author_id],
                body=msg.body,
                created_at=msg.timestamp
            )
        else:
            intercom.reply_as_contact(
                conversation_id=conversation.id,
                contact_id=contact_map[contact_id],
                body=msg.body,
                created_at=msg.timestamp
            )
 
# 5. Apply tags
for contact_id, tags in tidio.get_contact_tags():
    for tag in tags:
        intercom.tag_contact(
            contact_id=contact_map[contact_id],
            tag_name=tag
        )

Handling Failures Mid-Migration

Migrations break. Plan for it.

Contact import fails mid-batch: Your script should track which contacts have been successfully created in Intercom (the contact_map above). If the script crashes, you can resume from where you left off rather than re-importing everything. Duplicate detection by email or user_id is your safety net.

A conversation references a contact that wasn't imported: This will cause the API call to fail. Always validate that the contact exists in Intercom before attempting to create conversations for them. Log any orphaned conversations for manual review.

Rate limiter is more aggressive than expected: Intercom's rate limits can vary. Start with conservative delays between requests and adjust. A simple exponential back-off (wait 1s, then 2s, then 4s on repeated 429s) is more reliable than a fixed sleep duration.

Post-Migration Configuration

Once the raw data is moved, you need to reactivate the logic that powers your support.

Rebuild Workflows and Automation Tidio often uses bots or automated flows to handle initial interactions. Intercom uses Workflows (formerly Operator bot) to manage similar tasks.

You cannot migrate these via API. You must manually rebuild your routing rules, ensuring that new incoming conversations are sent to the correct Teams you created earlier.

Verify Custom Channel Events If you were using Tidio to track specific user actions, you might want to implement Custom Channel Events in Intercom. This allows you to notify Intercom when a user takes a specific action on your site, which can then trigger automation.

Post-Migration Verification Checklist

After the migration completes, verify these items before going live:

1. Contact count: Compare the number of contacts in Intercom against your Tidio export. Account for any contacts you intentionally excluded.
2. Conversation threading: Spot-check at least 20 conversations across different agents. Verify that messages appear in the correct chronological order and are attributed to the right author (Contact vs. Admin).
3. Ticket status mapping: Confirm that Open, Pending, and Solved statuses transferred correctly. Open a few tickets in the Intercom UI and verify the fields.
4. Tag application: Check that tags are applied to the correct contacts and conversations. Run a filtered search in Intercom for each tag and compare counts.
5. Custom Data Attributes: Verify that custom properties from Tidio appear correctly in the contact profiles in Intercom.
6. Timestamp accuracy: Pick several conversations with known dates and confirm the created_at values are correct — not defaulting to the migration date.
7. Team assignment: Verify that historical conversations are attributed to the correct Teams.
8. Workflow routing: Send a test conversation through each routing rule to confirm new inquiries reach the right team.

Common Pitfalls

This section covers the nuances that often trip up developers during a migration.

The Timestamp Trap: Both Tidio and Intercom rely heavily on Unix timestamps. However, when you create a conversation in Intercom, it might default to the "current" time unless you explicitly override the created_at field. If you forget this, years of history will look like they happened today.

Intercom is also strict about search queries involving dates — you generally cannot search for exact second-level matches, so plan your verification scripts to look for ranges rather than exact times.

Author Attribution is Critical: In Tidio, you have a list of Operators. In Intercom, you have Admins. These two systems will have different internal IDs for the same human being.

You must create a lookup table in your migration script. Without this, every historical reply from your support team will fail to import or be attributed to a generic bot user, destroying the personal context of the conversation.

Rate Limiting Strategy: Tidio's API documentation mentions batch updates for contacts to save requests. Use this. Updating contacts one by one will hit rate limits quickly.

Intercom also has rate limits. When running your script, implement a back-off strategy. If you receive a 429 status code (Too Many Requests), make your script pause and sleep for a few seconds before retrying. Here is a simple approach:

import time
 
def api_call_with_backoff(func, *args, max_retries=5):
    for attempt in range(max_retries):
        response = func(*args)
        if response.status_code == 429:
            wait = 2 ** attempt  # 1s, 2s, 4s, 8s, 16s
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")

Handling Viewed Pages: Tidio tracks the pages a visitor viewed. While you can technically migrate this as a Note or a Data Event in Intercom, experience suggests this is often noise.

Migrating thousands of "Page Viewed" events for old sessions clogs up the Intercom timeline. It is often smarter to only migrate the viewing history for active, open tickets and leave the rest behind.

Summary

Migrating from Tidio to Intercom is a shift from a chat-focused tool to a relationship-focused platform.

By defining your scope early, manually preparing your team structure, and meticulously mapping your Contacts, Tickets, and Conversations, you ensure that your team steps into Intercom with a full picture of their customers.

Pay close attention to author mapping and timestamps, and run through the verification checklist before going live.

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:

• Intercom API Reference
• Tidio API Reference