HappyFox to LiveChat Migration: A Technical Guide

HappyFox to LiveChat Migration: A Technical Guide

What This Migration Actually Involves

HappyFox is a traditional, ticket-based help desk that organizes support requests into categories, assigns them to staff members, and tracks them through configurable status workflows. Its data model centers on tickets with full conversation threads (staff replies, client replies, private notes), contacts, contact groups, custom fields, knowledge base articles, tags, and attachments.

LiveChat is a real-time messaging platform built for website chat, WhatsApp, Facebook Messenger, and other messaging channels. Its data model is conversation-centric: every interaction is a chat containing threads, and each thread contains events (messages, files, system messages). LiveChat organizes agents into groups rather than categories or departments.

A critical architectural detail: LiveChat's built-in ticketing system was retired on January 6, 2025. Ticketing now runs through HelpDesk (helpdesk.com), a separate product from the same parent company, Text. HelpDesk integrates directly into the LiveChat agent app and shares the same authentication system. When this guide references the "LiveChat migration target," it means the combined LiveChat + HelpDesk ecosystem.

Teams typically move from HappyFox to LiveChat for three reasons:

1. Chat-first customer engagement. HappyFox handles ticketing well but lacks a native live chat product with the depth of LiveChat's real-time messaging, pre-chat surveys, chat routing, and ChatBot AI integration.
2. Unified chat + ticket workflow. The LiveChat + HelpDesk combination lets agents handle chats and email tickets from one interface without switching platforms.
3. E-commerce and sales focus. LiveChat's marketplace integrations with Shopify, BigCommerce, and Stripe make it a natural fit for teams where support and sales overlap.

The core rule: migrate to the target operating model, not to the target field list. HappyFox's ticket-centric architecture does not map cleanly to LiveChat's chat-and-thread model. Some data will be flattened, some will be externalized, and some will be left in a system that models it better. Treat this as a data-model redesign, not a vendor swap. (support.happyfox.com)

Core Data Model Differences

Before planning any migration, understand where the two platforms diverge structurally:

Migration Approaches

There are five methods for moving data from HappyFox to LiveChat + HelpDesk. None are turnkey.

1. Native CSV Export + Manual Import

How it works: Export tickets from HappyFox via Reports → Exports as CSV/XLSX. HappyFox's support documentation notes that export links expire after three days (support.happyfox.com).

When to use it: A light archive, a contact seed, or a proof of concept for very small datasets (under 500 tickets) where conversation history is not required.

Limitations: HappyFox's CSV export only captures the initial ticket message and subject line. Staff replies, client replies, and private notes are excluded. HelpDesk does not offer a native CSV import tool for bulk ticket creation — you would still need the API or a third-party service to load data.

Complexity: Low (export) / Medium (import)

Verdict: Not viable for any migration where conversation history matters.

2. API-Based Custom Migration

How it works: Extract full ticket data (including all replies, notes, and attachments) from the HappyFox REST API (/api/1.1/json/tickets/), transform it into HelpDesk-compatible payloads, and load it via the HelpDesk API v1 (support.happyfox.com).

When to use it: Any migration where you need complete conversation threads, custom field values, and relational integrity.

Key constraints:

• HappyFox paginates at a maximum page size of 50 records
• Rate limits: 500 GET and 300 POST requests per minute; exceeding either triggers a 10-minute 429 lockout (support.happyfox.com)
• LiveChat message text caps at 16 KB; file uploads hit a 10 MB limit (platform.text.com)
• Timestamp backdating: In our testing, the HelpDesk API v1 does not accept a writable created_at field on ticket creation — the server overwrites it with the import timestamp. Test with a single record on your own instance to confirm current behavior, as this may change. See the Timestamp Preservation section for workarounds.

Pros: Full data fidelity; preserves conversation history; handles custom fields and attachments; repeatable runs.

Cons: Requires real engineering work — retry logic, crosswalk tables, rate-limit handling, and UAT.

Complexity: High

3. Third-Party Migration Services

How it works: Services like Help Desk Migration offer wizard-based tools that connect to source and target platforms and transfer data automatically. LiveChat's marketplace currently lists Help Desk Migration, which supports 70+ customer service platforms (livechat.com).

When to use it: Teams without engineering bandwidth who need a faster path than building custom scripts.

Pricing: Help Desk Migration charges per record. As of mid-2026, their published pricing starts at approximately $39 for up to 300 records (agents + contacts + tickets combined) and scales to several thousand dollars for datasets over 20,000 records. Demo migrations (testing up to 20 records) are free. Verify current pricing on their site, as it changes periodically.

Pros: No coding required; handles common mappings automatically; demo runs available.

Cons: Pricing is per-record (agents, contacts, tickets all count); limited control over field-level transformations; may not support all HappyFox custom field types or complex contact group structures. Inline images and nested custom fields often require manual cleanup.

Complexity: Low to Medium

4. Custom ETL Pipeline

How it works: Build a dedicated Extract-Transform-Load pipeline using tools like Python + pandas, Apache Airflow, or a lightweight queue system (Redis + worker). Data is extracted from HappyFox, written to an intermediate store (JSON files, PostgreSQL, S3), transformed, then loaded into HelpDesk.

When to use it: Enterprise migrations with 50,000+ tickets, complex transformation rules, or requirements for audit trails and rollback capability.

Pros: Full control; supports incremental runs; can handle deduplication, data cleansing, and validation as pipeline stages; audit logging built in.

Cons: Highest development effort; requires infrastructure; overkill for small datasets.

Complexity: High

5. Middleware (Zapier, Make)

How it works: Connect live events between systems after cutover. Zapier exposes LiveChat triggers such as New Chat, Finished Chat, and Chat Changed, plus HappyFox actions like Create Ticket and triggers like New Ticket (zapier.com).

When to use it: Never for historical migrations. Only for forward-syncing new data during a parallel run period while the historical migration executes.

Pros: Quick setup; low-code maintenance.

Cons: Cannot iterate over historical datasets; timeout limits and per-task pricing make backfilling impossible; no attachment support in most scenarios; does not preserve original timestamps; will exhaust API quotas quickly.

Complexity: Low

Approach Comparison

Which Approach to Choose

• Small team, <1,000 tickets, no dev resources: Third-party migration service, accepting minor data loss on edge cases.
• Mid-size, 1,000–50,000 tickets, some dev capacity: API-based custom migration.
• Enterprise, 50,000+ tickets, dedicated dev team: Custom ETL pipeline.
• Transition period, need both platforms running: Middleware for new data + API migration for history.
• One-time migration, conversation history required: API-based custom or managed migration service.

Pre-Migration Planning

Data Audit Checklist

Before writing a single line of migration code, audit your HappyFox instance:

• Ticket count by category and status (active, resolved, closed)
• Contact count and contact group memberships
• Custom fields — list all ticket-level and contact-level custom fields with their types (text, dropdown, date, checkbox, multi-select)
• Knowledge base articles — count by section; identify if you need a separate KB solution
• Attachments — estimate total storage volume; identify tickets with inline images vs. file attachments
• Tags — list all active tags; identify duplicates or near-duplicates
• Smart Rules and SLAs — document all automation rules for manual rebuild
• Canned Actions — export for manual recreation in HelpDesk
• Integrations — list all active HappyFox integrations (Slack, Salesforce, Jira) that need LiveChat/HelpDesk equivalents
• Webhooks — list all configured HappyFox webhooks, their target URLs, and the events they fire on; these must be reconfigured using HelpDesk/LiveChat webhook endpoints
• Connected CRM objects — if accounts, leads, opportunities, or activities live in a connected CRM, audit them now; LiveChat's public data model does not provide first-class CRM-style homes for them
• CSAT data — export aggregate satisfaction survey results from HappyFox Reports before cutover; historical per-ticket CSAT scores cannot be migrated to LiveChat's post-chat survey system
• HappyFox contract end date and data retention policy — confirm how long HappyFox retains data after account cancellation (typically 90 days per their terms, but verify with your account manager before relying on it as a fallback)

Identify What Not to Migrate

Not everything needs to move:

• Spam tickets — filter out tickets tagged as spam or auto-closed with no replies
• Test tickets — exclude internal test data
• Duplicate contacts — merge before migration, not after
• Obsolete custom fields — if a field has not been populated in 12+ months, consider dropping it
• Resolved tickets older than retention policy — if you only need 2 years of history, don't migrate 7

Migration Strategy

For most HappyFox-to-LiveChat migrations, a phased approach by category works best:

1. Migrate all historical data for one HappyFox category.
2. Validate it maps correctly to a HelpDesk team.
3. Proceed to the next category.
4. Execute a final delta sync (catching anything created or updated during the migration window) on the weekend of the cutover. See the Delta Sync Implementation section below for the technical approach.

Migration Architecture

Data Flow

HappyFox API (v1.1)        Transform Layer           HelpDesk API (v1)
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ GET /tickets/   │───▶│ Flatten threads   │───▶│ POST /tickets   │
│ GET /users/     │───▶│ Map categories    │───▶│ POST /agents    │
│ GET /categories/│───▶│ Map custom fields │───▶│ POST /teams     │
│ GET /tags/      │───▶│ Re-key IDs        │───▶│ POST /tags      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

HappyFox API (Source)

• Base URL: https://<instance>.happyfox.com/api/1.1/json/
• API Version: v1.1
• Authentication: HTTP Basic Auth (API Key as username, Auth Code as password)
• Pagination: ?size=50&page=<n> — max 50 records per page
• Rate limits: 500 GET and 300 POST requests per minute; 429 errors trigger a 10-minute lockout (support.happyfox.com)
• Key endpoints:
  • GET /tickets/ — list tickets with pagination
  • GET /ticket/<id>/ — single ticket with full thread
  • GET /users/ — list contacts
  • GET /categories/ — list categories
  • GET /ticket_custom_fields/ — list custom field definitions

HelpDesk API (Target)

• Base URL: https://api.helpdesk.com/v1/
• API Version: v1
• Authentication: OAuth 2.1 via Personal Access Tokens (shared auth system with LiveChat)
• Rate limit: 1,000 requests per 10-minute window per license, shared across all tokens and integrations
• Rate limit headers: X-RateLimit-Remaining, Retry-After
• Key endpoints:
  • POST /v1/tickets — create ticket
  • PUT /v1/tickets/{id} — update ticket
  • GET /v1/tickets — list tickets

LiveChat API (for Chat and Customer Data)

• Current stable version: v3.5
• Base URL: https://api.livechatinc.com/v3.5/
• Authentication: OAuth 2.1 / PATs
• Data model: Chats → Threads → Events
• Constraints: Message text capped at 16 KB; file uploads limited to 10 MB (platform.text.com)
• Customer management via Configuration API

Handling Rate Limits

Both APIs enforce strict rate limits. Your migration script must implement:

1. Exponential backoff with jitter on 429 responses — HappyFox's 10-minute lockout means you cannot just retry immediately
2. Request counting — track calls per window and pause proactively before hitting limits
3. Queue-based architecture — decouple extraction from loading so a rate-limit pause on one side does not block the other
4. Conservative throttling — stay at 70–80% of published limits; occasional bursts from other integrations can push you over, especially since HelpDesk rate limits are per-license across all tokens

import time
import random
import requests
 
def api_call_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Waiting {wait:.1f}s (attempt {attempt + 1})")
            time.sleep(wait)
        else:
            response.raise_for_status()
    raise Exception(f"Max retries exceeded for {url}")

Step-by-Step Migration Process

Step 1: Extract Data from HappyFox

Extract in this order (respects dependencies):

1. Categories → needed to map tickets to HelpDesk teams
2. Custom field definitions → needed to create corresponding fields in HelpDesk
3. Contacts and contact groups → needed before ticket creation
4. Tags → simple list extraction
5. Tickets with full thread data → the bulk of the work
6. Attachments → download and store locally or in S3

You cannot attribute a ticket to an agent or a team if those entities do not exist in HelpDesk yet.

import time
import requests
from requests.auth import HTTPBasicAuth
 
HF_BASE = "https://yourinstance.happyfox.com/api/1.1/json"
auth = HTTPBasicAuth("<API_KEY>", "<AUTH_CODE>")
 
def extract_all_tickets():
    tickets = []
    page = 1
    while True:
        resp = requests.get(
            f"{HF_BASE}/tickets/",
            params={"size": 50, "page": page},
            auth=auth
        )
        if resp.status_code == 429:
            print("Rate limit hit. Sleeping for 600 seconds...")
            time.sleep(600)  # HappyFox 10-minute lockout
            continue
        resp.raise_for_status()
        data = resp.json()
        page_data = data.get("data", [])
        if not page_data:
            break
        tickets.extend(page_data)
        page += 1
        time.sleep(0.2)  # Throttle to stay within 500 GET/min
    return tickets
 
def extract_all_contacts():
    """Extract contacts with contact group membership."""
    contacts = []
    page = 1
    while True:
        resp = requests.get(
            f"{HF_BASE}/users/",
            params={"size": 50, "page": page},
            auth=auth
        )
        if resp.status_code == 429:
            time.sleep(600)
            continue
        resp.raise_for_status()
        data = resp.json()
        page_data = data.get("data", [])
        if not page_data:
            break
        for contact in page_data:
            # Normalize: deduplicate by email
            email = contact.get("email", "").strip().lower()
            if email:
                contact["_normalized_email"] = email
                # Capture contact group for tag-based migration
                contact["_groups"] = [
                    g.get("name") for g in contact.get("contact_groups", [])
                ]
            contacts.append(contact)
        page += 1
        time.sleep(0.2)
    return contacts

Step 2: Transform Data

The transformation layer handles three categories of work:

Structural mapping:

• HappyFox Category ID → HelpDesk Team ID
• HappyFox Staff ID → HelpDesk Agent ID
• HappyFox Contact → HelpDesk Requester (email as deduplication key)
• HappyFox Status → HelpDesk Status (map custom statuses to open/pending/solved/closed)

Thread flattening:

• HappyFox stores ticket updates as an ordered array of objects (staff reply, client reply, private note)
• Each update has a timestamp, by (agent or contact), message, and attachments
• Transform into HelpDesk's message format preserving order and authorship
• Flag private notes correctly so they are not exposed to customers
• Split message bodies exceeding 16 KB if targeting the LiveChat chat model

Custom field transformation:

• Map field types: HappyFox dropdowns → HelpDesk single-select; HappyFox multi-select → may require tags or text
• Validate picklist values exist in the target before loading
• Flatten hierarchical or conditional custom fields into simpler structures — HelpDesk does not support conditional field logic

Step 3: Create Target Structure in HelpDesk

Before loading tickets, set up the receiving structure:

1. Create teams corresponding to HappyFox categories
2. Invite/create agents with correct team assignments
3. Create custom fields in HelpDesk matching HappyFox field definitions
4. Create tags (or let them auto-create on ticket import — pre-creating is safer)
5. Create canned responses manually (no API migration path for Smart Rules)
6. Wait for propagation — LiveChat configuration changes can take up to two minutes to propagate; do not start loading tickets immediately after creating reference data (platform.text.com)

Step 4: Load Data into HelpDesk

Load in dependency order:

1. Agents and teams (if not already created manually)
2. Tickets with messages and custom field values
3. Attachments (as follow-up API calls per ticket — download from HappyFox, re-upload as multipart form data)

For each ticket, persist a source-to-target ID crosswalk. Use HappyFox ticket IDs as external references. Before creating a ticket in HelpDesk, check if one with that external ID already exists — this prevents duplicates on retry and makes the entire pipeline idempotent.

For attachments: HappyFox attachment URLs may be secured behind authentication or may expire. Your script must authenticate and download each file, then re-upload it to HelpDesk. Files over 10 MB must be externalized or compressed. If you do not download and re-host inline images embedded in ticket HTML bodies, they will break as soon as your HappyFox instance is decommissioned.

Step 5: Validate

Run validation checks immediately after each batch:

• Record count: Total tickets in HappyFox vs. total in HelpDesk
• Thread completeness: Sample 50 tickets across categories; verify reply count matches
• Custom field accuracy: Spot-check 20 tickets for correct field values
• Attachment presence: Verify attachments are accessible and downloadable
• Contact linkage: Confirm tickets are linked to the correct requester

Delta Sync Implementation

A phased migration takes days or weeks. Tickets created or updated in HappyFox during that window must be caught up before cutover. Here is the technical approach:

Identifying Changed Records

HappyFox's ticket list endpoint supports filtering by last_modified:

def extract_delta_tickets(since_timestamp):
    """
    Extract tickets created or updated after a given timestamp.
    since_timestamp: ISO 8601 string, e.g., '2026-07-01T00:00:00Z'
    """
    tickets = []
    page = 1
    while True:
        resp = requests.get(
            f"{HF_BASE}/tickets/",
            params={
                "size": 50,
                "page": page,
                "last_modified": since_timestamp
            },
            auth=auth
        )
        if resp.status_code == 429:
            time.sleep(600)
            continue
        resp.raise_for_status()
        data = resp.json()
        page_data = data.get("data", [])
        if not page_data:
            break
        tickets.extend(page_data)
        page += 1
        time.sleep(0.2)
    return tickets

Reconciliation Logic

For each delta ticket, check the crosswalk table:

1. If the HappyFox ticket ID exists in the crosswalk → the ticket was already migrated. Fetch the HelpDesk ticket ID and append any new messages/updates that occurred after the initial migration timestamp.
2. If the HappyFox ticket ID does not exist → it is a new ticket created during the migration window. Run the full transform-and-load pipeline for it.

def reconcile_delta(delta_tickets, crosswalk):
    new_tickets = []
    updated_tickets = []
    for ticket in delta_tickets:
        hf_id = str(ticket["id"])
        if hf_id in crosswalk:
            hd_id = crosswalk[hf_id]
            # Identify updates newer than last sync timestamp
            new_updates = [
                u for u in ticket.get("updates", [])
                if u["timestamp"] > crosswalk[hf_id]["last_synced"]
            ]
            if new_updates:
                updated_tickets.append({
                    "helpdesk_id": hd_id,
                    "new_updates": new_updates
                })
        else:
            new_tickets.append(ticket)
    return new_tickets, updated_tickets

Cutover Sequence

1. Record the timestamp when you begin the final delta extraction.
2. Extract all tickets modified since the last full extraction.
3. Reconcile and load deltas.
4. Freeze HappyFox (set to read-only or disable new ticket creation).
5. Run one final delta extraction using the timestamp from step 1.
6. Load any remaining changes.
7. Switch DNS/chat widget/email forwarding to LiveChat + HelpDesk.

Sample Data Mapping Table

Edge Cases and Challenges

Duplicate Contacts

HappyFox may contain duplicate contacts (same email, different contact IDs) or multiple contacts with similar names but different emails. Deduplicate before migration using email as the canonical key. Otherwise, HelpDesk will create separate requester records for the same person, cross-contaminating ticket histories.

Deleted or Missing Data

• Tickets with deleted contacts: HappyFox retains the ticket but the contact may show as null. Assign a placeholder requester email (e.g., deleted-user@yourdomain.com).
• Custom fields with null values vs. empty strings: HelpDesk may treat these differently. Normalize during transformation.
• Orphaned attachments: Files referenced in ticket HTML that were deleted from HappyFox storage. Log and skip.
• Deleted agents: Stale staff references break loads. Map deleted agents to a catch-all "Former Agent" account or log and skip assignment.
• Invalid dropdown values: Custom field picklist values that exist in HappyFox data but not in the current field definition. Validate before loading.

Contact Groups Without an Equivalent

HappyFox Contact Groups have no direct HelpDesk equivalent. After testing all three options in production migrations, the tag-based approach is the recommended default:

The tag-based approach works best because it preserves the original grouping as searchable metadata without consuming custom field capacity, and it degrades gracefully — if an agent never filters by group, the tags are invisible.

Inline Images in Ticket Bodies

HappyFox ticket bodies may contain inline images referenced as <img src="https://...happyfox.com/..." />. After migration, these URLs will still point to HappyFox servers. If you decommission your HappyFox instance, they break. Options:

• Re-host images and rewrite URLs in the HTML body (complex but correct)
• Download and attach images as regular attachments with a reference note (simpler)
• Accept broken images after HappyFox is deactivated (fast but lossy)

Timestamp Preservation

The HelpDesk API v1 does not support writable created_at on ticket creation (verified in our testing as of mid-2026). All migrated records will display the import date as their creation date. Three concrete workarounds:

1. Custom property: Create a custom field called Original Created Date (type: text or date) and populate it with the HappyFox created_at value. Agents can see the true creation date. This is the recommended approach for most teams.
2. Message prefix: Prepend each ticket's first message with a header line: [Originally created: 2024-03-15T14:22:00Z | Original HappyFox ID: 12345]. Simple, visible, but clutters the message body.
3. External archive: Maintain a lookup table (spreadsheet, database, or JSON file) mapping HelpDesk ticket IDs to original HappyFox timestamps. Useful for reporting but not visible to agents in the UI.

Webhook Reconfiguration

If your HappyFox instance fires webhooks to downstream systems (Slack bots, internal dashboards, CRM sync endpoints, analytics pipelines), those must be reconfigured:

1. Inventory all HappyFox webhooks: Document the event trigger, target URL, payload format, and any authentication headers.
2. Map to HelpDesk/LiveChat equivalents: HelpDesk supports webhooks for ticket events (created, updated, status changed). LiveChat supports webhooks for chat events (incoming_chat, chat_deactivated, etc.) via the Configuration API v3.5.
3. Update payload consumers: HelpDesk webhook payloads use a different schema than HappyFox. Any downstream system parsing HappyFox JSON must be updated to parse HelpDesk/LiveChat JSON.
4. Test in staging: Fire test events and verify downstream systems process them correctly before cutover.

API Failures and Retries

• HappyFox 429: 10-minute lockout. Your script must pause entirely for the full duration, not just retry immediately.
• HelpDesk 429: Check Retry-After header and wait accordingly.
• Idempotency: Use HappyFox ticket IDs as external references. Before creating a ticket in HelpDesk, check if one with that external ID already exists. This prevents duplicates on retry.
• Logging: Log every API call result (success, failure, retry) with the source ticket ID. You will need this for validation and debugging.

Knowledge Base Has No Target

LiveChat and HelpDesk do not include a native knowledge base. If you rely on HappyFox's KB, plan a separate migration to KnowledgeBase.ai (from Text), Confluence, Notion, or another KB tool. This is a separate project with its own scope.

Limitations and Constraints

What Cannot Be Migrated Programmatically

Platform Constraints vs. HappyFox

• No true custom objects: HelpDesk works with tickets, teams, agents, and tags. HappyFox's asset management module has no counterpart.
• Simpler custom field system: HelpDesk custom fields support fewer types than HappyFox's nested, conditional custom fields. Complex hierarchical fields must be flattened.
• Contact Group absence: No organizational grouping for contacts beyond per-ticket requester assignment. Use the tag-based approach described above.
• Rate limits are per-license, not per-key: All integrations on your HelpDesk license share the same 1,000-request/10-minute budget. If you are running other integrations during migration, you are competing for capacity.
• LiveChat file limits: 10 MB per file upload, 16 KB per message text. HappyFox can store larger files.
• Property definitions are hard to change: Published LiveChat properties cannot be deleted, and application-owned property definitions are not editable after creation. Choose names carefully (platform.text.com).
• No writable timestamps: Neither HelpDesk nor LiveChat APIs accept client-supplied created_at values on creation. All migrated data shows the import date. See Timestamp Preservation for workarounds.

Validation and Testing

Pre-Go-Live Validation

1. Record count comparison: Total tickets, contacts, and tags in source vs. target
2. Thread depth check: For sampled tickets, count replies in HappyFox vs. messages in HelpDesk
3. Field-level spot check: Verify 5% of tickets for correct category→team mapping, custom field values, priority, and status
4. Attachment audit: Download 20 random attachments from HelpDesk and verify they match source files (file size, filename)
5. Agent assignment check: Verify assigned agent survived the mapping
6. Timestamp check: Verify original dates are preserved in custom properties or message prefixes

Sampling Strategy

For datasets over 5,000 tickets:

• Validate 100% of tickets from the smallest category (catches mapping edge cases)
• Random-sample 5% of tickets from large categories
• Validate 100% of tickets with 10+ replies (catches thread reconstruction issues)
• Validate 100% of tickets with attachments (catches upload failures)

For targeted risk-based sampling, pick: oldest ticket, newest ticket, longest thread, attachment-heavy ticket, private-note-heavy ticket, deleted-user ticket, and one record per category.

UAT Process

1. Migrate a single category as a pilot
2. Have 2–3 agents review their tickets in HelpDesk for 24 hours
3. Collect feedback on missing data, formatting issues, or broken references
4. Fix issues and re-run the pilot category
5. Once validated, proceed with remaining categories

For a deeper QA framework, see our Post-Migration QA Checklist.

Rollback Plan

Since this is a write-only operation into HelpDesk (HappyFox data is not modified), rollback means:

• Delete migrated data from HelpDesk (if the API supports bulk delete)
• Fix the migration script
• Re-run

Keep your HappyFox instance active and unmodified until migration is fully validated and agents have confirmed the cutover. HappyFox data retention after account cancellation is typically 90 days, but verify with your account manager — do not rely on this as a fallback without written confirmation.

Post-Migration Tasks

Rebuild Automations

Document every HappyFox Smart Rule before migration and recreate them as HelpDesk automated workflows:

• Ticket assignment rules → HelpDesk routing rules
• SLA escalation triggers → HelpDesk SLA policies
• Auto-reply rules → HelpDesk automation workflows
• Auto-tagging rules → HelpDesk tag-based automations

Update Integrations

Replace HappyFox integrations with LiveChat/HelpDesk equivalents:

• Slack notifications → LiveChat Slack app
• CRM sync → LiveChat marketplace (Salesforce, HubSpot apps available)
• Jira integration → HelpDesk Jira app or webhook-based connection
• Custom webhooks → Reconfigure per the Webhook Reconfiguration section

Agent Training

LiveChat + HelpDesk is a different workflow paradigm. Your team is shifting from "working a ticket queue" to "managing active chats and asynchronous threads":

• Agents handle live chats and tickets in the same interface
• Ticket statuses and routing work differently
• Keyboard shortcuts, canned responses, and macros need re-learning
• Plan 1–2 days of guided walkthrough before cutover

Monitor for 2 Weeks Post-Cutover

• Watch for tickets that failed to migrate (check error logs)
• Monitor HelpDesk for orphaned tickets (no requester, no team)
• Verify automated workflows are triggering correctly
• Compare ticket volume in HelpDesk vs. expected inbound rate
• Watch for search gaps, missing attachments, and duplicate contacts
• Verify webhook-fed downstream systems are receiving and processing events correctly

Best Practices

1. Back up everything first. Export HappyFox data via API and store the raw JSON before any transformation. Run a full CSV backup as well. This is your rollback source.
2. Run test migrations. At least two dry runs on a sandbox HelpDesk instance before production. Create a free trial HelpDesk instance for this purpose — it is the single most effective risk mitigation step.
3. Migrate in dependency order. Teams → Agents → Custom Fields → Tags → Tickets → Attachments.
4. Validate incrementally. Don't wait until the end. Check record counts and data integrity after each phase.
5. Throttle conservatively. Stay at 70–80% of published rate limits. Text bills API usage for PAT calls, so repeated dry loads have a real cost (platform.text.com).
6. Log everything. Every API call, every response code, every transformation decision. You will reference these logs during validation.
7. Freeze HappyFox configuration. Institute a change freeze two weeks before migration. Do not allow admins to add new custom fields or categories.
8. Communicate cutover timing. Agents need to know when to stop using HappyFox and start using LiveChat + HelpDesk. Overlap periods create confusion.
9. Keep HappyFox read-only for 30 days. Don't deactivate your HappyFox account until you have confirmed everything migrated correctly and agents are comfortable in the new system. Confirm HappyFox's data retention policy with your account manager before cancellation.
10. Export CSAT data before cutover. Historical satisfaction survey results cannot be migrated. Download aggregate reports from HappyFox for archival.

Automation Script Outline

High-level structure for a Python-based API migration:

# happyfox_to_helpdesk_migration.py
 
import json
import logging
import os
import time
import random
import requests
from pathlib import Path
from requests.auth import HTTPBasicAuth
 
# --- Configuration ---
HF_BASE_URL = os.environ["HF_BASE_URL"]
HF_API_KEY = os.environ["HF_API_KEY"]
HF_AUTH_CODE = os.environ["HF_AUTH_CODE"]
HD_BASE_URL = "https://api.helpdesk.com/v1"
HD_TOKEN = os.environ["HD_PAT"]
 
# --- Rate-limited API call ---
def hf_api_call(endpoint, max_retries=5):
    url = f"{HF_BASE_URL}/{endpoint}"
    auth = HTTPBasicAuth(HF_API_KEY, HF_AUTH_CODE)
    for attempt in range(max_retries):
        resp = requests.get(url, auth=auth)
        if resp.status_code == 200:
            return resp.json()
        elif resp.status_code == 429:
            wait = 600 + random.uniform(0, 30)  # 10-min lockout + jitter
            logging.warning(f"HappyFox 429. Waiting {wait:.0f}s")
            time.sleep(wait)
        else:
            resp.raise_for_status()
    raise Exception(f"Max retries exceeded for {url}")
 
# --- Phases ---
def phase_1_extract():
    """Extract all data from HappyFox. Save as JSON files."""
    extract_categories()        # -> data/categories.json
    extract_custom_fields()     # -> data/custom_fields.json
    extract_contacts()          # -> data/contacts.json (with group membership)
    extract_tags()              # -> data/tags.json
    extract_tickets()           # -> data/tickets/*.json (one per ticket)
    download_attachments()      # -> data/attachments/<ticket_id>/
 
def phase_2_transform():
    """Transform HappyFox data into HelpDesk-compatible format."""
    build_category_to_team_map()
    build_agent_map()
    build_custom_field_map()
    for ticket_file in Path("data/tickets").glob("*.json"):
        transform_ticket(ticket_file)
        # Output: data/transformed/<ticket_id>.json
 
def phase_3_load():
    """Load transformed data into HelpDesk."""
    create_teams()              # Must exist before tickets
    create_custom_fields()      # Must exist before tickets
    create_tags()               # Pre-creating is safer than auto-create
    time.sleep(120)             # Wait for configuration propagation
    load_tickets_with_threads() # Main migration loop
    upload_attachments()        # Post-ticket-creation attachment upload
 
def phase_4_validate():
    """Compare source and target record counts and field values."""
    compare_ticket_counts()
    sample_thread_depth_check(sample_size=100)
    verify_custom_fields(sample_size=50)
    verify_attachments(sample_size=20)
    verify_timestamps_in_custom_properties(sample_size=20)
    generate_validation_report()  # -> reports/validation.html
 
def phase_5_delta_sync(since_timestamp):
    """Catch up tickets created/updated during migration window."""
    delta_tickets = extract_delta_tickets(since_timestamp)
    crosswalk = load_crosswalk()
    new_tickets, updated_tickets = reconcile_delta(delta_tickets, crosswalk)
    load_new_tickets(new_tickets)
    append_updates(updated_tickets)
 
if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    phase_1_extract()
    phase_2_transform()
    phase_3_load()
    phase_4_validate()
    # phase_5_delta_sync("2026-07-15T00:00:00Z")  # Uncomment on cutover day

Making the Right Call

A HappyFox to LiveChat migration is a platform architecture change, not a data copy job. You are moving from a ticket-first system to a chat-first system with a companion ticketing product. The data model mismatch — categories vs. teams, contact groups vs. nothing, rich custom fields vs. basic custom fields, built-in KB vs. no KB, writable timestamps vs. server-generated timestamps — means every migration requires real engineering decisions.

If your target is LiveChat alone, keep the project honest: migrate the conversation history agents actually need and enough metadata to search and explain the archive. If your target is LiveChat + HelpDesk + CRM, design that stack first and load data into the right layer. That is the difference between a clean cutover and a messy compromise.

If your team has the bandwidth and API experience, the custom approach gives you full control. If engineering time is the constraint, a managed migration service eliminates the trial-and-error of navigating two unfamiliar APIs. ClonePartner handles this type of cross-platform helpdesk migration — structural mapping, attachment re-upload, thread reconstruction, delta sync, and post-migration validation — typically completing mid-size migrations (10,000–30,000 tickets) in 5–10 business days. If that fits your situation, book a scoping call.

For related migration guides, see our HappyFox to Zendesk guide and Freshservice to LiveChat guide. For post-migration quality assurance, use our 20-test QA checklist.