The Complete Guide to Migrating from Trengo to Freshdesk

Moving your customer support operation from Trengo to Freshdesk requires a structured approach. Every piece of historical data, configuration, and customer context must transfer accurately.

This guide breaks down the process of transitioning your data from Trengo to Freshdesk, covering API specifics, known failure modes, attachment handling, and post-migration validation.

Object Mapping: Trengo vs Freshdesk

Before writing a single API call, confirm exactly how each Trengo object maps to its Freshdesk equivalent. The table below is your migration reference.

Define Your Migration Scope

Successful migration starts with defining exactly what data moves and how it moves. We break the data into three lanes: data suitable for API migration, data requiring API workarounds due to structural differences, and data requiring manual reconfiguration or archiving.

API Migration

The backbone of your service desk, including core entities, can be moved via a direct 1:1 API integration model.

This includes foundational records such as Users (agents in Freshdesk), Teams (Groups in Freshdesk), Contacts (customers), and the actual Tickets. Your core Custom Fields (metadata attached to tickets or contacts) and Quick Replies (Canned Responses in Freshdesk) also generally fall into this category.

Similarly, migrating the primary organizational structure of your knowledge base, including Help Centers (Solution Categories) and Help Center Categories (Solution Categories/Folders), can be automated.

API Migration Requiring Workarounds

Some data types require transformation to fit Freshdesk's structure, but this process can still be managed programmatically:

• Labels (Tags): Trengo Labels typically need to be translated into tags within Freshdesk and applied during the creation or update of corresponding records like tickets or contacts.
• Ticket Messages (Conversations): While the main ticket content moves easily, individual Ticket Messages must be extracted and then imported sequentially as Replies or Notes in Freshdesk. This preserves the full conversation timeline.
• Contact Groups: Trengo's Contact Groups often map best to Freshdesk's internal logic for Company association or are converted into generalized user-defined tags applied to the Contacts.
• Profiles: Detailed data contained within Trengo Profiles — specifically custom field values and avatar images — must be parsed and mapped to the corresponding Freshdesk Contact or Agent record attributes. Profiles are not a standalone API object in either platform; they are attributes on Contact or Agent records.
• Help Center Sections / Blocks: These smaller content structures are consolidated into the hierarchical nature of Freshdesk Solution Folders and Solution Articles.
• Ticket Results: Information captured in Ticket Results, often denoting resolution types or outcomes, should be mapped to specific custom dropdown fields or utilized to set the final status on the Freshdesk ticket. Ticket Results is a UI construct in Trengo, not a dedicated API object; extract the values from ticket-level fields during your Trengo data pull.

Manual Configuration and Archiving

Features tied fundamentally to Trengo's underlying architecture must be manually rebuilt or archived:

• Boards/Cards: Trengo's Boards/Cards feature provides a Kanban-style view of conversations. There is no direct Freshdesk object equivalent. This data should be archived in Trengo or recreated manually as tasks in Freshdesk if necessary.
• Webhooks: Webhooks must be manually analyzed and reconfigured. The payload schema differs significantly between Trengo and Freshdesk (see the Webhook section below), so a direct re-point of existing endpoints will break integrations.

Prepare Freshdesk for Data Import

Before commencing the bulk data migration, the target Freshdesk environment must be structurally prepared to receive and correctly categorize the incoming information. Skipping this step often leads to messy data and broken relationships.

1. Define and Create Custom Fields: This is the most crucial prerequisite. All of Trengo's custom metadata must have corresponding target fields created first in Freshdesk. This ensures that when tickets, contacts, or companies are imported, there are designated fields to hold their historical custom attributes.
2. Establish Organizational Structure: Create the necessary Groups in Freshdesk to mirror your Teams structure, allowing for proper assignment during ticket migration.
3. Prepare Knowledge Base Skeleton: Construct the Solutions Categories and Folders that mirror the hierarchy established in your Trengo Help Centers and Categories.

Migrate Objects

The actual migration must follow a dependency chain. Base entities need to be established before relational entities can reference them.

1. Users, Agents, and Teams (The Foundation)

Begin with the people and their organizational containers.

Agents and Users: Pull Users from Trengo and push them into Freshdesk as Agents via POST /api/v2/agents. Correspondingly, migrate end-customer Contacts into Freshdesk as Contacts via POST /api/v2/contacts.

Teams: Migrate Teams by creating corresponding Groups in Freshdesk via POST /api/v2/groups.

Profiles and Metadata: During user and contact creation, import associated Profile data and custom attribute values directly into the Freshdesk agent or contact records.

2. Knowledge Base Content

Migrate the supporting self-service documentation, ensuring the structure is accurate.

Structure Migration: Map Help Centers and Categories directly to Freshdesk Solution Categories via POST /api/v2/solution/categories.

Content Migration: Iterate through Trengo's Help Center Sections / Blocks and Articles and migrate the content into Freshdesk Solution Articles via POST /api/v2/solution/categories/{category_id}/folders/{folder_id}/articles, ensuring proper hierarchical linking to the newly created folders and categories.

3. Contacts, Groups, and Quick Replies

With the structure and staff set, focus on standard customer data and common responses.

Contacts and Grouping: After initial contact creation, reconcile Contact Groups. If these groups define corporate relationships, model them as Companies in Freshdesk via POST /api/v2/companies and establish associations. Otherwise, apply corresponding tags during the contact update process.

Canned Responses: Migrate Quick Replies by creating Canned Responses in Freshdesk via POST /api/v2/canned_responses.

4. Tickets and Conversations (Historical Data)

This is the most time-consuming phase, requiring careful handling of historical context.

Ticket Creation: Retrieve historical Tickets from Trengo and create them in Freshdesk via POST /api/v2/tickets. During creation, map the Requester ID, creation timestamps, status (Open, Pending, Resolved, Closed), priority, and Custom Fields.

Timestamp Limitation: Freshdesk allows created_at to be set on ticket creation via the standard API when using certain plan tiers, but this capability is not guaranteed across all plan levels or all object types. Specifically, created_at on conversation replies (POST /api/v2/tickets/{id}/reply) cannot be overwritten — Freshdesk will record the time of the API call, not the original message timestamp. For conversation history, store the original Trengo timestamp as a text value in a custom field or in the note body to preserve it for reporting purposes.

Labeling and Results: As you create each ticket, map Labels from Trengo and assign them as tags. Map Ticket Results data to predefined custom fields within the Freshdesk ticket structure.

Conversation Import: For each new Freshdesk ticket ID, fetch all related Ticket Messages from Trengo. Import these chronological exchanges as either public Replies (POST /api/v2/tickets/{id}/reply) or private Notes (POST /api/v2/tickets/{id}/notes) in the corresponding Freshdesk ticket.

5. Attachments

Attachments are a commonly skipped step that causes post-migration complaints. Ticket attachments, inline images in conversation history, and knowledge base article media are all binary files that cannot be transferred by copying API metadata alone.

Process: Download each attachment from Trengo as a binary file, then re-upload it to Freshdesk using a multipart/form-data POST to the relevant endpoint (e.g., POST /api/v2/tickets/{id}/reply with the attachments [] parameter). Freshdesk has a per-file attachment size limit of 20 MB via API. Files exceeding this limit must be handled separately — either hosted externally and linked in the ticket body, or flagged for manual upload.

Knowledge base article images embedded inline require the same download-and-reupload approach, with the image URL in the article HTML updated to point to the new Freshdesk-hosted location after upload.

Post Migration Configuration

Once the data transfer is complete, the final step involves restoring platform behaviors in the new Freshdesk environment.

• Rebuild Automations and Workflows: The logic previously handled by Trengo's automation tools, such as routing, escalation triggers, and internal communications, must be rebuilt using Freshdesk's robust Automation Rules. This includes reconfiguring any complex processes that previously relied on Webhooks.
• Webhook Payload Differences: Trengo and Freshdesk webhook payloads use different schemas. Trengo webhooks send conversation-centric payloads (e.g., contact, assignee, channel, labels as top-level keys). Freshdesk webhook payloads are ticket-centric (e.g., ticket_id, requester_id, group_id, status). Any downstream integration expecting a Trengo payload will break if you simply re-point its endpoint to Freshdesk — the consuming service must be updated to parse the Freshdesk schema.
• Channel Configuration: Verify that all communication channels (email, chat, phone) are correctly pointed to Freshdesk's support inboxes (Email Mailboxes), ensuring a smooth handover of new incoming queries.
• Business Hours and SLAs: Manually configure Business Hours and define SLA Policies tailored to your service levels.

Post-Migration Validation

Moving data is half the job. Confirming it arrived correctly is the other half.

1. Record Count Reconciliation: After each migration phase, query both Trengo and Freshdesk for total object counts. Compare: total tickets, total contacts, total agents, total knowledge base articles. A discrepancy in any count is your signal to investigate before proceeding.
2. Spot-Check Conversation Threads: Randomly select 10–20 historical tickets and verify that all conversation replies and notes are present in Freshdesk in the correct order. Check that attachments on those tickets are accessible.
3. Custom Field Validation: Pull a sample of migrated tickets and contacts and confirm that custom field values match their Trengo source records. Pay particular attention to fields with type constraints (numbers, dates, dropdowns) — these are the most likely to have silently failed.
4. Duplicate Detection: Before migration, establish your deduplication key for contacts. Email address is the most reliable unique identifier. If a contact already exists in Freshdesk before migration (e.g., from a prior import or manual entry), use GET /api/v2/contacts?email={email} to check for an existing record before creating a new one. Merging duplicates post-migration is significantly more costly than preventing them.
5. Orphaned Record Log: Maintain a quarantine log for any records that failed to migrate — tickets with missing requester IDs, contacts with no email address, etc. Log these with their Trengo IDs so they can be manually investigated and resolved without data loss.

Technical Constraints

Having successfully executed these complex data transitions provides insight into critical pitfalls and optimization points.

1. Rate Limit Management: Freshdesk enforces API rate limits that vary by plan. The range runs from approximately 50 calls/minute on entry-level plans to 700 calls/minute on higher tiers. Check your specific plan's limit in the Freshdesk API documentation before building your migration pipeline, as this directly determines your throughput. When a rate limit is hit, Freshdesk returns an HTTP 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying. Your migration script must handle 429s explicitly — a missing retry handler will abort large batch jobs mid-run.
2. Handling Timestamps: All timestamp fields (created_at, updated_at) must be provided in UTC format: YYYY-MM-DDTHH:MM:SSZ. Freshdesk will reject or misparse timestamps in other formats. See the timestamp limitation note in the Tickets section above regarding conversation reply timestamps specifically.
3. Custom Field Type Validation: Before initiating bulk ticket or contact creation, test every custom field mapping. Pushing a text string into a number field returns an HTTP 400 Bad Request with a validation error body. A single type mismatch can cause an entire batch to fail. Run a small test batch of 10–20 records first and inspect the responses before scaling up.
4. Conflict Resolution for Contacts: If a contact with the same email address already exists in Freshdesk, POST /api/v2/contacts will return an HTTP 409 Conflict. Your migration script must handle this by switching to PUT /api/v2/contacts/{id} to update the existing record rather than creating a duplicate.
5. Orphaned Data: Despite thorough planning, some records will have missing foreign key references — ticket requesters that don't map to a migrated contact, or agent assignments referencing a deactivated user. Establish a fallback assignment (e.g., a placeholder agent or unassigned queue) and log these for manual resolution post-migration.

Summary

Migrating from Trengo to Freshdesk requires careful planning and execution. By adhering to a rigorous sequence — users and teams first, then knowledge base, then contacts, then tickets and conversations, then attachments — you preserve data integrity and referential consistency.

The key technical constraints to manage are API rate limits (with explicit 429 handling), timestamp formatting, custom field type validation, attachment binary transfer, contact deduplication, and webhook payload schema differences. Post-migration, run record count reconciliation and spot-check conversation threads before decommissioning your Trengo instance.

Further reading

• Freshdesk
• Trengo