The Complete Guide to Migrating from Zendesk to Tidio

Moving from one robust platform like Zendesk to another like Tidio is a significant undertaking, but it promises a fresh start for your customer support operations.
Zendesk provides comprehensive ticketing, knowledge base, and user management tools. Tidio focuses heavily on real-time communication (Contacts and Conversations) and ticketing.

Successfully bridging these systems requires more than simple data export; it demands intelligent data mapping and strategic phased execution.

This guide will walk you through this process, focusing on which of your previous platform's data models translate to the new environment and how to handle the inevitable differences.

Define Your Migration Scope

Not every historical data point is portable, and often, non-core logic must be recreated manually in the target system. Our scope defines three paths for your Zendesk assets: API migration, manual configuration, and archival.

Data Migrated via API (Requires Scripted Transformation): The core operational data that powers daily support needs can typically be moved using APIs, although complex transformations are necessary to match the data models:

1. Users (End users) map to Contacts. Zendesk users can be massive, detailed records. Tidio accepts new contacts via batch endpoints, requiring at least an email, first name, last name, or phone number.
2. User Fields (Custom) translate into Contact Properties. Zendesk allows complex user fields (like dropdowns, dates, and text fields). These fields must be migrated as custom properties on the corresponding Tidio Contact records.
3. Organizations migrate as Contact Properties/Metadata. Zendesk treats organizations as distinct entities with custom fields, ownership, and ticket sharing rules. Since a dedicated Organization object API is not present in the Tidio tools provided, this data will be mapped to custom properties or internal notes on the relevant Tidio Contacts.
4. Tickets (Core Data) migrate to Tickets. Basic ticket information (subject, requester, priority, status) can be transferred, usually via a bulk or batch creation process in Tidio.
5. Ticket Comments migrate to Ticket Replies/Messages. The sequential history of communications on a Zendesk Ticket (pulled from ticket audits or list comments endpoints) needs to be carefully logged as replies on the newly created Tidio Tickets.
6. Attachments (on Tickets) require a workaround. Zendesk links attachments to ticket comments using file URLs or upload tokens. Since the Tidio ticket reply mechanism may not directly support embedding large files via API, attachments must be extracted from Zendesk (using `content_url`) and stored externally, with links inserted into the migrated ticket messages in Tidio.

Configuration Rebuilt Manually (Non-Data Migration): Structural and workflow elements rarely transfer well and require administrative setup in Tidio:

1. Agents / Administrators (Staff) must be manually onboarded or provisioned as Operators in Tidio. The API only allows retrieving lists of existing operators, not creating them in bulk.
2. Groups must be manually rebuilt as Departments in Tidio. Tidio supports the retrieval of Department IDs and names, implying creation is a manual configuration step.
3. User Fields / Organization Fields (Schema): Although we transfer the values of custom fields via API, the custom field structure itself (the schema defining fields for contacts/organizations) must be set up manually in Tidio before importing the corresponding data.
4. Custom Ticket Statuses: Zendesk allows custom statuses tied to status categories (e.g., "new," "open," "solved"). These workflow statuses must be recreated and mapped to the appropriate Tidio statuses manually.

Data to be Archived (Historical/Non-Core): Due to the limited API structure available for import or irrelevance to Tidio's core offerings, these complex historical and auxiliary objects should be preserved in your deprecated Zendesk environment or exported to cold storage:

1. Help Center Content (Categories, Sections, Articles, Translations): The complex hierarchical structure of Zendesk Guide (Categories containing Sections, containing Articles) has no visible import pathway to Tidio, requiring manual migration if a knowledge base exists there.
2. Article Comments/Labels/Attachments: These elements tied to knowledge management are managed via the Help Center API and must be manually recreated alongside the articles.
3. Ticket Forms / Dynamic Ticket Fields: Zendesk uses Ticket Forms and Ticket Fields to control agent and end user experience, including conditional field logic. This deep configuration data is strictly operational within Zendesk and must be manually rebuilt in Tidio if equivalent functionality exists.
4. Audit Logs / Ticket Metrics / Events: Detailed historical logs, metric events (like reply time and resolution time calculations), and user activity events (Sunshine Events) are typically retained in the source system for compliance and historical reporting, as importing granular event timelines into the target system is highly complex or impossible.

Prepare Tidio for Data Import

Before migrating any interaction data, you must establish the foundational structure in Tidio to receive the imported data.

1. Create Staff and Teams: Begin by manually creating all necessary Operators (your agents) within Tidio, as their IDs are crucial for correctly assigning historical tickets and communications. Simultaneously, replicate your Zendesk Groups as Departments in Tidio.
2. Configure Custom Fields (The Schema Mapping): For every custom field you have attached to Users and Organizations in Zendesk (e.g., a "Membership Tier" field on a User or a "Contract Start Date" on an Organization), you must manually create a corresponding custom property in Tidio. This upfront creation is critical because later steps rely on updating these pre-defined Tidio Contact Properties.

Migrate Objects

The actual transfer of data must follow a strict logical sequence to ensure data integrity, especially related to dependencies.

1. Migrate Users (End Users) and Their Identities
   
   You must bring over every unique user who has ever interacted with your Zendesk system. In Tidio, these become Contacts.
   
   Use Tidio's batch creation capability to create multiple contacts efficiently. Since Tidio requires at least an `email`, `first_name`, `last_name`, or `phone`, ensure you map one of the user's identities to meet this requirement.
   
   Once the basic contact records exist in Tidio, use the contact update process to populate their custom properties using the data extracted from the Zendesk `user_fields` and `organization_fields` associated with the user.
   
   
2. Migrate Organizations and Relationships
   
   Since Tidio doesn't natively expose an "Organization" object equivalent via the documented API, the organizational hierarchy is preserved as attributes attached to the Contacts.
   
   This relational data must be flattened and converted into custom properties on the Tidio Contact records.
   
   For instance, an organization name from Zendesk is written as a custom property on every associated Tidio Contact, ensuring the relationship is retained even if the object model differs significantly.
   
   
3. Migrate Tickets (Core Data)
   
   Tickets represent the chronological container for the customer service request.
   
   Utilize the `Create ticket (as Contact)` endpoint in Tidio. Critical mapping occurs here: The Zendesk requester ID must be linked to the newly created Tidio Contact ID from Step 1. You must map the complex Zendesk status (which might include custom statuses that fall into status categories like "open" or "solved") to the closest available status in Tidio.
   
   
4. Migrate Ticket Conversation History (Comments and Replies)
   
   Conversation history provides the context for each ticket and must follow the parent ticket established in Step 3.
   
   For each comment, determine the author (which must match an existing Tidio Operator or Contact ID) and the body content. Use the `Reply to a ticket` endpoint to append these historical messages sequentially to the newly created Tidio Tickets.
   
   
5. Handling Attachments
   
   If a comment contains an attachment, the file must be downloaded using the Zendesk `content_url` and either uploaded elsewhere or linked directly within the body of the message sent to Tidio, since a direct upload method within the `Reply to a ticket` workflow is not clearly defined in the available Tidio documentation.

Post Migration Configuration

Once the raw data is migrated, the system needs configuration to start functioning properly in a production environment. These elements are primarily controlled manually within the Tidio interface.

• Workflows and Business Rules: Zendesk relies heavily on triggers, automations, and macros to manage ticket flow and agent efficiency. These sophisticated rules cannot be automatically transferred via API; they must be rebuilt manually within the Tidio platform to replicate your custom support processes.
• Reporting and Dashboards: Custom reports, views (filtered lists of tickets), and metrics derived from Zendesk’s rich historical data models (like Ticket Metrics or detailed Audit Logs) must be recreated using Tidio’s reporting tools to ensure continuity in performance monitoring.
• Knowledge Base Recreation: The content structure of your Help Center, including Categories, Sections, and Articles, must be manually recreated in Tidio, as no programmatic migration path is provided for this content, maintaining the integrity of your customer self-service library.

Insider Secrets

Having successfully executed these types of migrations before, there are a few nuances to bear in mind for a smoother transition:

• The Timestamp Challenge for Threading: While creating replies in sequence is critical, accurately preserving the original authorship and precise timestamp in a new system can be complicated. You must ensure the Tidio API allows overriding creation timestamps or utilize custom fields to log the original Zendesk `created_at` and `author_id` to maintain historical accuracy for agents referencing old conversations. This often requires custom metadata fields on the replies themselves.
• Handling User Duplication: Zendesk manages multiple identities per user gracefully. When creating Tidio Contacts, always attempt to match users based on primary email or external ID first. Since Tidio's `Create contact` function always creates a new record even if `email` or `distinct_id` matches, you should use the `Create or Update User` or the `Update Multiple Contacts` approach after initial creation passes to ensure consolidation of identities.
• Ticket ID Preservation: Although the API automatically generates new IDs in Tidio, it is extremely valuable to save the original Zendesk Ticket ID in a designated custom field within the new Tidio Ticket. This allows cross-referencing old audit trails or communicating legacy ticket numbers when necessary.
• Rate Limit Management: Zendesk enforces rate limits, particularly on bulk operations and incremental exports, sometimes limiting requests per minute or per user. Careful, paced iteration and liberal use of bulk endpoints (like `Create Many Users` or `Update Many Tickets`) are essential to avoid HTTP 429 errors and complete the migration efficiently.

Summary

The migration journey from Zendesk to Tidio centers on moving Users (Contacts), Organizations (Contact Attributes), and Tickets (with conversation history).

Success hinges on meticulous preparation in Tidio (setting up Operators and custom property schemas) before engaging in the scripted data transfer.

Elements outside the core ticketing function, particularly knowledge base content and complex workflow automation logic, necessitate manual recreation, marking them as key tasks in your post-migration checklist.

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

• Tidio
• Zendesk