The Complete Guide to Migrating from Trengo to Zendesk

Zendesk offers a robust platform for customer service operations, and transitioning from Trengo involves understanding how data models translate between the two environments.

While many objects like users and organizations map cleanly, complex historical data and system configurations require careful planning.

This guide outlines the key steps and considerations for migrating your data from Trengo to Zendesk, focusing on how different Trengo components map to Zendesk objects.

Trengo's Data Model: What You're Working With

Before mapping objects to Zendesk, it helps to understand what Trengo's own data model contains — especially if your team inherited a Trengo instance and didn't build it from scratch.

• Users: Agents and team members who operate inside Trengo. These have API-level access and belong to Teams.
• Contacts: External people (customers) who have interacted with your inbox. A Contact can have multiple communication identities (email, WhatsApp number, Instagram handle).
• Profiles: A Trengo concept for a unified view of a Contact across channels. Profiles consolidate multiple identities into a single record, similar to how Zendesk Sunshine Profiles work.
• Teams: Groups of agents organized for routing or collaboration purposes. These are the Trengo equivalent of Zendesk Groups.
• Contact Groups: Organizational groupings of Contacts — analogous to Zendesk Organizations.
• Boards and Cards: A project-board feature in Trengo (similar to a Kanban board) for tracking non-ticket work. These have no direct Zendesk equivalent.
• Tickets: Conversations assigned to agents, sourced from any connected channel (email, WhatsApp, Instagram, etc.).
• Quick Replies: Saved response templates, equivalent to Zendesk Macros.
• Labels: Tags applied to conversations for filtering and reporting.

Define Your Migration Scope

The foundation of a successful migration is clearly defining what data needs automated transfer, what configuration must be built manually, and what legacy data can be archived.

Data Fidelity Matrix

The table below defines every major Trengo object, its Zendesk equivalent, the migration method, and the expected fidelity.

Trengo Object	Zendesk Equivalent	Migration Method	Fidelity
Users (agents)	Users (agents)	API	Full
Contacts	Users (end-users)	API	Full
Profiles	Users + Sunshine Profiles	API	Partial — multi-identity consolidation requires Sunshine
Teams	Groups	API	Full
Contact Groups	Organizations	API	Full
Custom Field Definitions	Ticket / User / Org Fields	API	Full
Custom Field Values	Custom field values on records	API	Full (if fields pre-created)
Knowledge Base (Categories/Sections/Articles)	Zendesk Guide	API	Full
Tickets	Tickets	API	Full
Ticket Messages	Ticket Comments	API	Full
File Attachments	Ticket Attachments	API (multi-step upload)	Full
Labels	Tags	API	Full
Quick Replies	Macros	Manual rebuild	Partial — content portable, logic must be rebuilt
Webhooks	Zendesk Webhooks	Manual rebuild	Partial — endpoints must be reconfigured and tested
Boards / Cards	No direct equivalent	Manual or custom app	None — requires custom workflow design
WhatsApp-native messages	Ticket Comments (text only)	API	Partial — media/stickers may not carry over
Instagram / Facebook messages	Ticket Comments (text only)	API	Partial — channel-specific metadata lost
Internal chat (Trengo inbox chat)	Internal notes	API	Partial — context preserved, threading may differ
Historical report metrics	External archive / data warehouse	Export only	None — not importable into Zendesk Explore

API Migration

Most foundational data can and should be moved using API calls, leveraging bulk processing capabilities.

• Users, Contacts, and Profiles: Trengo Users map directly to Zendesk Users, managed via the Users API. Trengo Contacts and Profiles are generally consolidated into Zendesk Users, often using the Zendesk Profiles API if you utilize Sunshine functionality for multi-system identities.
• Teams and Contact Groups: Trengo Teams correspond directly to Zendesk Groups. Trengo Contact Groups translate to Zendesk Organizations.
• Custom Fields: The definitions of Trengo's global Custom Field Definitions map to Zendesk's Ticket Fields, User Fields, or Organization Fields. The actual custom field Values attached to contacts, profiles, or tickets in Trengo must be explicitly mapped and set when creating or updating the corresponding Zendesk record.
• Knowledge Base Content: Trengo's Help Center Categories, Sections, and Articles map to the hierarchical structure within Zendesk Guide.
• Tickets and Messages: Trengo Tickets correspond to Zendesk Tickets. Individual messages within a ticket must be imported as Ticket Comments or Audits in Zendesk.

Manual Configuration and Review

Some functional objects involve replicating business logic or complex configuration that is best done manually in the new environment or requires custom setup:

• Quick Replies (Macros): While Trengo supports Create a quick reply, migrating these to Zendesk Macros is typically done manually or requires analyzing the structure of the quick replies and rebuilding them within Zendesk's macro interface.
• Webhooks: Trengo manages Webhooks through API endpoints. These complex integrations must be rebuilt and tested manually in Zendesk to ensure proper triggering of external services or business systems.
• Boards/Cards: Trengo uses Boards and Cards (managed via Create a new card) for organizational purposes. This functionality generally lacks a direct 1:1 mapping to a single Zendesk object and may require custom app development or being mapped into specialized ticket workflows or custom objects.

Archiving and Historical Data

Reporting data and long-gone history should be carefully evaluated:

• Historical Data/Metrics: Detailed report data from Trengo is read-only and should be extracted into a separate data warehouse or archived outside of Zendesk.
• Deep History: For maximum fidelity of message history in Zendesk, use the specialized side conversation import endpoint for threads that cannot be recreated simply via the bulk ticket endpoint.

Pre-Migration Readiness Checklist

Before writing a single API call, confirm the following.

Zendesk requirements:

• Confirm your Zendesk plan supports Custom Ticket Statuses. This feature is available on Suite Professional and above. On lower tiers, you are limited to the five system statuses (new, open, pending, hold, solved).
• Generate a Zendesk API token with full read/write scope, or use OAuth with the tickets:write, users:write, and organizations:write scopes.
• Confirm your plan's rate limits (see the Rate Limits section below) and size your migration window accordingly.

Trengo requirements:

• Obtain a Trengo API token with read access to all objects you intend to export: Tickets, Contacts, Profiles, Teams, Labels, and Knowledge Base content.
• Confirm whether your Trengo account has access to the full API (some legacy plans restrict export endpoints).
• Export a sample of 100 tickets and validate that messages, attachments, and custom field values are all present in the response before running a full export.

Data audit before starting:

• Count total records per object type in Trengo (Users, Contacts, Tickets, Articles). You will use these counts to validate completeness after migration.
• Identify duplicate Contact records in Trengo and resolve them before migration — duplicates will create duplicate end-users in Zendesk.
• Document all custom field names and value types in Trengo so you can pre-create matching fields in Zendesk before importing records.
• Decide how to handle open Trengo tickets at cutover: migrate them in-progress, or close them first and migrate as solved.

Prepare Zendesk for Data Import

Before commencing data migration, ensure that the target Zendesk environment is ready to receive and structure the incoming data.

1. Map and Create Custom Fields: First, recreate the structure of Trengo's Custom Field Definitions in Zendesk, mapping them to the corresponding fields (Ticket, User, or Organization). This step is critical because many subsequent objects (users, tickets) rely on these fields being present.
2. Define Teams/Groups and Organizations: Next, create all necessary Groups (from Trengo Teams) and Organizations (from Trengo Contact Groups) using the respective creation APIs. This establishes the organizational backbone of your new support system.
3. Configure Ticket Workflow Statuses: If Trengo used custom Ticket Results, mirror these in Zendesk using Custom Ticket Statuses. These custom statuses belong to underlying system categories like "new," "open," "pending," "hold," or "solved".

Migrate Objects

The data migration must follow a dependency chain to ensure child objects link correctly to parent objects.

1. Users and Contacts

Migrate all agents and end users first. You can use the Create Or Update User or Create Many Users endpoints in Zendesk.

User Creation: For each user, migrate core identity data (name, email) and assign their initial Role (e.g., agent, admin, or end-user). Use the email or external_id for matching existing records.

Linking Organizations and Teams: Once users and organizations/groups exist, establish the relationships. Assign users to Organizations (Trengo Contact Groups) using Organization Memberships APIs, defining their default organization if they belong to multiple. Similarly, link agents to Groups (Trengo Teams) using the Group Memberships APIs.

Adding Profiles/Identifiers: Import additional user identities (like secondary emails or phone numbers) using the User Identities API, linking them to the main user record.

2. Knowledge Base Hierarchy and Content

This involves building the structure first, then populating the articles.

Categories and Sections: Create the parent container structures first: Categories and Sections using their respective APIs. Remember that deleting a Category in Zendesk automatically deletes all contained Sections and Articles.

Articles: Import the content for Articles into the relevant Sections. When creating articles, you must specify the target locale, permission group ID, and user segment ID.

Content Assets (Blocks): Trengo Blocks (reusable content) often translate to reusable assets, or may simply be embedded HTML within the Article body of a Zendesk Guide article. Complex assets might require the three-step Zendesk Guide Media process: request an upload URL, upload the file, and finally create the media object, specifying parameters like guide_media_id when creating attachments to link them.

Labels (Tags): Trengo Labels are utilized in Zendesk as Tags attached to articles, tickets, users, or organizations. Tags should be applied after the object creation where applicable.

3. Historical Ticket Data

Migrating ticket data is the most data intensive step, and it must account for message history, timestamps, and metadata integrity.

Ticket Creation: Create tickets, using bulk creation methods where possible (up to 100 tickets per call via create_many). The initial ticket creation uses the comment property to set the first conversation message.

Crucially, when importing tickets, the requester must be specified (requester_id). If the ticket originally came from a closed Trengo ticket, you could recreate it as a follow-up ticket in Zendesk by including the via_followup_source_id property, if appropriate.

All custom field values associated with the original Trengo ticket should be populated using the custom_fields array during creation or update.

Ticket Conversation History: For transferring subsequent messages within a conversation (Trengo Ticket Messages), utilize the Zendesk ticketing Update Ticket endpoint, including a comment object for each message in the historical thread.

Attachments: For files attached to historical messages (Trengo File uploads), the process requires multiple steps in Zendesk: first, upload the file using the Attachments API to get an upload token, and then pass this token within the uploads array inside the comment object when updating the relevant ticket.

Historical Threads (Side Conversations): Complex internal or external conversations tracked separately in Trengo, perhaps labeled uniquely, can be imported directly into Zendesk as historical Side Conversations or Side Conversation Events if they involve multi-party threads outside the main ticket flow.

Rate Limits and Volume Planning

Zendesk's rate limits vary by plan. For the Ticketing API, Zendesk documents the following limits (source: Zendesk Rate Limits documentation):

• Enterprise plans: up to 700 requests per minute
• Professional plans: up to 400 requests per minute
• Lower tiers: typically 200 requests per minute or below

The create_many endpoint for tickets accepts a maximum of 100 tickets per call. Each call counts as one request against your rate limit quota.

Volume estimate example: A dataset of 50,000 tickets with an average of 5 comments each requires approximately 50,000 ÷ 100 = 500 bulk creation calls, plus up to 250,000 individual comment update calls. At 700 requests/minute (Enterprise), comment updates alone require a minimum of approximately 6 hours of sustained API throughput — before accounting for attachment uploads, retries, or backoff delays. Plan your migration window accordingly, and monitor the X-Rate-Limit-Remaining and Retry-After response headers to avoid hard throttling.

Common Errors and How to Resolve Them

The following errors appear frequently during Trengo-to-Zendesk migrations. Anticipating them reduces the time spent debugging mid-migration.

1. Duplicate user / conflicting email If a user already exists in Zendesk with the same email as a Trengo Contact you are trying to create, the API returns a 422 Unprocessable Entity with a message like Email has already been taken. Resolution: use Create Or Update User instead of Create User, which will update the existing record rather than reject the request. If the existing Zendesk user is an agent and the incoming record is an end-user, review the role assignment before merging.

2. Missing requester_id Tickets created without a valid requester_id will fail with 422: Requester: is not valid. This happens when user migration has gaps — typically because a Trengo Contact was soft-deleted or had no email address. Resolution: create a placeholder end-user in Zendesk (e.g., unknown-<trengo_contact_id>@yourdomain.com) and use that ID as the fallback requester before importing the ticket batch.

3. Invalid custom field option value Drop-down custom fields in Zendesk only accept values that match a pre-defined option. If the Trengo source data contains a value not present in the Zendesk field's option list, the ticket creation silently omits the field value or returns a validation error depending on the endpoint. Resolution: before migration, pull the allowed option list for each drop-down field from Zendesk and cross-reference it against all values present in your Trengo export. Add missing options to Zendesk before importing tickets.

4. Attachment upload token expiry Zendesk attachment upload tokens are valid for a limited time after the upload completes. If there is a processing delay between uploading the file and including the token in a ticket comment, the token may be expired and the attachment will not attach. Resolution: upload attachments immediately before the API call that references them, not in a pre-upload batch hours earlier.

5. Organization membership limit Zendesk limits the number of organizations a single user can belong to. If your Trengo Contact Group structure results in a user being assigned to more organizations than Zendesk permits for your plan, the membership creation call will fail. Resolution: audit users with multiple Contact Group memberships in Trengo before migration and determine which organization should be set as the default.

Post Migration Configuration

Once the raw data is safely residing in Zendesk, focus shifts to rebuilding the functional and reporting layers. These processes typically involve configuration within the Zendesk Admin Center or using specific APIs that govern ongoing operations and compliance.

1. Rebuild Automated Workflows: Any Trengo automations, including routing rules, triggers, and automations (actions executed on tickets or other objects), must be manually recreated within Zendesk Triggers and Automations.
2. Redirects: To preserve SEO and link integrity for old Help Center content, implement Redirect Rules for deleted or relocated articles, sections, or categories. You can configure redirect rules using the Redirect Rules API.
3. Setup Reporting Dashboards: While raw metrics were archived, the corresponding reporting views and dashboards need to be set up in Zendesk Explore or Analytics to utilize the new data structure for future performance analysis.
4. Security and Compliance Cleanup: Review user identities to ensure primary emails are correctly verified, especially if migration bypassed standard verification flows.

Post-Migration Validation

Do not consider the migration complete until record counts and data integrity are confirmed.

Record count reconciliation:

• Query the Zendesk Users API (GET /api/v2/users/count) and compare the result to your Trengo Contact + User export count.
• Query the Zendesk Tickets API (GET /api/v2/tickets/count) and compare to your Trengo Ticket export count.
• For Knowledge Base content, query GET /api/v2/help_center/articles with a count and compare to your Trengo article export.

If counts do not match, cross-reference your import logs against the external IDs stored on Zendesk records (the Trengo IDs you stored as external_id during migration) to identify which records failed to import.

Spot-check data fidelity:

• Select a random sample of 20–30 tickets from across your date range and verify that: the requester is correct, all comments are present and in chronological order, custom field values match the Trengo source, and attachments open correctly.
• Verify that at least one ticket per custom field type (drop-down, text, checkbox, date) has the correct value populated.

Workflow validation:

• Trigger a test ticket through each rebuilt Zendesk automation and confirm it routes, assigns, and updates status as expected.
• Confirm that redirect rules for moved Knowledge Base articles return HTTP 301 responses when the old URLs are requested.

Insider Secrets

Successfully migrating large volumes of support data demands forethought concerning technical nuances and organizational dependencies.

• The Golden Rule of IDs: While you cannot always preserve original IDs, ensuring every migrated object (User, Organization, Ticket) is tagged with its original Trengo ID as an External ID in Zendesk is vital. This correlation ID is essential for debugging post-migration sync issues, reconciling data, and quickly referencing legacy systems if necessary.
• Timestamp Integrity for History: When importing historical communication (messages/comments), ensure you use the correct API methods that allow the original created_at timestamp to be set. This preserves the narrative history of the ticket accurately in Zendesk's audit log. Using a system user for the import process is often recommended to maintain the integrity of the original author and time of the customer-facing events.
• Bulk API Limits: Zendesk APIs employ rate limits and bulk limits — the create_many endpoint accepts up to 100 items per batch. For massive datasets, use the create_many and update_many endpoints and strictly monitor the rate limit headers (X-Rate-Limit-Remaining, Retry-After) provided in each response to prevent throttling or temporary blocks. For heavy ticket volume, explore Incremental Exports APIs, which can retrieve mass data efficiently for export purposes.

Summary

The migration from Trengo to Zendesk is primarily an API-driven project focused on data translation and integrity.

By sequentially importing administrative objects (Custom Fields, Groups, Organizations, Users) before transactional data (Tickets, Articles), you correctly build dependencies and ensure a functional environment from day one.

Post-migration tasks should immediately focus on setting up automation and validating redirected paths for historical content access.

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

• Trengo API Reference
• Zendesk Ticketing API Reference
• Zendesk Rate Limits
• Zendesk Bulk Import (create_many)
• Zendesk User Identities API