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.

Data Mapping Overview

Before diving into the details, here's a high-level view of how Zendesk objects map to Tidio:

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. The Tidio ticket reply endpoint does not support direct file uploads, so 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)

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 defined in the Tidio documentation.

Validate the Migration

Once data transfer completes, you need to verify that the migration was accurate before cutting over to production use.

• Record Count Comparison: Compare total counts for each object type — Users vs. Contacts, Tickets vs. Tickets, Comments vs. Replies — between Zendesk and Tidio. Any discrepancy signals dropped records that need investigation.
• Spot-Check Sampling: Pull a random sample of tickets (we recommend at least 5% or 50 tickets, whichever is larger) and manually compare the full conversation thread, attachment links, custom field values, and requester assignment against the Zendesk originals.
• Custom Property Verification: Confirm that Organization data flattened into Contact Properties is correctly populated. Check edge cases: contacts with multiple organization memberships, contacts with empty or null custom fields.
• Status and Assignment Audit: Verify that ticket statuses mapped correctly and that operator assignments match the intended Zendesk agent-to-Tidio operator mapping.

Error Handling and Recovery

Migrations at scale will encounter failures. Plan for them rather than hoping they don't happen.

• Idempotent Operations: Design your migration scripts so that re-running a step doesn't create duplicates. Since Tidio's Create contact always creates a new record even on email match, your script must check for existing records before creating new ones. Use the Create or Update User or Update Multiple Contacts approach to prevent duplication on retry.
• Failure Logging: Log every failed API call with the source record ID, the error response, and the payload. This lets you retry only the failed records rather than re-running the entire batch.
• Partial Recovery: If ticket creation fails midway, your script should be able to resume from the last successfully created record. Maintain a checkpoint file or database table that tracks which Zendesk IDs have been successfully migrated.
• Rate Limit Handling: Zendesk enforces rate limits on bulk operations, sometimes limiting requests per minute. When you hit an HTTP 429 response, implement exponential backoff rather than fixed delays. Use bulk endpoints (like Create Many Users or Update Many Tickets) to reduce total API calls.

Data Privacy Considerations

Transferring customer data between two SaaS platforms involves moving PII across systems, which carries compliance obligations.

• Data Processing Agreements: Ensure you have valid DPAs in place with both Zendesk and Tidio that cover the data transfer.
• Consent and Legal Basis: Confirm that your existing legal basis for processing customer data (consent, legitimate interest, or contractual necessity) covers the transfer to a new platform.
• Data Minimization: Use the migration as an opportunity to audit what you're transferring. Not all historical data needs to move — consider excluding records beyond your retention period or data you no longer have a legitimate purpose to process.
• Secure Transfer: Ensure all API calls use HTTPS and that any intermediate storage (for attachments or staging data) is encrypted at rest.

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.

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, followed by thorough validation to confirm data integrity.

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.

Further reading

• Tidio API Reference
• Zendesk API Reference