Trengo to Helpshift Migration: A Technical Guide

Trengo to Helpshift Migration: A Technical Guide

Scope: This guide covers the Trengo REST API v2 and Helpshift REST API v1. All API behaviors were verified against current documentation. API interfaces change — cross-reference against developer.helpshift.com and Trengo's developer portal before executing a production migration.

Disclosure: This guide was written by ClonePartner, a help desk migration services vendor. The technical details reflect direct experience running this migration. All claims are presented factually; commercial context is limited to the final section.

Migrating from Trengo to Helpshift means moving data between two fundamentally different architectures. Trengo is an omnichannel shared inbox built around discrete tickets across email, WhatsApp, social, and voice. Helpshift is a mobile-first, app-centric platform where every interaction is an Issue scoped to a specific App, driven primarily by in-app SDK messaging and web chat.

This isn't a 1:1 copy — it's a restructuring of your data model. You're not just swapping databases; you're translating a channel-centric world into an app-centric one.

This guide covers entity mapping, API mechanics on both sides, dependency ordering, and the edge cases that will cause silent data loss if ignored.

If you've already read our post on how to export data from Trengo, you're ahead of the game. That export knowledge is your starting point here.

Why Teams Move from Trengo to Helpshift

The most common driver is a strategic pivot toward in-app support. Helpshift was purpose-built for mobile apps and games — its SDK automatically attaches device metadata (OS version, app version, battery level, device model, network state) to every Issue at creation time. If your product is a mobile app and you want native, conversational in-app support with AI-powered bots and that automatic device context, Helpshift is a natural fit.

Other reasons include:

• SDK-level integration — Helpshift embeds directly into iOS, Android, Unity, React Native, and Unreal Engine. Trengo has no equivalent in-app SDK. API-created Issues (the migration path) do not receive automatic SDK device context — they arrive as bare Issues without attached device metadata unless you pass that data explicitly in the payload.
• AI automation depth — Helpshift's bot framework and Guided Issue Filing offer structured in-app automation flows. These are not migrated; they must be rebuilt from scratch in Helpshift after migration.
• Gaming and high-volume mobile support — Helpshift is the dominant platform in mobile gaming support, where ticket volumes can be massive and in-app device context is non-negotiable for effective triage.

The Architectural Mismatch You Must Understand

Before touching any code, internalize this: Trengo is channel-centric; Helpshift is app-centric.

In Trengo, a ticket can originate from email, WhatsApp, Instagram, Facebook Messenger, SMS, live chat, or VoIP. Each channel is a first-class citizen. A ticket is created on a channel and agents reply on that same channel.

In Helpshift, Issues originate from an App — an iOS app, an Android app, a web app, or the REST API. Every Issue must be associated with a specific App ID (app_publish_id). The concept of "channels" in Trengo's sense does not exist. There is no WhatsApp channel, no email inbox, no social DM feed.

This means:

• Trengo tickets from email, social, or voice channels don't have a natural home in Helpshift. They'll be imported as API-created Issues, but they'll lose their channel-specific context (email headers, social handles, voice recordings).
• Trengo Contact Groups have no direct equivalent. Helpshift organizes users by App, not by arbitrary groupings.
• VoIP call logs and voice recordings cannot be migrated. Helpshift has no voice support at all. Archive these separately before cutover.
• Multi-brand data requires careful mapping. If your Trengo data spans multiple brands or apps, you must map Trengo channels or labels to specific Helpshift App IDs during the transformation phase before running any import.

Entity Mapping Reference

This table maps every relevant Trengo object to its Helpshift equivalent, the migration method, and critical notes.

Define Your Migration Scope

What Moves via API

The Helpshift REST API (v1) provides write access to the core objects you need. The base URL follows the pattern https://api.helpshift.com/v1/<domain>/. Authentication uses an API key passed as the username in HTTP Basic Auth (password field left blank), obtained from the Helpshift Dashboard under Settings → API.

• Issues — Create, edit, bulk edit, add messages, add private notes
• FAQs — Create and edit individual FAQ articles
• FAQ Sections — Create and edit sections (containers for FAQs), scoped per App
• Users — The User Hub Bulk APIs support importing end-user data with a documented limit of 10,000 user payloads per request

What Requires Manual Configuration

These structural elements must be set up in the Helpshift Dashboard before any API import runs:

• Agents and Agent Groups — Provision early. You'll need agent IDs for Issue assignment during migration.
• Apps — Create the App(s) in Helpshift that will receive the migrated data. Every Issue and FAQ Section is scoped to an App via app_publish_id.
• Custom Issue Field Definitions — Must be created in the Dashboard (Settings → Custom Issue Fields) before any Issue can reference them. Supported types: singleline, multiline, number, checkbox, dropdown, date. Note: multiline and certain advanced CIF types may require specific Helpshift plan tiers — confirm with your account manager before designing your field schema.
• Tags — Must exist in the Dashboard before they can be applied to Issues via API. Tags must match exactly (case-sensitive). There is also a character limit on tag names; values exceeding this limit will return a 400 Bad Request.
• Quick Replies / Canned Responses — No API for creation; rebuild manually.
• Business Schedules — Configure operating hours in the Dashboard.
• Automations and Smart Views — Rebuild routing rules and filtered views post-migration. Helpshift's automation engine is event-model-based and differs fundamentally from Trengo's workflow logic; these cannot be exported or converted automatically.

What Gets Archived (Cannot Be Migrated)

Import Dependency Order

Helpshift's data model has strict reference dependencies. Importing out of order produces missing reference errors or, worse, silently incomplete records. Follow this sequence exactly:

1. Apps — Create or verify target Apps in the Dashboard; collect app_publish_id for each
2. Agents & Agent Groups — Provision manually; collect agent IDs for assignment mapping
3. Custom Issue Field Definitions — Create in Dashboard; verify exact key names and types
4. Tags — Create in Dashboard; document exact case-sensitive strings used
5. FAQ Sections — Create via API; scoped to App (app_publish_id required)
6. FAQs — Create via API; linked to Sections by Section ID
7. Users (End Users) — Import via User Hub Bulk APIs in batches of up to 10,000
8. Issues — Create via API; linked to App, optionally assigned to Agent
9. Messages & Private Notes — Add to Issues in strict chronological order (created_at ascending)
10. Attachments — Included with Messages at creation time via multipart/form-data

Trengo Export: API Constraints and Rate Limit Math

Pulling data out of Trengo is the first half of the migration. The Trengo REST API v2 base URL is https://app.trengo.com/api/v2/. Authentication uses a Bearer token passed in the Authorization: Bearer <API_TOKEN> header, generated under Settings → Apps and Integrations → REST API.

Rate limit: 120 requests per minute. Trengo returns 429 Too Many Requests with Retry-After and X-RateLimit-Reset headers when exceeded. Your export script must implement exponential backoff using the Retry-After value.

Pagination: Use page and per_page query parameters. The API does not provide a total count upfront on all endpoints — paginate until you receive an empty result set.

Rate Limit Math: Estimating Export Duration

At 120 RPM, the theoretical maximum throughput is 7,200 requests per hour. In practice, with retry overhead and variable response times, budget 5,000–6,000 effective requests per hour.

For a Trengo instance with 50,000 tickets where each ticket requires 3 API calls (ticket record, messages thread, attachments list):

50,000 tickets × 3 calls = 150,000 requests
150,000 ÷ 5,500 effective RPH = ~27 hours for tickets alone
+ contacts export (~50,000 ÷ 100 per page = 500 calls)
+ labels, articles, categories (~200 calls)
Total: ~28–30 hours end-to-end

Plan for a 36-hour export window for a 50,000-ticket instance to account for retries and network variability.

The core export endpoints:

GET /api/v2/contacts          # All contacts with custom field values
GET /api/v2/tickets           # All tickets (paginated)
GET /api/v2/tickets/{id}      # Individual ticket with messages
GET /api/v2/labels            # All labels
GET /api/v2/users             # All agents
GET /api/v2/help_center/categories  # Help center structure
GET /api/v2/help_center/articles    # Help center content (paginated)

Helpshift Import: API Mechanics

Creating Issues

The Create Issue endpoint is the core workhorse:

POST https://api.helpshift.com/v1/<domain>/issues

Example payload mapping a Trengo ticket to a Helpshift Issue:

{
  "title": "Login issue on iOS",
  "message_body": "Customer reported they cannot log in after the latest update.",
  "app_publish_id": "app_1234567890",
  "author_email": "customer@example.com",
  "author_name": "Jane Doe",
  "tags": ["ios", "login_error"],
  "custom_issue_fields": {
    "plan_type": {
      "type": "singleline",
      "value": "premium"
    },
    "source_channel": {
      "type": "dropdown",
      "value": "email"
    }
  }
}

The Helpshift Create Issue API does not have a documented rate limit as of current API v1 documentation. However, sustained high-volume imports should be discussed with your Helpshift account manager, as costs on some plan tiers are usage-based.

Timestamp Preservation: The Definitive Answer

This is one of the most common and painful issues in this migration. By default, Issues created via the Helpshift API receive a created_at timestamp of the moment the API call is made — not the original ticket creation date from Trengo.

The correct approach: Pass the original Trengo created_at value (Unix timestamp in milliseconds) in the created_at field of the Create Issue payload:

{
  "title": "Original ticket from 2022",
  "message_body": "...",
  "app_publish_id": "app_1234567890",
  "author_email": "customer@example.com",
  "created_at": 1640995200000
}

If the endpoint rejects the created_at override (which can occur on certain Helpshift plan configurations), use this fallback: prepend the original date as the first line of message_body in plaintext format (e.g., [Originally submitted: 2022-01-01 12:00 UTC]). This preserves the timestamp as human-readable context visible to agents, even though the system created_at will reflect import time. Verify timestamp override behavior on a test Issue before running the full migration.

Adding Messages to Issues

Once an Issue is created, capture the returned issue_id and add the conversation thread:

POST https://api.helpshift.com/v1/<domain>/issues/{issue-id}/messages

Messages support attachments. Import in strict chronological order (created_at ascending). Each message is attributed to either the end user or an agent via the author_id field — pass the customer's identifier or the mapped Helpshift Agent ID accordingly.

Expected error codes on this endpoint:

• 400 Bad Request — Malformed payload, oversized attachment, or invalid author ID
• 403 Forbidden — API access not enabled or insufficient permissions
• 404 Not Found — issue_id does not exist (indicates the Issue creation step failed silently)
• 422 Unprocessable Entity — Payload structure valid but content fails validation (e.g., attachment type not permitted)

Adding Private Notes

POST https://api.helpshift.com/v1/<domain>/issues/{issue-id}/private-notes

Trengo internal notes map directly to Helpshift private notes. Verify your script correctly distinguishes note type in the Trengo export — misclassifying a private note as a public message exposes internal agent commentary to end users.

Handling Attachments

Trengo attachment URLs frequently expire or require session authentication. Your middleware must:

1. Download the file from Trengo into a temporary local buffer immediately during export (do not rely on stored URLs being valid at import time)
2. Upload the file to Helpshift using a multipart/form-data POST to the message creation endpoint
3. Append the returned Helpshift attachment reference to the specific message payload

Voice recordings can technically be attached as audio files on Helpshift messages, but Helpshift has no audio playback UI — they will appear as downloadable file links only.

Importing FAQs

FAQs require a two-step process:

1. Create the FAQ Section (scoped to an App):

   POST https://api.helpshift.com/v1/<domain>/sections
   

2. Create individual FAQs within that Section:

   POST https://api.helpshift.com/v1/<domain>/faqs
   

Trengo's Help Center uses a Category → Article hierarchy. Helpshift uses App → Section → FAQ. Map each Trengo category to a Helpshift Section, and each article to a FAQ.

Multi-locale FAQ handling: If your Trengo Help Center contains articles in multiple languages, Helpshift supports multi-locale FAQ content. Each locale is a separate FAQ object linked to the same Section. You must create one FAQ per language per article — there is no bulk-locale import. Audit your Trengo article count by language before estimating import time.

Formatting: Trengo articles often contain rich HTML. Helpshift FAQs support HTML, but you should sanitize the payload before import: strip unsupported inline styles, remove <script> tags, and test rendering against Helpshift's mobile SDK (which applies its own CSS). What renders correctly in a browser may break in the mobile SDK renderer.

Importing Users via Bulk API

POST https://api.helpshift.com/v1/<domain>/user-hub/bulk

The User Hub Bulk API accepts a JSON array of user profile maps, with a documented limit of 10,000 per request. Each user object should include identifiers that will match the author_email or author_id fields you use in Issue creation — mismatches will create orphaned Issues with no linked user profile.

Pagination on GET Requests

When verifying imported data, Helpshift's GET endpoints paginate at 100 items per page by default, with a maximum of 100 pages per query (10,000 items per unfiltered request). The page-size parameter can be set up to 1,000 items, raising the ceiling to 100,000 items per unfiltered query. For datasets exceeding 100,000 records, segment using created_since and created_until time-range filters.

Practical implication: A Helpshift account with 150,000 Issues requires at minimum 2 time-range query segments to retrieve all records for validation. Plan your validation queries around date ranges, not page offsets.

Custom Issue Fields: The Mapping Problem

This is where Trengo-to-Helpshift migrations get genuinely complex. Trengo has Contact-level custom fields — metadata attached to a customer profile that persists across all their tickets. Helpshift has Custom Issue Fields (CIFs) — metadata attached to individual Issues, not to users.

This is a fundamental data model difference:

Practical mapping strategy:

• Per-ticket fields (priority, category, issue type, error code): Map directly to CIFs on each Issue
• Per-customer fields (account tier, plan, region, customer ID): Choose one of three approaches:
  1. Duplicate onto every Issue — Highest data redundancy, but context is always visible on the Issue detail view without a separate lookup
  2. Store only on User Hub profile — Cleaner data model, but agents must navigate to the user profile to see it; won't appear on Issue detail view
  3. Hybrid — Store on User Hub and populate new Issues via SDK going forward; accept that historical migrated Issues carry the value as a CIF snapshot

Helpshift supports exactly six CIF types: singleline, multiline, number, checkbox, dropdown, and date. There is no multi-select type. If your Trengo custom fields use multi-select or array-type values, flatten them into a comma-delimited singleline value before import.

Handling Channel-Specific Tickets

Trengo tickets carry channel context — a WhatsApp ticket has a phone number and WhatsApp-specific metadata, an email ticket has headers and CC fields, a voice ticket has call duration and a recording. Helpshift has no channel model. Every imported ticket becomes a generic Issue.

Preservation strategy by channel type:

Migration Script Structure

A practical outline for a production migration script:

# Phase 1: Export from Trengo (run first; takes 28–36 hours for 50k tickets)
contacts = paginate_all("GET /api/v2/contacts", rate_limit=120)
tickets = paginate_all("GET /api/v2/tickets", rate_limit=120)
for ticket in tickets:
    ticket["messages"] = fetch(f"GET /api/v2/tickets/{ticket['id']}")
    # Download all attachments immediately — URLs expire
    for msg in ticket["messages"]:
        for attachment in msg.get("attachments", []):
            attachment["local_path"] = download_to_temp(attachment["url"])
labels = fetch("GET /api/v2/labels")
articles = paginate_all("GET /api/v2/help_center/articles", rate_limit=120)
 
# Phase 2: Pre-flight checks (verify all manual setup is complete)
assert helpshift_apps_exist()
assert helpshift_agents_provisioned()
assert helpshift_cifs_created()   # Keys must match exactly — verify case
assert helpshift_tags_created()   # Names must match exactly — case-sensitive
 
# Phase 3: Import to Helpshift (strict dependency order)
for section in trengo_categories:
    create_helpshift_section(section, app_id)
 
for article in articles:
    # Handle multi-locale: create one FAQ per language variant
    for locale, content in article["locales"].items():
        create_helpshift_faq(content, section_id, locale)
 
import_users_bulk(contacts, batch_size=10000)
 
for ticket in tickets:
    issue_id = create_helpshift_issue(ticket, app_id)
    # Verify issue was created before threading messages
    assert issue_exists_in_helpshift(issue_id), f"Issue creation failed for ticket {ticket['id']}"
    for message in sorted(ticket["messages"], key=lambda m: m["created_at"]):
        if message["type"] == "note":
            add_private_note(issue_id, message)
        else:
            add_message(issue_id, message)
        # Idempotency: record committed message IDs to prevent duplicates on restart
        mark_committed(ticket["id"], message["id"])
 
# Phase 4: Validate
validate_issue_counts()
validate_message_counts_sampled(sample_rate=0.05)  # 5% spot-check
validate_cif_values_sampled(sample_rate=0.05)
validate_faq_counts()

Idempotency is mandatory. If the script crashes halfway through threading messages to an Issue, restarting without idempotency will produce duplicate messages. Maintain a local SQLite database or Redis cache mapping each Trengo message_id to its committed Helpshift state. On restart, skip any message already recorded as committed.

The Cutover Strategy

A zero-downtime migration requires a phased approach. The goal is to move the bulk of data before any freeze, minimizing the blackout window to minutes rather than days.

1. Historical Sync — Migrate all closed tickets and historical data up to a cutoff date (e.g., one week before planned cutover). This moves the bulk of your data volume without impacting live operations in Trengo.
2. Delta Sync — Run a daily incremental script that migrates only tickets updated since the last sync, using Trengo's updated_since filter parameter.
3. The Freeze — Choose a low-traffic window (e.g., Saturday 2 AM in your primary timezone). Stop routing new inquiries to Trengo. Redirect support email forwarding and SDK endpoints.
4. Final Catch-up — Run the migration script one final time with a narrow updated_since window covering the last 24–48 hours, catching any tickets created or updated since the last delta sync.
5. Validate — Run issue count, message count, and CIF spot-checks before declaring success.
6. Go Live — Point SDKs, email forwarding, and any routing infrastructure to Helpshift.

Post-Migration Validation Checklist

Do not declare the migration complete until all of the following pass:

• Issue count parity — Total Issues in Helpshift matches total Tickets exported from Trengo, minus any intentionally excluded records (spam, test tickets). Document exclusions.
• Message count per Issue — Spot-check a random 5% sample. Verify thread completeness and chronological order.
• Custom Issue Field integrity — Retrieve 5% of Issues via GET and compare CIF values against source data. This check is essential given silent CIF drop behavior.
• FAQ accuracy — Confirm all articles rendered correctly, including HTML formatting, images, and links. Test rendering in the Helpshift mobile SDK, not just the browser admin view.
• Multi-locale FAQs — If applicable, verify each language variant is present and correctly attributed to the right locale.
• Tag application — Verify tags on Issues match original Trengo labels. Check case.
• User profiles — Confirm end-user data imported correctly via User Hub with correct identifiers.
• Agent assignment — Spot-check that Issues are assigned to correct agents where applicable.
• Private notes isolation — Verify private notes are not visible on the customer-facing thread.
• Timestamp accuracy — Check created_at on a sample of Issues against Trengo source data.

Use Helpshift's GET Issues API with created_since/created_until time-range filters to retrieve all Issues in your migration window for count comparison.

What You'll Lose in This Migration

Common Failure Modes by Severity

Critical Blockers (will prevent migration from running)

1. Integrations API not enabled — The Helpshift REST API is disabled by default. A 403 Forbidden on your first API call means this feature is not enabled. Contact Helpshift support to enable it. Factor in 1–3 business days lead time.
2. Custom Issue Fields not pre-created — Attempting to set CIFs on Issues before creating the field definitions in the Dashboard results in silent data loss. The API returns 200 OK with no indication that the field was dropped. Always run a test batch of 10 Issues and retrieve them via GET to verify CIF presence before the full run.

Data Quality Issues (will corrupt records silently)

3. Tag name mismatch — Tags must match exactly (case-sensitive). "Billing" and "billing" are different tags. If the tag doesn't exist in the Dashboard, it's silently dropped — no error.
4. Tag character limit exceeded — Helpshift enforces a character limit on tag names. Trengo labels exceeding this limit return 400 Bad Request. Add truncation logic in your transformation layer and log all truncations for manual review.
5. CIF type mismatch — If your Trengo data contains values that don't conform to the target CIF type (e.g., free-text string mapped to a date CIF), Helpshift drops the field silently. Audit Trengo data for type consistency before extraction and add type validation in your transform layer.
6. Message ordering — Messages not sorted by created_at before import will produce unreadable conversation threads in Helpshift. Sort ascending at the transform stage, not at import time.

Edge Cases and Scale Issues (appear only at production volume)

7. Trengo rate limit without backoff — At 120 RPM, a script without retry logic will produce incomplete exports. Implement exponential backoff using the Retry-After header value.
8. Pagination ceiling on Helpshift GET — 100 pages × up to 1,000 items = 100,000 Items maximum per unfiltered query. Datasets larger than 100,000 Issues require time-range filter segmentation for validation queries.
9. Orphaned message threads — If the script crashes mid-thread, restarting without idempotency produces duplicate messages. Track committed Trengo message_id values in a local store.
10. Expired Trengo attachment URLs — Attachment URLs in Trengo exports expire. Download all attachments to local storage during export, not at import time.
11. Multi-locale FAQ volume underestimation — If your Help Center has 500 articles in 3 languages, that's 1,500 FAQ API calls, not 500. Recalculate your import time estimates if you have multilingual content.

When to Bring in Help

If your Trengo instance has more than 50,000 tickets, uses heavy multi-channel workflows (email + WhatsApp + voice), relies on complex custom field mappings, or has multilingual Help Center content, migration complexity scales non-linearly. The Trengo rate limit alone means extraction takes 28–36 hours for a 50,000-ticket instance. The channel-to-app model translation and silent CIF drop behavior require careful validation infrastructure that a naive script won't catch.

At ClonePartner, we've built the middleware to handle Trengo's rate limits, Helpshift's app-scoped data model, the messy reality of channel-specific data, and multi-locale FAQ handling. If your engineering team lacks the bandwidth to build, test, monitor, and validate this infrastructure end-to-end, we can handle the full migration.