The Complete Guide to Migrating from Tidio to Freshdesk

Moving your support operations to a new platform like Freshdesk is a significant undertaking that requires careful planning.

If you are currently relying on Tidio for managing your customer interactions, planning a methodical migration is key to retaining valuable historical data and ensuring a smooth transition for your team.

This guide walks you through every step, focusing on leveraging the application programming interfaces for a data-rich migration from Tidio to Freshdesk.

Define Your Migration Scope

A successful migration hinges on understanding which data elements move smoothly (via direct mapping), which require translation (API workarounds), and which must be configured manually in the new environment.

Migrated via Direct API Mapping: These core entities have direct counterparts in Freshdesk and can be transferred efficiently once preparatory steps are complete.

• Contacts: Tidio's contacts, which represent identified visitors who interacted with the widget, map to Freshdesk Contacts.
• Operators (Agents): Your Tidio agents, or operators, who handle real-time customer interactions, transition into Freshdesk Agents.
• Departments (Groups): Tidio organizes agents into Departments, which correlate directly with Freshdesk Groups, allowing you to maintain your team structure.
• Tickets: The primary support records in Tidio translate directly to Freshdesk Tickets.

Migrated via API Workaround/Transformation: These objects exist in both systems but require data manipulation or mapping to different concepts in Freshdesk to retain context.

• Contact Custom Properties (Schema): Tidio allows for custom properties to be defined on contacts. These must be first defined as custom fields in Freshdesk before the actual contact data can be imported.
• Conversations/Messages: The stream of messages within a Tidio contact's conversation, originating from contacts, operators, or chatbots, needs to be converted into specific conversation types in Freshdesk (like public Replies or private Notes).
• Viewed Pages History: The history of pages viewed by identified contacts in Tidio (available for the past 30 days), must be restructured as Omnichannel Activities for publication onto the Freshdesk contact timeline, providing valuable context for agents.

Not Migrated: Some Tidio configurations and features have no API-accessible equivalent in Freshdesk and cannot be transferred automatically. Being upfront about these losses helps you plan:

• Chatbot flows and automation logic built in Tidio's visual builder
• Widget customizations (colors, positioning, branding)
• Email template designs
• Canned responses (must be recreated manually in Freshdesk)

Manual Configuration: Settings, workflows, and rulesets cannot be automatically imported via API and must be rebuilt directly within the Freshdesk admin interface after the data migration is complete.

Prepare Freshdesk for Data Import

Before moving mass volumes of customer data, you need to lay the foundation in Freshdesk. This initial setup ensures that the incoming Tidio data lands in the correct format and locations.

The most critical preparatory phase involves replicating your custom data structure. Retrieve the complete list of properties and their associated types from Tidio. Since Freshdesk mandates that custom fields exist before data import, you must use the administrative API to create matching Contact Fields in your Freshdesk instance. This step guarantees that all the valuable contextual data gathered in Tidio moves with your customer profiles.

Migrate Objects

The actual data movement must be executed in a specific, logical sequence due to object dependencies. For instance, you cannot assign a ticket to an agent or put a contact in a group unless those entities already exist in Freshdesk.

Key Field Mappings

Before executing the migration, use this reference for how core Tidio fields translate to their Freshdesk equivalents:

Step 1: Establishing Support Structure (Groups and Agents)

We begin by establishing the team structure. First, retrieve your list of Departments from Tidio.

You can then create these as Groups within Freshdesk. Next, pull all Operators data from Tidio. These correspond directly to Agents in Freshdesk and can be created in bulk.

Ensure that these new Agents are associated with the corresponding Groups defined earlier.

Step 2: Migrating Contacts (Customer Records)

Using Freshdesk's bulk creation or import mechanisms, ingest all contacts retrieved from Tidio. Map Tidio's standard fields (name, email, phone) directly to Freshdesk's primary contact attributes.

Crucially, during this step, ensure that the values stored in the Tidio Contact Custom Properties are mapped precisely to the custom contact fields you prepared earlier in Freshdesk.

Step 3: Importing Tickets (Support History)

With agents and contacts in place, we move the tickets. Retrieve the list of all Tidio Tickets.

Use the Freshdesk API to Create a Ticket for each record. When creating the tickets, be sure to pass along standard ticket data, including the associated customer (Requester ID) and any agent (Responder ID) or group assignments, using the IDs established in the previous steps.

Map statuses and priorities to the corresponding numerical values supported by Freshdesk (see the field mapping table above).

Step 4: Rebuilding Conversations and Messages

This is perhaps the most detail-oriented step. We must take the chronological communication stream from Tidio and fit it into Freshdesk's structured conversation format.

Pull the specific message history associated with each ticket or contact from Tidio.

• For public-facing customer and agent messages, recreate these items sequentially in Freshdesk using the Create a Reply functionality against the corresponding ticket ID.

• For internal chat operator notes or chatbot actions, recreate these as Notes in Freshdesk, carefully marking them as private if they should not be visible to the customer.

Step 5: Contextual Data: Viewed Pages History

Finally, load auxiliary data that enriches the contact profile. The log of pages a contact viewed in Tidio provides vital context for support agents.

In Freshdesk, leverage the Omnichannel Activities API to publish this web activity history directly onto the contact's timeline.

This ensures that your agents have a rich, integrated view of the customer's journey leading up to their support request.

Edge Cases and Error Handling

Real migrations hit problems that conceptual guides gloss over. Here are the common failure points and how to handle them:

• Duplicate contacts: Tidio contacts may share an email address, but Freshdesk enforces unique emails per contact. Before importing, deduplicate your contact list. Decide whether to merge conversation history into the surviving record or flag duplicates for manual review.
• Contacts without email addresses: Freshdesk requires either an email or phone number to create a contact. Tidio contacts identified only by browser session or name cannot be imported as-is. You'll need to either skip these records or assign a placeholder identifier.
• Tickets with deleted operators: If a Tidio operator who was assigned to tickets has since been removed, those tickets will fail to import if you try to set a responder_id that doesn't exist. Import these tickets without an assignee, or reassign them to a catch-all agent.
• Attachment handling: File attachments on Tidio messages need to be downloaded and re-uploaded to Freshdesk. Large attachments may hit Freshdesk's file size limits depending on your plan. Check Freshdesk's documentation for current limits and plan accordingly.
• Ticket custom fields: If you use custom fields on tickets in Tidio (not just contacts), those fields must also be pre-created in Freshdesk before ticket import—the same pattern as contact custom properties.

Post-Migration Validation

A migration without validation is a gamble. Run these checks systematically before declaring the migration complete:

• Record counts: Compare the total number of contacts, tickets, and conversations in Tidio against what landed in Freshdesk. Any discrepancy above zero needs investigation.
• Spot-check relational integrity: Pick a sample of tickets and verify the requester, assignee, and group associations are correct. Broken ID mappings tend to surface here.
• Custom field verification: Filter contacts and tickets by custom field values in Freshdesk to confirm data populated correctly. Empty custom fields on records that had values in Tidio indicate a mapping failure.
• Conversation ordering: Open several migrated tickets and confirm that replies and notes appear in the correct chronological sequence. Timestamp mishandling shows up as jumbled conversation threads.
• Rollback plan: If validation reveals systemic issues (wrong contact associations, missing ticket batches), you need a path back. Before starting the migration, document which Freshdesk objects were created by the import process so they can be identified and deleted cleanly via the API if a re-run is necessary.

Post Migration Configuration

Once the data is securely migrated, several key functional configurations must be rebuilt manually to ensure your helpdesk operates efficiently. While the data moved via API, the system logic remains in Freshdesk.

You will need to manually recreate your:

• SLA Policies: Define the time-based targets for response and resolution for different priority levels and customer segments.
• Scenario Automations: Rebuild quick-action automations that help agents manage routine updates to tickets.
• Ticket Rules (Automations): Recreate business logic that runs on ticket creation, update, or hourly triggers (like assigning tickets or sending notifications).

Technical Considerations

Having successfully navigated this type of migration, here are critical points to keep in mind for smooth execution and data fidelity:

• Mind the Rate Limits: Freshdesk imposes API rate limits per minute that vary by subscription plan. Even invalid requests count toward this limit. Design your integration to process data in batches with exponential backoff and retry logic to handle HTTP 429 responses gracefully. Check Freshdesk's rate limiting documentation for the specific limits on your plan.
• ID Mapping is Everything: As you migrate Groups, Agents, and Contacts, meticulously store the mapping of the original Tidio IDs to the new Freshdesk IDs. This cross-reference table is crucial later on, especially when updating the relational fields in the massive volume of ticket and conversation data. Without accurate ID mapping, associating history and replies to the correct records becomes impossible.
• Handle Timestamps Carefully: Both systems rely heavily on timestamps for sequencing events. Ensure that all creation (created_at) and update (updated_at) timestamps from Tidio are correctly formatted and migrated in UTC (Coordinated Universal Time) to maintain historical accuracy in Freshdesk.

Summary

Migrating from Tidio to Freshdesk is a multi-phase process involving foundational setup, phased data transfer, and thorough validation.

By addressing the schema (Custom Properties) first, followed by hierarchical data (Groups and Agents), and finally moving transactional data (Tickets and Conversations), you ensure dependencies are met in the correct logical sequence.

Leveraging Freshdesk's specialized tools, like Omnichannel Activities, allows you to preserve the full context of your customer interactions, setting your team up for success in their new support platform.

Further reading

• Tidio API Reference
• Freshdesk API Reference
• Freshdesk Rate Limiting