The Complete Guide to Migrating from Tidio to Help Scout

Moving customer support data between platforms can feel daunting, but with a thoughtful plan, you can ensure your transition from Tidio to Help Scout is smooth and complete.

Tidio is excellent for real-time chat, but when you transition to Help Scout, you are leveraging its robust conversation management system.

This guide details a structured approach for migrating your help desk, ensuring nothing is left behind or overlooked during this essential process.

Define your migration scope

Here is a breakdown of what falls into each migration category and how to handle it:

Migrated via API (Core Data):

The vast majority of your core customer data can and should be moved using the API.

This includes Contacts and their associated data. Tidio contacts, identified by their email, name, or phone number, can be retrieved along with their customized data properties.

These seamlessly map to Help Scout's Customers and their corresponding properties. Crucially, all Tickets and Conversation Messages must be migrated via API.

Tidio tickets, which often include complex or lengthy interactions with operators, must be pulled and restructured into Help Scout's Conversations and Threads.

Configured Manually (Structural Data):

Structural components, which are essential for Help Scout's operational flow, require manual creation and mapping before data migration begins.

This includes Tidio's Departments, which need to be rebuilt as Help Scout Inboxes or Teams. Similarly, Tidio's Operators must be manually created as Help Scout Users or Team Members, even though you can retrieve the full list of operators via the Tidio API.

This initial manual setup ensures the migrated conversations are assigned to the correct teams and agents.

Workaround Manual Migration (Contextual Data):

Some contextual data requires a combination of API retrieval and manual appending. For instance, Viewed Pages History, which Tidio captures for contacts over the last 30 days, lacks a direct ingestion endpoint in Help Scout for historical activity.

This information can be retrieved via the Tidio API but must be added manually as notes or metadata to the corresponding Customer or Conversation records in Help Scout.

Archived/Excluded Data:

Tidio-specific configuration objects, such as Project Info or the data related to Lyro and Product Recommendations, are proprietary features that do not map to Help Scout and should generally be archived on the Tidio side or excluded entirely from the migration scope.

Entity mapping reference

Before diving into the migration steps, here is a canonical mapping of how Tidio objects translate to Help Scout:

Tidio Entity	Help Scout Entity	Migration Method	Notes
Contacts	Customers	API	Match on email to avoid duplicates
Contact Properties	Customer Properties	API (after manual field setup)	Define custom fields in Help Scout first
Tickets	Conversations	API	Reconstruct full thread history
Messages	Threads	API	Map to Customer Thread, Reply Thread, or Chat Thread based on sender
Departments	Inboxes / Teams	Manual	Create before migrating conversations
Operators	Users / Team Members	Manual	Maintain ID mapping table
Tags	Tags	API / Manual	Recreate tag taxonomy in Help Scout, then apply during conversation import
Attachments	Attachments	API	Download from Tidio, re-upload to Help Scout threads
Viewed Pages History	Customer Notes / Metadata	Workaround	Only last 30 days available from Tidio
Lyro / Product Recommendations	N/A	Excluded	Proprietary Tidio features with no Help Scout equivalent
Project Info	N/A	Excluded	Archive on Tidio side

Prepare Help Scout for data import

Before initiating any data transfer, you must establish the foundational structure in Help Scout.

1. Establish Agent and Team Identities:

Start by setting up your team. While the Tidio API allows you to retrieve a complete list of Operators, you will need to manually create these accounts in Help Scout.

Once created, keep a secure map connecting the old Tidio Operator IDs to the new Help Scout User IDs. Next, review the Departments retrieved from Tidio and manually configure the corresponding Inboxes and Teams in Help Scout.

This mapping ensures conversations are routed correctly upon import.

2. Define Custom Customer Properties:

Customer property fields in Tidio, which can be defined by specific types like text, email, or number, must be defined in Help Scout before importing contact data.

Use the Tidio API to retrieve the complete list of defined Contact Properties. Then, manually create the matching Customer Property Definitions in Help Scout.

This preparation prevents data loss during the transfer of contact details.

3. Recreate Tags:

If you use tags in Tidio to categorize tickets, create the corresponding tag taxonomy in Help Scout before importing conversations. This way, tags can be applied during the conversation creation step rather than requiring a second pass.

Migrate objects

The migration should proceed in a strictly logical sequence, ensuring that foundational objects (Customers) exist before relational objects (Conversations) are created.

1. Customer Data Model (Contacts):

Tidio defines Contacts as site visitors identified by information such as email, name, or phone. These contacts can be retrieved in batches or individually.

You can also update them individually or in groups. In Help Scout, these Tidio Contacts become Customers.

We utilize the Help Scout Customer endpoints to create new customers or update existing ones, transferring the core demographic data and the previously mapped custom properties.

It is vital to use the available bulk creation and update endpoints for efficient data transfer, given the Help Scout rate limits you will encounter.

2. Conversation Data Model (Tickets and Messages):

This is the most intricate phase. In Tidio, a complex customer interaction is recorded as a Ticket. You can retrieve a ticket's details, including the full message history, using the Tidio API.

Conversations also include messages exchanged between the contact and operators or chatbots.

For each Tidio Ticket, you must create a new Conversation object in Help Scout. The real work lies in reconstructing the message history.

The Tidio messages (retrieved via the ticket details or contact messages endpoints) must be transformed into Help Scout Threads.

• If the original message was from the customer, it becomes a Customer Thread.
• If it was a reply from an agent, it becomes a Reply Thread.
• If the conversation originated as a real-time chat, you might use a Chat Thread to maintain that context.

You must map the original Tidio Operator ID to the new Help Scout User ID to correctly attribute the replies within the thread. Information like ticket status, priority, and assignment retrieved from Tidio must be reflected when creating or updating the Help Scout Conversation.

3. Attachments:

Tickets often include file attachments — screenshots, documents, logs. These must be downloaded from Tidio and re-uploaded to the corresponding Help Scout thread. Handle attachments as part of the thread creation step: for each message that contains an attachment, download the file, then include it in the Help Scout thread creation request. Watch for file size limits on the Help Scout side.

Post Migration Configuration

Once the historical data is safely loaded into Help Scout, you must rebuild the operational structure and automation manually.

Workflows and Automation: Help Scout allows for defining Workflows to automate tasks based on conversation triggers. Any automated actions, routing rules, or organizational processes that were present in Tidio (such as auto-replies or conditional assignments) must be recreated manually as new Workflows in the Help Scout platform.

Saved Replies: If your Tidio operators utilized canned responses, you must manually recreate these as Saved Replies in Help Scout. While the Help Scout API allows listing, creating, and updating Saved Replies, the text and structure of these responses must be ported over by your team.

Security and Permissions: Any specific operator permissions or security settings defined in Tidio need to be replicated manually within the Help Scout administrative interface.

Validation and QA

A migration is not complete until you have verified the data landed correctly. Without a validation pass, you are flying blind.

• Record count comparison: After migration, compare total counts of Customers, Conversations, and Threads in Help Scout against source counts from Tidio. Any discrepancy signals dropped records that need investigation.
• Spot-check thread ordering: Pick a sample of conversations (especially long, multi-message tickets) and verify that messages appear in the correct chronological order with the correct sender attribution.
• Custom property integrity: For a random sample of migrated customers, confirm that all custom property values transferred accurately — check for truncation, encoding issues, or type mismatches.
• Attachment verification: Confirm that attachments are accessible and correctly linked to their parent threads. Broken or missing attachments are easy to miss in bulk migrations.
• Assignment and routing: Verify that conversations are assigned to the correct Help Scout users and inboxes based on your ID mapping table.

Contingency and rollback planning

Migrations can fail partway through. Plan for it.

• Idempotent scripts: Design your migration scripts so they can be re-run safely. Use your ID mapping table to skip records that have already been migrated. This lets you resume from the point of failure rather than starting over.
• Batch checkpointing: Log progress after each batch. If the migration stalls at record 47,000 out of 80,000, you need to know exactly where to pick up.
• Help Scout cleanup: If you need to roll back, Help Scout's API supports deleting Conversations and Customers. Have a cleanup script ready that can remove migrated records using the IDs stored in your mapping table.
• Parallel operation: Consider running both Tidio and Help Scout in parallel during the migration window. Route new incoming conversations to Help Scout while migrating historical data. This avoids downtime and gives your team a fallback if something goes wrong.

Common pitfalls

Knowing where the subtle complexities lie ensures a smooth transition beyond the basic transfer steps.

• ID Mapping is Non-Negotiable:

The relationship between Operators and Departments in Tidio and Users and Inboxes in Help Scout is critical.

You must maintain a master lookup table that permanently links the old Tidio IDs (for operators, contacts, and departments) to the new Help Scout IDs (for users, customers, and inboxes).

Without this map, you cannot accurately link conversations to their historical owner.

• Managing Rate Limits:

Help Scout imposes rate limits on API requests when migrating large volumes of Contacts or Tickets. You must build exponential backoff and retry logic into your migration scripts.

Ignoring the rate limits will lead to HTTP 429 error responses, potentially stalling your migration for extended periods. Monitoring the X-RateLimit-Remaining header is essential to pacing your transfer.

• Handling Tidio Contact Duplicates:

When retrieving contacts from Tidio, recognize that creating a new contact in Tidio will always add a new record, even if the email or distinct ID exists, meaning no data is overwritten.

When moving to Help Scout, you must develop a strategy for merging these potential duplicates into a single Customer record, likely prioritizing unique identification via email address.

Help Scout offers endpoints to create new customers or overwrite existing ones, giving you the control necessary to manage merging contact histories.

• Viewed Pages Context:

Remember that Viewed Pages History only covers the last 30 days in Tidio. If you require older browsing history, you may need a separate archival method.

For the recent data, pull it alongside the contact data and structure it as a clean note or metadata field within the Help Scout Customer record to maintain valuable context for agents.

• HTML vs Plain Text Formatting:

Tidio messages may contain HTML formatting, while Help Scout threads expect a specific format depending on thread type. Ensure your migration scripts handle content type conversion correctly — stripping or preserving HTML as appropriate — to avoid garbled message content in Help Scout.

Summary

Migrating from Tidio to Help Scout is an organized process that relies on careful preparation and methodical API transfer.

By first establishing your core organizational structure (Users and Inboxes) and defining custom fields, you pave the way for a smooth transfer of bulk data.

The successful migration hinges on accurately mapping Tidio Contacts to Help Scout Customers and reconstructing Tidio Tickets and Messages as sequential Help Scout Conversations and Threads.

By paying close attention to these data models and managing technical details like ID mapping and API rate limits, you ensure a complete transition of your valuable customer support history.

Further reading

• Help Scout API Documentation
• Tidio API Reference