Helpshift to Zammad Migration: A Technical Guide

Helpshift to Zammad Migration: A Technical Guide

Migrating from Helpshift to Zammad means translating between a mobile-first, issue-based support platform and an open-source, ticket-centric helpdesk — entirely through custom API scripting. There is no native migration tool, no vendor-provided connector, and no built-in import path between these two systems. Zammad's official inbound migrators cover Freshdesk, Kayako, OTRS, and Zendesk, but not Helpshift. (docs.zammad.org)

Helpshift stores support conversations as issues containing messages. Zammad stores them as tickets containing articles. To preserve full conversation history — internal notes, attachments, device metadata, and authorship — you must extract from Helpshift's REST API and load through Zammad's REST API.

This guide covers the full migration architecture: data model mapping, API constraints on both sides, extraction strategies, transform logic, FAQ and knowledge base migration, delta sync implementation, resumability, and the failure modes that trip up engineering teams mid-project.

Verified against: Helpshift REST API v1 and Zammad 6.x/7.x REST API. Helpshift's API lifecycle is subject to change — verify endpoint behavior before scripting.

For details on getting data out of Helpshift, see How to Export Data from Helpshift. For Zammad export patterns useful during parallel testing, see How to Export Data from Zammad. For a side-by-side architecture comparison, see Zammad vs Helpshift: Architecture, TCO & Migration Guide.

Why Teams Move from Helpshift to Zammad

The decision drivers that appear consistently across these migrations, translated into concrete terms:

• Data sovereignty and self-hosting. Helpshift is a closed SaaS platform. Zammad runs self-hosted under AGPL with full infrastructure control. For teams subject to GDPR data residency requirements or SOC 2 audit controls over data location, self-hosting is often non-negotiable.
• Cost structure shift. Helpshift's pricing is consumption-based (per monthly active issue). Zammad's hosted plans start at €7/agent/month; self-hosting is license-free. Teams processing high issue volumes with small agent headcounts — common in mobile gaming — face a nonlinear cost disadvantage under Helpshift's model. A team with 10 agents handling 50K issues/month pays per issue under Helpshift and per agent under Zammad: the crossover point typically favors Zammad above ~5,000 issues/month at comparable agent counts.
• Channel expansion beyond mobile. Helpshift is purpose-built for in-app mobile support. Teams adding email-first, web form, or social channel support find Zammad's multi-channel architecture fits those workflows without bolting on separate tooling.
• Open-source extensibility. Zammad's codebase is on GitHub. Teams that need to customize triggers, automations, or integrations at the code level — without waiting on a vendor roadmap — gain that access.
• Reducing SDK coupling. Helpshift's SDK-driven approach tightly couples your mobile app to its platform at the dependency level. Zammad's REST API and open data model reduce the cost of future migrations (whether you eventually move from Zammad to Zendesk for enterprise routing or Zammad to Help Scout for a shared inbox) or integrations.

Data Model Mapping: Helpshift → Zammad

The core translation challenge is mapping Helpshift's mobile-native, issue-centric model to Zammad's ticket/article architecture.

Custom Issue Field Type Mapping

Helpshift CIFs are typed. Map them explicitly to Zammad object attribute types before building your schema:

Create all Zammad object attributes before starting data load. Schema changes mid-import require re-running migrations and, on self-hosted instances, may require a service restart.

State Mapping

Helpshift uses four primary issue states: new, agent-replied, resolved, and rejected. Zammad's default states are new, open, closed, pending close, and pending reminder. A practical mapping:

Helpshift State    →  Zammad State
─────────────────────────────────────
new                →  new
agent-replied      →  open
resolved           →  closed
rejected           →  closed (with tag "rejected")

If you need to distinguish resolved from rejected in Zammad, create a custom state or use tags. Define this mapping before writing any load code — state mismatches are one of the most common mid-migration surprises.

Migration Sequence

Data dependencies dictate the order. Zammad will reject ticket creation payloads if the associated customer, agent, or group does not exist. Execute your migration in this sequence:

1. Pre-create agents and groups — Map Helpshift assignees to Zammad agent accounts by email. Map each Helpshift app to a Zammad group. Use POST /api/v1/users and POST /api/v1/groups.
2. Create custom object attributes — Define Zammad custom fields for Helpshift metadata, Custom Issue Fields, and the original Helpshift issue ID. Use POST /api/v1/object_manager_attributes, then call POST /api/v1/object_manager_attributes_execute_migrations.
3. Extract and load FAQs into Zammad Knowledge Base (see FAQ migration section below).
4. Extract issues from Helpshift in date-windowed batches.
5. Transform and load tickets with all articles, attachments, and metadata.
6. Validate — Compare issue counts, message counts, and spot-check content.
7. Delta sync — Re-extract issues modified since initial extraction began (see Delta Sync section).

Extracting Data from Helpshift

Issues and Messages

Helpshift's REST API exposes issues at GET /v1/{domain}/issues. Key constraints:

Helpshift recommends an oldest-first export pattern using created_since, created_until, and sort-by=creation-time. This is the right approach because realtime changes can make paged reads inaccurate during iteration. (developers.helpshift.com)

On Helpshift rate limits: The limits are not published. In practice, sustained extraction at high request frequencies triggers 429 responses. Implement exponential backoff starting at 2 seconds, doubling up to a 60-second ceiling, with ±20% jitter. Use 30-day time windows as your default partition — most accounts' busiest months stay under 50K issues at that window size. If a window exceeds 50K, halve the window and re-extract.

import requests
import time
import random
 
DOMAIN = "your-domain"
API_KEY = "your-api-key"
BASE_URL = f"https://api.helpshift.com/v1/{DOMAIN}/issues"
 
def fetch_issues_with_retry(created_since, created_until=None, page=1, page_size=1000, max_retries=5):
    params = {
        "page": page,
        "page-size": page_size,
        "sort-by": "creation-time",
        "sort-order": "asc",
        "created_since": created_since,
    }
    if created_until:
        params["created_until"] = created_until
 
    for attempt in range(max_retries):
        try:
            resp = requests.get(BASE_URL, params=params, auth=(API_KEY, ""), timeout=30)
            if resp.status_code == 429:
                wait = min(2 ** attempt + random.uniform(0, 0.4 * (2 ** attempt)), 60)
                time.sleep(wait)
                continue
            resp.raise_for_status()
            return resp.json()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            wait = min(2 ** attempt + random.uniform(0, 0.4 * (2 ** attempt)), 60)
            time.sleep(wait)
 
def extract_window(created_since, created_until):
    """Extract all issues in a time window, using cursor-based pagination."""
    page = 1
    while True:
        data = fetch_issues_with_retry(created_since, created_until, page=page)
        issues = data.get("issues", [])
        if not issues:
            break
        yield from issues
        total_pages = data.get("total-pages", 1)
        if page >= total_pages:
            break
        page += 1
 
# Partition into 30-day windows to stay under the 50K ceiling
def extract_all_issues(start_ts, end_ts, window_days=30):
    window_seconds = window_days * 86400
    cursor = start_ts
    while cursor < end_ts:
        window_end = min(cursor + window_seconds, end_ts)
        for issue in extract_window(cursor, window_end):
            yield issue
        cursor = window_end

Messages are included inline within the issue response — each issue object contains a messages array with body, author, origin, and attachment fields.

Custom Issue Fields and Metadata

Helpshift separates three types of issue-level data:

1. Metadata — automatically collected device info (OS type, app version, device model, battery level). Read-only.
2. Custom Data — developer-configured key-value pairs passed via the SDK. Nested inside metadata.
3. Custom Issue Fields — structured fields with types (singleline, multiline, dropdown, number, date, checkbox) configured in the dashboard.

All three are included in the issue API response. Plan your Zammad object attribute schema before extraction so you know what to capture.

User Identity

Helpshift issues filed through the mobile SDK often identify users by device ID, not email. For richer identity data, Helpshift's User Hub Bulk APIs run asynchronously and accept up to 10,000 records per request. Use them to retrieve email, phone, platform IDs, language, or LTV data you need in Zammad. (developers.helpshift.com)

Pick a canonical identity key early — email, device ID, or player ID — and apply it consistently across all records. Switching the key mid-import produces duplicate customers in Zammad that are difficult to merge after the fact.

Loading Data into Zammad

Authentication and Notification Suppression

Use token auth for the migration. Zammad supports basic auth, token auth, and OAuth2, but recommends access tokens for automation. The API user must have ticket.agent permission.

Zammad Write Throughput and Elasticsearch Lag

On a self-hosted Zammad instance with 4 CPU cores and 16 GB RAM, Elasticsearch indexing typically keeps pace with API writes up to approximately 2–3 articles per second sustained. Above that rate, the indexing queue falls behind — you'll observe Elasticsearch returning stale or missing results while the import is running. Do not use Zammad's search API to verify data during import; use direct REST API GET endpoints or database queries instead.

Practical guidance:

• Batch ticket creation in groups of 50–100 with a 1–2 second pause between batches.
• For migrations above 50K tickets, plan for Elasticsearch catch-up time after the bulk load completes before declaring the migration done.
• Monitor the indexing queue via Zammad's admin panel or directly via the Elasticsearch API (GET /_cat/indices?v).

Ticket and Article Creation

Zammad's REST API requires a two-step process for tickets with multiple messages (a structural requirement you'll also encounter in other inbound API projects like an Ada to Zammad migration):

1. Create the ticket with the first article via POST /api/v1/tickets.
2. Add remaining articles one at a time via POST /api/v1/ticket_articles.

You cannot create a ticket with multiple articles in a single API call.

import requests
import json
import time
import random
 
ZAMMAD_URL = "https://your-zammad.example.com/api/v1"
HEADERS = {
    "Authorization": "Token token=YOUR_TOKEN",
    "Content-Type": "application/json",
    "X-Zammad-Suppress-Notifications": "true"
}
 
def zammad_post_with_retry(endpoint, payload, max_retries=5):
    for attempt in range(max_retries):
        try:
            resp = requests.post(
                f"{ZAMMAD_URL}/{endpoint}",
                headers=HEADERS,
                data=json.dumps(payload),
                timeout=30
            )
            if resp.status_code in (429, 502, 503, 504):
                wait = min(2 ** attempt + random.uniform(0, 0.4 * (2 ** attempt)), 60)
                time.sleep(wait)
                continue
            resp.raise_for_status()
            return resp.json()
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            wait = min(2 ** attempt + random.uniform(0, 0.4 * (2 ** attempt)), 60)
            time.sleep(wait)
 
def map_state(helpshift_state):
    return {
        "new": "new",
        "agent-replied": "open",
        "resolved": "closed",
        "rejected": "closed",
    }.get(helpshift_state, "open")
 
def map_sender(origin):
    return "Customer" if origin == "end-user" else "Agent"
 
def create_ticket(issue, first_message, group_name):
    payload = {
        "title": issue.get("title", f"Helpshift Issue {issue['id']}"),
        "group": group_name,
        "customer_id": f"guess:{first_message['author'].get('email', f\"{issue['id']}@helpshift-import.local\")}",
        "state": map_state(issue["state_data"]["state"]),
        "hs_issue_id": issue["id"],  # custom object attribute
        "article": {
            "subject": issue.get("title", "Migrated from Helpshift"),
            "body": first_message["body"],
            "content_type": "text/html" if "<" in first_message["body"] else "text/plain",
            "type": "note",
            "internal": False,
            "sender": map_sender(first_message.get("origin", "end-user"))
        }
    }
    return zammad_post_with_retry("tickets", payload)
 
def add_article(ticket_id, message):
    payload = {
        "ticket_id": ticket_id,
        "body": message["body"],
        "content_type": "text/html" if "<" in message["body"] else "text/plain",
        "type": "note",
        "internal": message.get("is_private", False),
        "sender": map_sender(message.get("origin", "end-user"))
    }
    return zammad_post_with_retry("ticket_articles", payload)

Article Type: note vs email

Choose article types deliberately. note is non-communicating — safe for history replay. email carries channel semantics but can trigger side effects. Zammad explicitly warns that internal: true does not by itself stop email sending. Default to note for migrated history unless mail semantics are a hard requirement. (docs.zammad.org)

Creating Articles on Behalf of Users

Zammad supports creating tickets on behalf of other users — essential for preserving the original customer identity. Use customer_id with guess:{email} on ticket creation, and origin_by_id on article creation to attribute messages to the correct agent or customer.

Handling Helpshift Users Without Email

Zammad requires an email address for customer records. Helpshift issues filed through the mobile SDK often identify users by device ID only. Options:

• Generate synthetic emails: {helpshift_user_id}@helpshift-import.local — creates individual customer records you can later merge or update when real addresses are available. This is the cleanest approach.
• Map to a catch-all account — loses individual user tracking.
• Use any email from Helpshift's user profile if available via User Hub Bulk APIs.

Handling Attachments

Helpshift provides attachment URLs in message payloads. Zammad accepts attachments as base64-encoded data in article creation requests. The process:

1. Parse the attachment URL from the Helpshift message.
2. Download the file to your local staging environment.
3. Base64-encode the binary content.
4. Include it in the Zammad article payload.

import base64
import mimetypes
import requests
 
def download_and_encode_attachment(url, api_key):
    resp = requests.get(url, auth=(api_key, ""), timeout=60)
    resp.raise_for_status()
    encoded = base64.b64encode(resp.content).decode("utf-8")
    content_type = resp.headers.get("Content-Type", "application/octet-stream")
    return encoded, content_type
 
def add_article_with_attachments(ticket_id, message, api_key):
    attachments = []
    for att in message.get("attachments", []):
        try:
            encoded_data, mime_type = download_and_encode_attachment(att["url"], api_key)
            # Skip attachments over 20MB after encoding (base64 adds ~33%)
            if len(encoded_data) > 20 * 1024 * 1024 * 4 // 3:
                log_skipped_attachment(ticket_id, att)
                continue
            attachments.append({
                "filename": att.get("file_name", "attachment"),
                "data": encoded_data,
                "mime-type": mime_type
            })
        except Exception as e:
            log_skipped_attachment(ticket_id, att, error=str(e))
 
    payload = {
        "ticket_id": ticket_id,
        "body": message["body"],
        "content_type": "text/html" if "<" in message["body"] else "text/plain",
        "type": "note",
        "internal": message.get("is_private", False),
        "sender": map_sender(message.get("origin", "end-user")),
        "attachments": attachments
    }
    return zammad_post_with_retry("ticket_articles", payload)
 
def log_skipped_attachment(ticket_id, att, error=None):
    # Write to staging DB for manual review
    pass

Migrating Helpshift FAQs to Zammad Knowledge Base

Helpshift organizes help content as FAQs grouped into FAQ Sections. Zammad's Knowledge Base uses Answers grouped into Categories — a direct structural match.

The migration flow:

1. Extract FAQ sections from Helpshift via GET /v1/{domain}/faqs → create Zammad KB categories via POST /api/v1/knowledge_bases/{kb_id}/categories.
2. Extract individual FAQs → create Zammad KB answers via POST /api/v1/knowledge_bases/{kb_id}/answers.
3. Zammad answers require translations_attributes containing title, locale, and content_attributes.body.

def create_kb_answer(kb_id, category_id, faq, locale="en-us"):
    """
    Create a Zammad Knowledge Base answer from a Helpshift FAQ.
    translations_attributes holds one entry per locale.
    content_attributes.body accepts HTML.
    """
    import html
    clean_body = sanitize_html(faq.get("body", ""))  # strip SDK-injected elements
 
    payload = {
        "category_id": category_id,
        "translations_attributes": [
            {
                "title": faq.get("title", "Untitled"),
                "locale": locale,
                "content_attributes": {
                    "body": clean_body
                }
            }
        ]
    }
    resp = requests.post(
        f"{ZAMMAD_URL}/knowledge_bases/{kb_id}/answers",
        headers=HEADERS,
        data=json.dumps(payload),
        timeout=30
    )
    resp.raise_for_status()
    return resp.json()
 
def create_kb_category(kb_id, section_name, locale="en-us", parent_id=None):
    payload = {
        "translations_attributes": [
            {"title": section_name, "locale": locale}
        ]
    }
    if parent_id:
        payload["parent_id"] = parent_id
    resp = requests.post(
        f"{ZAMMAD_URL}/knowledge_bases/{kb_id}/categories",
        headers=HEADERS,
        data=json.dumps(payload),
        timeout=30
    )
    resp.raise_for_status()
    return resp.json()

If your Helpshift FAQs are multi-language, create a translations_attributes entry for each locale. Watch for HTML formatting differences — Helpshift FAQ bodies may include mobile-specific markup or SDK-injected elements that render poorly in Zammad's knowledge base. Run content through an HTML sanitizer before import.

This is not a drop-in replacement for Helpshift bot trees or SDK-driven self-service. Those workflows need to be redesigned in Zammad.

Timestamp Preservation

One of the hardest problems in any helpdesk migration. Zammad's API sets created_at and updated_at server-side when creating tickets and articles. The standard API does not document these as accepted fields in create payloads — created_at appears in API responses but not as a writable input. (docs.zammad.org)

Workarounds for self-hosted Zammad:

• Direct database writes: After API import, update created_at timestamps directly in PostgreSQL/MySQL. Risk: this bypasses Zammad's business logic and Elasticsearch indexing. You must re-index after updating timestamps.
• Rails console: Use Zammad's Rails console to update timestamps with model callbacks: Ticket.find(id).update_columns(created_at: original_ts) followed by a manual re-index call.

For hosted Zammad instances, you have no database access. Your only option is to store original Helpshift timestamps in custom fields (hs_created_at, hs_updated_at) and accept that Zammad's native timestamps reflect the migration date.

If exact historical timestamps are a hard requirement, test the workaround against your specific Zammad version early and plan for it before you start loading data.

Handling Helpshift Device Metadata

Helpshift automatically captures device-level metadata through its SDK: OS version, device model, app version, screen resolution, carrier info, battery level, and more. Zammad has no native equivalent.

Three options:

1. Custom object attributes on the ticket. Create dedicated fields in Zammad for key metadata like device_model, os_version, app_version. Best if you actively query or filter on this data post-migration.
2. Structured note as the first internal article. Dump the full metadata JSON as an internal article on each ticket. Searchable via Elasticsearch but not filterable as a field.
3. Drop it. If you don't use device metadata for reporting or routing post-migration, don't carry it over.

Option 1 is the most operationally useful. Option 2 is the cheapest to implement. Be honest about which metadata fields you actually use before over-engineering the schema — teams routinely design for Option 1 and discover post-migration that they never filter on device fields.

Delta Sync: Capturing Changes During Migration

The gap between "extract everything" and "handle changes during cutover" is where migrations actually fail. A backfill of large datasets takes days. During that time, Helpshift issues continue to be created and updated. Your cutover plan must account for this.

Webhook-Driven Delta Capture

Helpshift supports webhooks for real-time event delivery. (developers.helpshift.com) Configure a webhook receiver at the start of your backfill to capture all changes during the extraction window. The webhook payload includes the full issue object and a meta.action field indicating the event type (issue-created, issue-replied, issue-resolved, etc.).

# Minimal Flask webhook receiver for delta capture during migration
from flask import Flask, request, jsonify
import sqlite3
import json
import hmac
import hashlib
 
app = Flask(__name__)
WEBHOOK_SECRET = "your-helpshift-webhook-secret"
 
def verify_signature(payload_bytes, signature_header):
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")
 
@app.route("/helpshift-webhook", methods=["POST"])
def receive_webhook():
    if not verify_signature(request.data, request.headers.get("X-Helpshift-Hmac-Sha256")):
        return jsonify({"error": "invalid signature"}), 401
 
    event = request.json
    issue_id = event.get("issue", {}).get("id")
    action = event.get("meta", {}).get("action")
 
    conn = sqlite3.connect("migration_progress.db")
    conn.execute("""
        INSERT OR REPLACE INTO delta_events (helpshift_issue_id, action, payload, received_at)
        VALUES (?, ?, ?, CURRENT_TIMESTAMP)
    """, (issue_id, action, json.dumps(event)))
    conn.commit()
    conn.close()
    return jsonify({"status": "ok"}), 200

Delta Processing Logic

After the initial backfill completes:

1. Query delta_events for all issue IDs that received events after your extraction start timestamp.
2. For issues already migrated (present in migration_log): fetch the current Helpshift issue state and update the Zammad ticket accordingly.
3. For new issues (not present in migration_log): run them through the full extract → transform → load pipeline.

def process_delta_events(conn):
    cursor = conn.execute("""
        SELECT DISTINCT helpshift_issue_id FROM delta_events
        WHERE received_at > (SELECT MIN(created_at) FROM migration_log)
    """)
    issue_ids = [row[0] for row in cursor.fetchall()]
 
    for issue_id in issue_ids:
        migrated = conn.execute(
            "SELECT zammad_ticket_id FROM migration_log WHERE helpshift_issue_id = ? AND status = 'done'",
            (issue_id,)
        ).fetchone()
 
        # Fetch current state from Helpshift
        issue = fetch_issue_by_id(issue_id)
 
        if migrated:
            # Update existing Zammad ticket
            zammad_ticket_id = migrated[0]
            sync_ticket_updates(zammad_ticket_id, issue)
        else:
            # New issue created during backfill
            load_issue_to_zammad(issue)

API-Based Delta as Fallback

If webhooks are not available on your Helpshift plan, use the updated_since filter on the issues endpoint: GET /v1/{domain}/issues?updated_since={backfill_start_timestamp}. This returns all issues modified since that timestamp. Run this after your initial backfill completes and process the results the same way.

API Rate Limits

Helpshift

Helpshift's rate limits are not publicly documented. Sustained high-frequency extraction triggers 429 responses. Implement exponential backoff starting at 2 seconds, doubling per retry, with ±20% jitter, capping at 60 seconds. The 50K pagination ceiling is the larger structural constraint — partition by 30-day created_since windows to work around it. If any 30-day window approaches 50K issues, halve the window.

Zammad

Self-hosted Zammad instances have no built-in rate limiter by default, but database and Elasticsearch bottlenecks become the effective ceiling. At sustained rates above ~2–3 articles/second on typical hardware, Elasticsearch indexing falls behind. Batch writes in groups of 50–100 with 1–2 second pauses. On Zammad's SaaS offering, you are subject to their infrastructure limits.

Building for Resumability

Migrations of significant size will fail partway through. Network errors, API timeouts, and rate limit hits are inevitable. Your script must be resumable and idempotent.

Track progress in a local database: map each Helpshift issue_id to its Zammad ticket_id and a status flag.

import sqlite3
 
def init_tracking_db():
    conn = sqlite3.connect("migration_progress.db")
    conn.execute("""
        CREATE TABLE IF NOT EXISTS migration_log (
            helpshift_issue_id TEXT PRIMARY KEY,
            zammad_ticket_id INTEGER,
            status TEXT DEFAULT 'pending',
            error_message TEXT,
            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    """)
    conn.execute("""
        CREATE TABLE IF NOT EXISTS delta_events (
            helpshift_issue_id TEXT,
            action TEXT,
            payload TEXT,
            received_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
            PRIMARY KEY (helpshift_issue_id, received_at)
        )
    """)
    conn.commit()
    return conn

Before creating a ticket in Zammad, check if that Helpshift issue ID already has a Zammad ticket in your tracking table. Also store the original Helpshift issue ID in a hs_issue_id custom field on the Zammad ticket as a secondary check — resume logic based only on local checkpoint files tends to fail when workers are restarted or batches are retried.

Store extracted Helpshift data in a local staging database (SQLite or PostgreSQL) before loading into Zammad. Do not pipe data directly from one API to the other in memory. The staging layer gives you resumability, allows re-runs, and makes debugging transform issues far easier.

Edge Cases and Failure Modes

• Orphaned agent references. Helpshift issues often reference agents who left the company. Attempting to assign a Zammad ticket to a non-existent agent causes the API call to fail. Maintain a fallback mapping: collect all Helpshift assignee IDs, pre-create any that don't exist in Zammad, or map orphaned assignments to a designated "Legacy Agent" account.
• Notifications leaked. Forgetting the X-Zammad-Suppress-Notifications: true header — or importing replay history as email articles instead of note — blasts customers and agents with notifications for years-old tickets. Test notification suppression on a single ticket before running any batch.
• HTML/plain text mismatch. Helpshift messages from the mobile SDK may be plain text; agent responses may be HTML. Set content_type to text/html or text/plain per article based on content detection, not a blanket default.
• Authorship flattened. Missing sender or origin_by_id on articles makes conversation history unreadable. Every article needs explicit sender attribution.
• Custom fields changed mid-import. Object Manager changes in Zammad trigger migrations and may require a restart on self-hosted instances. All schema changes must be complete and migrations executed before data load begins.
• Elasticsearch lag. Pushing hundreds of thousands of tickets via API at high throughput causes indexing lag. Don't rely on Zammad's search to verify data during import; use the REST API GET endpoints directly.
• Identity never normalized. Pick one canonical identity key (email, device ID, player ID) before extraction and apply it everywhere. Inconsistency produces duplicate Zammad customers that require manual merging after the fact.
• Attachment URL expiry. Helpshift attachment URLs in historic issues may be time-limited. Download attachments during extraction and stage them locally — don't store URLs expecting to fetch them later during the load phase.

Time and Effort Estimation

Rough benchmarks based on typical migration projects:

These estimates assume one engineer with API scripting experience. Add time for custom field schema design, stakeholder validation, and the inevitable mid-migration discoveries.

The biggest variable is attachment volume. A 50K-issue migration with minimal attachments can complete the load phase in 2–3 days at ~2 articles/second. The same 50K issues with heavy screenshot and screen recording attachments — typical in mobile gaming support — can take weeks due to download/upload throughput and base64 payload size. Estimate attachment volume before scoping.

Validation Checklist

After migration, verify:

• Issue count match — total issues extracted from Helpshift = total tickets in Zammad.
• Message count match — total messages per issue = total articles per ticket.
• Attachment integrity — spot-check file sizes and content; verify nothing was silently skipped.
• State mapping — verify resolved/rejected issues are closed in Zammad.
• Agent assignment — verify tickets are assigned to the correct Zammad agents.
• Custom field data — spot-check CIF values transferred to Zammad object attributes.
• Knowledge base content — verify FAQ section → category mapping and article body rendering.
• Search functionality — confirm Elasticsearch has indexed all imported data. Run sample searches against known ticket content.
• Delta events processed — confirm all webhook-captured or API-polled changes during backfill have been applied.
• Notification suppression — verify no emails were sent to customers during the import by checking your email sending logs.

When Not to Migrate Everything

Not every Helpshift issue is worth moving. Consider:

• Resolved issues older than 12–24 months — are they ever referenced? If not, archive to CSV and skip.
• Bot-only conversations — Helpshift's automation can generate high volumes of auto-resolved issues with zero human interaction. These rarely have value in Zammad.
• Rejected/spam issues — unless you need them for audit, leave them behind.

A selective migration runs faster, costs less, and produces a cleaner Zammad instance. Establish a cutoff date and data inclusion criteria with your support team before writing extraction logic.

A Cutover Plan That Keeps Support Running

1. Freeze schema and state mapping before any data load.
2. Prove one app or one date window end-to-end, including delta sync and notification suppression validation.
3. Start webhook receiver (or begin updated_since polling) at the beginning of the backfill so no changes are missed.
4. Backfill history in batches with source IDs and checkpoints.
5. After backfill completes, process all delta events captured during the backfill window.
6. Move agents and routing last — keep agents working in Helpshift until delta sync is complete.
7. Audit counts, spot-check histories, verify unresolved queues, and check KB publication state before turning off Helpshift.
8. Keep Helpshift in read-only access for 2–4 weeks post-cutover as a fallback reference.

For a deeper look at running migrations without downtime, see Zero-Downtime Help Desk Data Migration.

What a Good Migration Looks Like

A successful Helpshift to Zammad migration preserves usable history, correct identity, searchable metadata, and a target workflow your team will actually use. That means conservative article types, aggressive source-side validation, explicit handling of every Helpshift feature that has no direct Zammad equivalent, and a delta sync strategy that closes the gap between backfill start and cutover.

The parts teams consistently underestimate: authorship fidelity, attachment download throughput, resumability when failures occur mid-batch, and the delta window between backfill start and cutover date. These are engineering problems with known solutions — the key is planning for them before you start loading data.