The Complete Guide to Migrating from Tidio to Zendesk

Tidio has served its purpose, but transitioning to Zendesk gives you access to more powerful ticketing, automation, and reporting capabilities. Moving your customer service infrastructure is a significant step — one that requires careful planning, especially when handling complex historical data like conversations and customer attributes.

This guide covers the technical methodology for migrating from Tidio to Zendesk, including object mapping, API sequencing, validation, and the pitfalls we've seen trip people up.

Migration Mapping Reference

Before diving into the steps, here's the core object mapping between the two platforms:

Define Your Migration Scope

Not every bit of historical data needs an active new home, and deciding what moves where is the crucial first step.

The majority of your operational data can and should be moved programmatically to maintain fidelity and scale:

1. Contacts (End Users) & Operators (Agents): These map directly to Zendesk's Users. Zendesk allows bulk creation or updating of users, identifying them by email or external ID. Tidio's user attributes like name, email, and phone number transition seamlessly.
2. Departments (Groups): Tidio departments, which organize your agents, translate naturally into Zendesk Groups.
3. Custom Properties (User/Organization Fields): Custom data fields attached to contacts in Tidio must be recreated in Zendesk as custom User Fields or Organization Fields before the customer records are imported.
4. Tickets: Tidio Tickets become Zendesk Tickets.
5. Contact Messages (Ticket Comments/History): The chronological chat log from Tidio (Contact Messages) becomes the internal history within a Zendesk ticket, captured as sequential Ticket Comments or audit events.
6. Viewed Pages History (Events API): Tidio records pages viewed by contacts. This non-conversational behavioral data can be imported into the Zendesk platform using the Events API, storing it as custom events tied to the user profile (Sunshine Events). Note: Sunshine Events require a Zendesk Suite Professional plan or higher.

Certain functional elements cannot be migrated directly and require manual configuration within the new Zendesk environment:

• Business Rules (Triggers, Automations, and Macros): Complex logic, like routing based on Tidio Departments or custom fields, must be analyzed and rebuilt using Zendesk's native Triggers and Automations.
• Ticket Forms and Custom Statuses: While Zendesk supports Custom Ticket Statuses and Ticket Forms, the structure and conditional logic must be manually reconstructed within the Zendesk admin center to ensure your new workflow is maintained. Custom Ticket Statuses require Zendesk Suite Growth or higher.

Evaluate temporary chat sessions or unassigned communication threads that are old or purely informational. Archiving or permanently deleting this noise can accelerate the migration and ensure a clean start in Zendesk.

Prepare Zendesk for Data Import

Before moving any core customer or ticket data, you must establish the structural groundwork in Zendesk.

1. Map and Create Custom Fields: First, recreate any unique data points captured in Tidio as custom properties in Zendesk. Define these properties as User Fields or Organization Fields. This step is critical because incoming user and ticket data will reference these fields.
2. Establish Groups: Replicate your Tidio organization structure by creating Groups in Zendesk for each Tidio Department. These groups will be used later to assign agents and maintain team routing logic.
3. Prepare Agent Accounts: Ensure all your Tidio Operators are provisioned as Agents or Administrators in Zendesk. You can set roles, alias, and other essential details during the user creation process. If you have deactivated or deleted operators in Tidio who authored historical messages, you still need placeholder agent accounts in Zendesk to correctly attribute those comments — you can suspend these accounts after import.

Migrate Objects

The actual data migration must proceed in a dependent sequence, ensuring primary keys (IDs) exist before linked records are processed.

1. Importing Users (Contacts and Operators)

We start by populating the user base, mapping Tidio Contacts to Zendesk End Users, and Tidio Operators to Zendesk Agents.

Leverage the bulk operation API to create and update users (including End Users and Agents) efficiently. Pass the raw data from Tidio's custom properties into the corresponding Zendesk user_fields object that you configured earlier.

Example payload for bulk user creation:

POST /api/v2/users/create_many
 
{
  "users": [
    {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "external_id": "tidio_contact_12345",
      "role": "end-user",
      "user_fields": {
        "tidio_plan": "premium",
        "signup_source": "website"
      }
    }
  ]
}

2. Linking Personnel and Teams (Group Memberships)

Once the Groups (Departments) and Users (Operators/Agents) are created, explicitly link them by creating Group Memberships.

Create Group Memberships to map your agents to their respective teams/departments. This step is necessary before importing historical tickets that were assigned to those teams.

3. Migrating Tickets

The creation of tickets must include references to the newly established users (requesters) and groups (assignments).

Use the Ticket Import API (/api/v2/imports/tickets/create_many) rather than the standard ticket creation endpoint. The import endpoint is specifically designed for historical data — it allows you to set created_at timestamps, specify the requester_id, and include full comment history in a single call without triggering automations or notifications.

Example payload for a historical ticket import with comments:

POST /api/v2/imports/tickets/create_many
 
{
  "tickets": [
    {
      "subject": "Billing question from Tidio",
      "status": "closed",
      "requester_id": 98765,
      "group_id": 54321,
      "external_id": "tidio_ticket_6789",
      "created_at": "2024-01-15T10:30:00Z",
      "comments": [
        {
          "author_id": 98765,
          "value": "Hi, I have a question about my invoice.",
          "created_at": "2024-01-15T10:30:00Z",
          "public": true
        },
        {
          "author_id": 11111,
          "value": "Sure, let me look into that for you.",
          "created_at": "2024-01-15T10:32:00Z",
          "public": true,
          "uploads": ["token_from_upload_api"]
        }
      ]
    }
  ]
}

4. Rebuilding Conversation History (Comments and Attachments)

The historical message exchange from Tidio (Contact Messages) must be accurately sequenced within the corresponding Zendesk ticket.

Conversation History: Each individual message in the Tidio chat log should be imported as a Ticket Comment. The Ticket Import API (used in step 3) allows you to specify the original author_id and the historical created_at timestamp for each comment directly in the import payload, ensuring the conversation flows correctly and maintains historical context. This requires admin-level access — the importing user must be an administrator.

Attachments: If messages included files, those files must first be uploaded using the uploads endpoint (/api/v2/uploads), yielding an attachment token. That token is then included in the comment's uploads array when creating the ticket, linking the historical files directly to the relevant message.

5. Importing Customer Activity Data (Viewed Pages History)

Tidio's tracking of customer web browsing behavior needs a new home where agents can contextualize the support request.

Use the Events API to send historical page_view data, linking each event to the previously created Zendesk User ID.

POST /api/v2/user_profiles/events
 
{
  "profile": {
    "source": "tidio",
    "type": "customer",
    "identifiers": [
      {
        "type": "external_id",
        "value": "tidio_contact_12345"
      }
    ]
  },
  "event": {
    "source": "tidio",
    "type": "page_view",
    "description": "Visited pricing page",
    "properties": {
      "url": "https://example.com/pricing",
      "title": "Pricing - Example"
    },
    "created_at": "2024-01-14T08:15:00Z"
  }
}

Validate the Migration

Don't assume success — verify it. A migration without validation is a migration you'll regret.

• Record count comparison: Compare total counts for users, tickets, and comments between Tidio exports and Zendesk. Every record should be accounted for — either migrated or explicitly excluded.
• Conversation ordering: Spot-check at least 20-30 tickets across different time periods. Verify that comment sequence, timestamps, and author attribution are correct. Pay special attention to tickets with many messages.
• Attachment integrity: Open a sample of tickets with attachments and confirm files are accessible and not corrupted.
• Custom field values: Verify that custom properties transferred correctly by sampling user and ticket records.
• External ID linkage: Confirm that external IDs are populated and queryable — you'll need these for any post-migration reconciliation.

Handle Failures and Rollback

Migrations don't always go cleanly on the first pass. Plan for partial failures.

• Idempotent operations: Use create_or_update_many with external IDs wherever possible. This means you can safely re-run a failed batch without creating duplicates.
• Batch tracking: Log which batches succeeded and which failed. When a batch fails (rate limit, malformed record, network timeout), you need to retry only the failed batch, not the entire migration.
• Partial rollback: If you need to undo a migration, Zendesk's bulk delete endpoints can remove users and tickets by ID. This is why your mapping file from the validation step is critical — it tells you exactly what to delete.
• Checkpoint strategy: For large migrations, break the work into logical checkpoints (users complete → groups complete → tickets batch 1-10 complete, etc.). This lets you resume from the last known good state rather than starting over.

Post-Migration Configuration

Once the raw data is loaded, final configuration steps ensure operational readiness and long-term data health.

• Final Workflow Setup: Manually rebuild complex support elements like routing based on agent capacity, service level agreements (SLAs), and internal notification logic that rely on the new Group and Custom Field IDs.
• Link Management (Redirect Rules): If you had a knowledge base or public URLs in Tidio that are no longer valid, implement Zendesk's Redirect Rules. This prevents broken links (404s) and preserves search engine optimization (SEO) value by directing old links to new Zendesk articles or external resources. This process is essential for maintaining customer trust immediately following the switch.

Technical Details Worth Knowing

Having executed complex platform migrations, we understand the nuances that standard documentation doesn't cover. These details are critical for avoiding surprises:

• Beware of API Rate Limits: Zendesk enforces strict rate limits, and bulk importing many objects (especially tickets and users) can quickly lead to hitting those caps. Use bulk creation endpoints (create_many, create_or_update_many) whenever possible, and always build exponential backoff logic into your migration scripts to handle 429 responses gracefully.
• External IDs are Your Lifeline: Always map and import Tidio's original IDs (for Contacts, Tickets, etc.) into Zendesk's External ID field. This provides an immutable link back to the source system, invaluable for validation, reporting, and future data synchronization.
• Historical Timestamps via the Import API: The Ticket Import API (/api/v2/imports/tickets/create_many) is purpose-built for historical data. It accepts created_at and author_id on comments without triggering notifications or automations. The importing user must have admin-level access. The standard Ticket API does not support setting historical timestamps — if you use the wrong endpoint, all your tickets will show today's date.
• Indexing Delay for Tickets: Be aware that newly imported tickets may take up to 90 seconds (often longer for large imports) to become fully available and searchable via the API endpoints that list active or recent tickets. Don't panic if your first check doesn't show the records immediately — build a polling delay into your verification scripts.
• Field Length Constraints: Zendesk has character limits on certain fields (e.g., subject lines are capped at 150 characters, custom field text fields at 255 characters). If Tidio allowed longer values, your data will be truncated or the API call will fail. Check for these edge cases before running the full migration.

Summary

Migrating from Tidio to Zendesk is a structured process best handled with an API-first approach, focusing on foundational elements first.

Begin by creating your custom infrastructure and logical groups, migrate all personnel, and only then proceed to import the transactional data (Tickets) and associated communication history (Comments/Events) in their proper chronological sequence. Validate everything, and have a plan for when things go wrong.

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 API Reference
• Zendesk API Reference
• Zendesk Ticket Import API