The Complete Guide to Migrating from Zendesk to Trengo

Moving core operational data from one platform to another is always a significant undertaking.

A successful migration requires careful planning, a deep understanding of data dependencies, and precision in execution. using strategic API methods and crucial manual configuration steps.

This guide breaks down the complex process of transitioning your valuable data, including user profiles, historical tickets, and your knowledge base, from Zendesk to Trengo.

Define Your Migration Scope

Before writing a single line of code or touching any configuration, you must define which data moves easily (via API), which requires human intervention (manual), and which can be set aside (archived).

Data Migrated via API

The vast majority of structured data can be moved programmatically, often requiring clever workarounds to manage the slight differences in platform architecture:

• Users (Agents and End Users) and Contacts: Direct creation of user accounts in Trengo is straightforward. End users map into Trengo's Contacts or Profiles.
• Organizational Data: Zendesk Organizations map logically to Trengo's Contact Groups. While Group Memberships don't have an exact dedicated bulk import process, the links can usually be established programmatically through subsequent updates to user roles and profiles.
• Custom Fields and Labels: The structure of custom fields for users, organizations, and tickets, along with all operational tags (Labels), can be re-created in Trengo using dedicated creation endpoints.
• Help Center Content and Structure: The organizational structure (Help Centers, Categories, Sections) and the articles themselves can all be moved via API.
• Historical Tickets and Conversations: Ticket metadata (priority, status, assignments) is created first, and then the chronological conversation history must be injected using Trengo's ticket message creation endpoints.
• Attachments (Media): Since ticket files and embedded article media are complex objects in Zendesk, they must first be downloaded, uploaded to Trengo's system, and then referenced in the relevant article bodies or message imports.

Zendesk → Trengo Object Mapping

The table below maps core Zendesk objects to their Trengo equivalents, noting where gaps or lossy conversions exist:

Manual Configuration

Certain logic-heavy resources are impractical to migrate directly via API due to deep platform differences and require manual configuration in the Trengo interface:

• Ticket Forms: Zendesk Ticket Forms often contain complex conditional logic and display rules, tying fields to specific channels or internal roles. These complex rule sets must be manually recreated in Trengo to ensure accurate workflow processing (Note: The structural definition is manual).
• Custom Ticket Statuses: While you can migrate the status category (e.g., "open," "solved"), the granular custom statuses themselves, and their integration with ticket forms, need to be manually defined and managed in the new system.
• Article Comments: Currently, there is no standardized, dedicated Trengo API for creating historical Article Comments, meaning this content must be handled outside the automated flow or considered non-critical for migration purposes.

Data to Archive

Data such as old custom reports, historical user activity logs (beyond ticket conversation logs), and very old closed tickets that are no longer referenced operationally should generally be archived in a data warehouse rather than migrated, reducing the complexity and cost of the migration project.

Prepare Trengo for Data Import

Before commencing the transfer of millions of records, the foundational architecture must be firmly in place. This order ensures that dependencies (like custom fields) exist before the data that relies on them (like users and tickets) is imported.

1. Define Custom Fields: Start by mirroring the schema of your Zendesk User Fields and Organization Fields by creating corresponding Custom Fields within Trengo. This step is critical because users and tickets cannot accept custom data until these fields are defined first.
2. Establish Teams and Labels: Create your organizational structure: import your existing Zendesk Groups as Teams in Trengo. Simultaneously, replicate your global system of Tags as Labels in Trengo. These form the backbone for ticket routing and organizational tagging.
3. Build Help Center Scaffolding: Set up the structure of your Knowledge Base (KB). This involves creating top-level Help Centers, followed by Categories, and then the Sections within them.

Migrate Objects

This phase involves the physical movement and re-composition of your data using the defined API strategies.

1. Transfer People and Organizations

We start with human resources, laying the groundwork for ownership and permissions.

First, migrate all internal Users (agents and admins), followed by Contacts/End Users.

Once the user profiles exist, you can create the Contact Groups derived from your old Organizations.

Then, iterate through your imported users to attach their custom field values and re-establish their roles and team associations, effectively replicating the original organization and group memberships.

2. Migrate Knowledge Base Content

The Knowledge Base migration moves from structure to content, treating media carefully.

Load Structure: The categories and sections defined in the preparation phase are populated.

Process Media: For articles containing embedded images or attachments, you must first extract the file data, upload it to Trengo's system, and capture the new URL or reference ID generated by Trengo.

Import Articles: Insert the article content, ensuring that all HTML content is clean and references the newly uploaded media URLs to preserve visual integrity.

1. Migrate Tickets and Conversation History

This is the most crucial part of the migration. We reconstruct the tickets and then rebuild the conversation chronologically.

Extract Ticket Data: Pull all relevant tickets using Zendesk's incremental export API, capturing metadata like the original requester, creation date, final status, tags, and most importantly, the chronological history of all comments and activities.

Create Ticket Shells: Create the base ticket records in Trengo — the ticket object with its initial properties, status, and custom field values that represent the ticket's current or resolved state — but without conversation history attached yet.

Inject Conversation History: Each message from the Zendesk history must be inserted sequentially against the newly created Trengo ticket ID to faithfully recreate the conversation timeline, preserving authorship and timestamps.

Re-link Attachments: For binary files embedded in the original ticket history, these files must be uploaded separately, and the resulting Trengo file ID should be referenced within the message import payload to keep the file linked correctly to the specific historical comment.

Post-Migration Validation and Configuration

Once the data is resident in Trengo, the focus shifts to validation and activating business logic that cannot be imported automatically.

Record Count Reconciliation

Before touching any business logic, verify that the migration is numerically complete:

• Users/Contacts: Compare the total count of migrated users and contacts against the source Zendesk instance. Query both platforms and reconcile the numbers.
• Tickets: Verify total ticket counts match. Spot-check tickets at the boundaries — the oldest migrated ticket, the newest, and a random sample from the middle — to confirm metadata (status, assignee, tags/labels, custom fields) transferred correctly.
• Conversations: For a sample set of tickets, verify that the message count per ticket matches the original and that messages appear in the correct chronological order with correct authorship.
• Knowledge Base: Confirm article counts per section match. Open a sample of articles and verify that embedded images render correctly from their new Trengo-hosted URLs.
• Attachments: Verify that attachments on sampled tickets are downloadable and match the original file size.

Rebuild Operational Logic

• Rebuild Workflows: Any complex operational logic defined by Zendesk triggers, automations, and historical macros must be rebuilt directly in Trengo's rule engine. These logic-based rules govern ticket assignment, notifications, and time tracking.

The table below catalogs Zendesk automation primitives and their Trengo parity:

• Fine-Tune Custom Statuses and Forms: Manually configure the new Custom Ticket Statuses and validate how they interact with the new Ticket Forms to ensure agents can successfully move tickets through the desired workflow states.
• Quality Assurance of Relationships: Verify that imported users are correctly tied to their Contact Groups and that all old custom fields are populating correctly on the imported tickets.

Rollback Strategy

Before cutting over, have a rollback plan documented:

• Keep Zendesk active until validation is complete. Do not cancel your Zendesk subscription or delete data until the migration is fully verified.
• Maintain your ID mapping table (Zendesk IDs → Trengo IDs) as the authoritative reference. If a partial migration fails, this table tells you exactly which records made it across and which did not.
• If migration fails mid-way: Because Trengo is the write target, you can delete the partially imported data in Trengo and re-run from the last known good checkpoint using your mapping table. The source Zendesk data is never modified during the migration.

Insider Secrets

When performing a migration of this scale, small details related to platform behavior can make or break the timeline.

• Rate Limits are the Real Gatekeepers: Be acutely aware that Trengo's APIs enforce rate limits — approximately 60 requests per minute based on current API behavior (check Trengo's API documentation for the latest figures, as these limits may change). Successful mass import requires careful throttling of requests with exponential backoff on 429 Too Many Requests responses, or you risk stalling the migration process entirely.
• The Difference in "ID": You must maintain a clean mapping table between the original Zendesk IDs (for users, organizations, and tickets) and their newly created IDs in Trengo. This internal cross-reference is essential when associating dependent records, such as linking a ticket message to the correct user who authored it.
• HTML is a Minefield: While Zendesk ticket comments support HTML (and older markdown rendering logic), ensure that when importing historical comments into Trengo, you sanitize complex HTML elements — particularly nested tables, inline styles, and legacy formatting — to prevent display issues in the new environment. Test a sample batch of HTML-heavy tickets before running the full import.
• Metadata is often Lost: Be mindful that many background data points, such as granular SLA breach events, ticket metric events, satisfaction ratings, and internal skip records, are historical metrics that cannot be inserted into Trengo retroactively. Plan to keep the original Zendesk instance accessible for archival reporting if these historical metrics are critical for long-term audit purposes.

Summary

Migrating from Zendesk to Trengo is fundamentally a phased operation: establish your infrastructure (Custom Fields, Teams, Help Center skeletons), populate your master data (Users, Organizations), and finally, rebuild the operational content (Articles, Tickets, and Message History).

Success hinges on respecting the platform differences, especially converting complex relational data into manageable payloads and diligently throttling bulk API requests to navigate platform limits.

Further reading

• Zendesk Ticketing API Reference
• Zendesk Incremental Exports API
• Trengo API Reference