HappyFox to LiveAgent migration requires API-based extraction — CSV exports strip conversation history. No native plugin exists. Plan 2–4 weeks for mid-size datasets.
There is no native migration path from HappyFox to LiveAgent — LiveAgent does not include a built-in migration plugin for HappyFox, and HappyFox's CSV export only captures the initial ticket message, omitting staff replies, client replies, private notes, and attachments. The two platforms differ structurally: HappyFox organizes work around Categories (which bundle email forwarding, SLA rules, and assignment logic), while LiveAgent uses simpler Department routing containers with SLA Levels and Rules configured separately. A successful migration requires custom API-based extraction via HappyFox's REST API, transformation of data models (especially Categories to Departments, Contact Groups to Companies, and custom field type mapping), and loading into LiveAgent's REST API v3. Smart Rules, SLA Policies, Canned Actions, and Satisfaction Survey results cannot be migrated programmatically and must be manually rebuilt.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
TL;DR: HappyFox → LiveAgent Migration
A HappyFox to LiveAgent migration requires custom API-based extraction — HappyFox's native CSV export only includes the initial ticket message, not staff replies, client replies, or private notes. LiveAgent does not have a built-in migration plugin for HappyFox. You must extract data via the HappyFox REST API (/api/1.1/json/tickets/), transform it, and load it into LiveAgent via its REST API v3. HappyFox Categories don't map 1:1 to LiveAgent Departments — each requires a structural decision. Smart Rules, SLAs, and Canned Actions cannot be migrated programmatically. A typical mid-size migration (10,000–50,000 tickets) takes 2–4 weeks. (support.happyfox.com) Quick Links: - Help Desk Data Migration Checklist - Post-Migration QA Checklist - HappyFox to Zendesk Migration Guide
Critical: HappyFox Categories ≠ LiveAgent Departments
A HappyFox Category bundles email forwarding addresses, SLA rules, visibility settings, and ticket assignment logic into one object. A LiveAgent Department is a routing container. You'll need to split Category logic across Departments, SLA Levels, and Rules in LiveAgent. Map this before you write a single line of migration code.
Data loss risk
HappyFox's own documentation confirms that through the Tabular view report export, "you will not be able to export the staff/client replies that are updated after the initial message and private notes of a ticket." This makes CSV-only migration unsuitable for any team that needs conversation history.
Status mapping is not obvious
HappyFox has configurable statuses (New, Open, Pending, On Hold, Closed). LiveAgent uses a more rigid model: New, Open, Answered, Resolved, Postponed, Closed (since v5.47+). Map carefully, especially if you have custom statuses in HappyFox. If a HappyFox Category also serves as classification (not just routing), preserve it as a LiveAgent tag in addition to the Department mapping.
Attachment URL expiry
HappyFox attachment URLs in API responses expire in 5 minutes. Your extraction script must download each attachment immediately after retrieving the ticket data. Do not batch-collect URLs and download later. (support.happyfox.com)
LiveAgent API retrieval limits
Since version 5.51, the LiveAgent v1 /conversations API retrieves a maximum of 1,000 records, and the v3 /tickets API is limited to 10,000 records per filtered query. When reading back data for validation, use date-range or department filters to stay within these limits. On large datasets, shard your validation queries by date, department, or tag so you never rely on one broad filter window. (support.liveagent.com)
Test load tip
If you run vendor-assisted or plugin-based migration into LiveAgent, deactivate the Ticket resolved customer email template during test loads to avoid sending accidental notifications to customers. (support.liveagent.com)
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Establish why you are moving, what "done" means, and who signs off.
Objective A written scope with agreed success criteria, a named owner per workstream, and a budget approved by finance.
Keep these open
-
Pull the real numbers out of HappyFox
Export counts for tickets (open and closed separately), contacts, organisations, attachments, macros, triggers, automations, views and SLA policies. Note the oldest ticket date — history depth drives the whole timeline. Estimating from memory is the single most common cause of a blown migration window.
Data Profiler Get real record counts instead of estimating from memory -
Decide what history actually moves
Agree a cut-off with the support lead: all history, last 24 months, or open tickets plus a read-only archive. Every extra year of closed tickets adds API time and cost without adding much agent value. Get this in writing — it is the decision people relitigate mid-cutover.
A "move everything" default is what turns a two-week migration into a two-month one.
COI & ROI Calculator Build the 36-month business case you will need for sign-off -
Confirm LiveAgent can hold your support model
Walk your current workflow through LiveAgent: multi-brand, business hours, SLA targets, CSAT, side conversations, public vs internal notes, and any channel you depend on (voice, chat, WhatsApp, social). List anything with no native equivalent — those are project risks, not configuration details.
-
Build the business case
Model licence delta, migration effort, agent retraining, and the cost of staying put (Cost of Inaction). Executives approve a number, not a plan, and you will be asked for it again at the go/no-go.
Helpdesk Migration Planner Turn ticket volume into a dated HappyFox → LiveAgent timeline -
Name owners and set the go/no-go date
One named owner each for data, configuration, integrations, and agent enablement, plus a decision-maker who can call a rollback. Put the go/no-go meeting in calendars now, 48 hours before the freeze.
HappyFox → LiveAgent specifics
- Enterprise, >50K tickets
- Managed migration service or dedicated ETL pipeline
- Parallel-run period
- Middleware for new tickets + API migration for historical data
Don't move on until
- Record counts confirmed for tickets, contacts, organisations and macros
- Success criteria signed off by the support lead
- Freeze window provisionally booked with the business
02 Data Audit Find out what is actually in the data before you try to move it.
Objective A profiled, cleaned export with every quality defect either fixed at source or explicitly accepted.
Keep these open
-
Take a full HappyFox export and profile it
Export to CSV or JSON and profile every file: row counts, null rates per column, distinct values, and type consistency. Compare row counts against the API totals from Discovery — a gap here means your export is silently truncated, usually by pagination.
Data Profiler Profile the HappyFox export for nulls, outliers and type drift -
Validate file structure before anyone writes a transform
Check delimiters, quoting, encoding (expect UTF-8, watch for BOMs and Latin-1), duplicate headers, and embedded newlines in ticket bodies. Ticket descriptions with raw newlines and commas break naive CSV parsers and silently shift columns.
A single unescaped quote in one ticket body can shift every subsequent column without any error.
CSV Validator Catch broken headers and ragged rows in the raw export -
Inventory PII and set retention
Scan for emails, phone numbers, payment card fragments, national IDs and anything else regulated in ticket bodies and custom fields — support tickets are where customers paste things they should not. Decide what gets migrated, masked, or dropped, and record the legal basis.
Ticket bodies and attachments routinely contain card and ID data that never appears in a structured field.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Quantify duplicates, orphans and dead references
Count duplicate contacts (same email, different casing), tickets whose requester no longer exists, organisations with no members, and attachments whose parent ticket is gone. Fix these in HappyFox where you can — migrating them just moves the mess.
Data Cleaner Strip empty rows, stray whitespace and dead columns -
Clean and normalise the export
Trim whitespace, drop empty rows and columns, normalise casing on emails and tags, and standardise every timestamp to UTC ISO 8601. Timezone drift is invisible at load time and shows up weeks later as SLA reports nobody can reconcile.
-
Produce a masked copy for sandbox work
Generate a realistic but fake version of the export for testing and for any vendor who needs sample data. Loading real customer PII into a sandbox is a breach in most jurisdictions, and sandboxes are rarely covered by your DPA.
PII Masker Generate a safe copy for sandbox and vendor testing
HappyFox → LiveAgent specifics
- HTML cleanup
- Strip proprietary HappyFox CSS classes from message bodies; LiveAgent expects well-formatted HTML
Don't move on until
- Export parses cleanly with no ragged rows or encoding errors
- PII inventory complete and retention decisions recorded
- Duplicate and orphan records quantified and triaged
03 Field Mapping Turn two schemas into one signed-off mapping spec.
Objective A reviewed field-level mapping covering every object, with an explicit decision for every field that has no target.
Keep these open
-
Generate the first-pass HappyFox → LiveAgent field map
Start from an automated match on both schemas, then review every row by hand. Automated matching gets the obvious 70% right and is confidently wrong on the rest — especially anything named "type", "status" or "custom_field_1".
Schema Mapper Opens pre-loaded with the HappyFox → LiveAgent field pair -
Map status, priority and channel values, not just field names
Enumerate every value in each picklist on both sides and map them explicitly. Value-level mismatches are the defect class that survives all the way to production because the field itself mapped fine — a ticket that should be "Pending" arriving as "Open" reopens SLA clocks.
Statuses with no target equivalent (on-hold, pending-customer) need a policy decision, not a best guess.
-
Decide how custom fields land
Create the target custom fields first, matching type exactly (a dropdown mapped to free text can never be mapped back). Where LiveAgent has no equivalent, decide between a new custom field, a tag, or a note appended to the ticket body — and record which.
-
Resolve identity and threading
Decide how source IDs are preserved — most platforms will not let you set the primary key, so keep the original ID in a custom field. Without it, reconciliation becomes fuzzy matching and every future support question about an old ticket is unanswerable.
Losing the original ticket ID makes reconciliation and rollback effectively impossible.
-
Plan attachments, inline images and threading order
Confirm size limits, allowed MIME types, and whether inline images survive as attachments or need rehosting. Decide the comment ordering and author attribution rules: comments loaded out of order, or all attributed to the API user, destroy the conversation history agents rely on.
-
Freeze and sign off the mapping spec
Version the spec, walk the support lead through it row by row, and get explicit sign-off. Any change after this point goes through change control — mid-flight mapping edits are how partial loads happen.
-
Contact deduplication
Merge duplicate contacts by email before loading
HappyFox → LiveAgent specifics
- Status mapping
- Convert HappyFox status names to LiveAgent status codes
- Category → Department
- Replace HappyFox category IDs with pre-created LiveAgent department IDs
- Agent mapping
- Map HappyFox staff IDs to LiveAgent agent IDs (match by email)
- Custom field conversion
- Ensure data types match (e.g., HappyFox dropdown values → LiveAgent list values)
- Thread reconstruction
- Flatten HappyFox updates [] array into individual messages with preserved timestamps and sender attribution
Don't move on until
- Every source field is mapped, deliberately dropped, or parked in a custom field
- Status, priority and channel value maps agreed with the support lead
- Mapping spec version-controlled and signed off
04 Test Migration Prove the pipeline on a small, representative slice.
Objective A pilot load into a LiveAgent sandbox that reconciles cleanly and has been reviewed by real agents.
Keep these open
-
Stand up a LiveAgent sandbox that matches production config
Create the custom fields, groups, brands, business hours and SLA policies first. A pilot into a default sandbox tests nothing, because the failures you care about are all configuration mismatches.
-
Pick a deliberately nasty pilot sample
Take 500-1000 records chosen for difficulty, not convenience: the longest ticket threads, tickets with the most attachments, non-Latin character sets, merged and split tickets, deleted requesters, and every status value. A clean random sample proves only that easy records are easy.
-
Run the load with masked data and instrument everything
Log every API request and response with its source record ID. When 40 records fail out of 10,000 you need to know exactly which ones and why, without re-running the whole batch.
PII Masker Never load real customer PII into a sandbox -
Measure real throughput against the rate limit
Record achieved records-per-hour under LiveAgent's actual rate limits, including retries and backoff. Extrapolate to the full volume: if the maths says the full load exceeds your freeze window, you fix that now, not on cutover night.
Published rate limits are ceilings, not throughput. Assume real-world rates are meaningfully lower once retries and backoff are counted.
-
Reconcile the pilot and triage every failure
Diff source against target on record counts and field-level values. Every discrepancy gets a root cause and a fix — "probably fine" at pilot scale becomes thousands of broken records at full scale.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Put real agents in front of the pilot data
Have two or three agents work sample tickets end to end in the sandbox. They find the things reconciliation cannot see: unreadable threading, missing context, macros that no longer make sense. Fix the mapping, then re-run.
Don't move on until
- Pilot batch reconciles to 100% on record counts
- Agents have reviewed sample tickets and confirmed they are workable
- Measured throughput extrapolates to a viable full-load window
05 Cutover Execute the switch inside a controlled, reversible window.
Objective All in-scope data live in LiveAgent, agents working in the new system, and a rollback path that stayed available throughout.
Keep these open
-
Pre-load history before the freeze
Load closed tickets and contacts days or weeks ahead while HappyFox stays live. Only open tickets and the final delta need to move inside the freeze — this is the single biggest lever on window length.
Helpdesk Migration Planner Size the freeze window from LiveAgent's real API limits -
Publish the runbook with times, owners and abort criteria
A timed sequence: freeze start, final export, delta load, channel switch, smoke test, go/no-go, agent switch. Name who does each step and the explicit condition that triggers a rollback. Decide the abort criteria before the night, when nobody wants to be the one to call it.
-
Freeze HappyFox and take the final delta
Stop new ticket creation, let agents finish in-flight replies, then export everything changed since the pre-load. Announce the freeze to the whole business, not just support — someone always tries to raise a ticket during it.
Tickets created during an unenforced freeze land in the old system and are the most common source of permanently lost data.
-
Load the delta and open tickets
Run the delta load, then reconcile counts before touching any channel. Do not repoint email until the delta has verified — an inbound ticket arriving mid-load is far harder to untangle than a few extra minutes of freeze.
Migration Validation Tool Confirm the final delta landed before you reopen -
Repoint channels and verify with live traffic
Switch email forwarding and MX or connector settings, update chat widgets and web forms, and re-authorise integrations. Then send real test tickets through every channel and confirm each lands, routes and triggers the right automation.
Email forwarding changes can take up to a full DNS TTL to propagate — check the TTL days in advance and lower it if needed.
Cron Expression Builder Schedule the delta syncs that run through the freeze -
Run the go/no-go and switch the agents
Walk the exit criteria with the decision-maker, call it explicitly, then move agents over with a named person on hand for the first few hours. Keep HappyFox read-only rather than cancelled — cancelling the old contract on day one removes your only fallback.
Don't move on until
- Full historical load complete and counts matched
- Inbound channels repointed and verified with live test tickets
- Rollback decision point passed explicitly, not by default
06 Validation Prove the migration is complete, then close it out.
Objective Documented evidence that data, workflow and reporting all survived, and a signed acceptance.
Keep these open
-
Run the full reconciliation
Compare source and target on every object: total counts, counts by status, counts by group, attachment counts, and field-level spot checks on a random sample. Produce one report you can hand to an auditor.
Migration Validation Tool Reconcile HappyFox and LiveAgent record-for-record -
Verify field completeness, not just record counts
Re-profile the loaded data and compare null rates per field against the source profile. Matching record counts with a field that silently arrived empty is the failure mode counts alone will never catch.
Data Profiler Prove field completeness held up through the load -
Rebuild reporting and compare against baselines
Recreate your core dashboards — volume, first response time, resolution time, CSAT — and compare to pre-migration figures for the same period. Explain every variance; a changed SLA calculation is a real finding, not a rounding error.
SLA and first-response metrics are usually recalculated from the loaded timestamps, so they will differ if any timestamp mapping was approximate.
-
Test the workflow layer end to end
Fire every trigger, automation, SLA escalation, macro and notification with a live ticket. Workflow does not migrate — it gets rebuilt — so it is untested until someone has actually watched it run.
-
Confirm compliance and produce the audit trail
Re-scan the loaded data for regulated fields, confirm retention and deletion policies are configured in LiveAgent, and file the evidence with your PII decisions from the audit phase.
PII & Compliance Scanner Produce the compliance evidence your auditor will ask for -
Sign off, then decommission on a schedule
Get written acceptance against the Discovery success criteria. Keep HappyFox read-only for an agreed period (30-90 days is typical), take a final archive export, and only then cancel. Diarise the decommission date so it does not quietly renew.
Don't move on until
- Full reconciliation report attached to the project record
- Reporting baselines match pre-migration figures within agreed tolerance
- Formal acceptance signed and archive retention scheduled
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Concept Equivalent
| HappyFox field | LiveAgent field | Notes |
|---|---|---|
| Ticket | Ticket (Conversation) | LiveAgent treats every inbound message as a conversation that becomes a ticket |
| Category | Department | HappyFox Categories contain email config + SLA rules; LiveAgent Departments are simpler routing containers |
| Contact | Contact (Customer) | 1:1 mapping, but custom field schemas differ |
| Contact Group | Company | LiveAgent's Company object is the closest equivalent. One LiveAgent contact can belong to only one company. (support.liveagent.com) |
| Agent / Staff | Agent | Role and permission models differ |
| Tags | Tags | Direct mapping |
| Custom Fields (Ticket) | Ticket Custom Fields | LiveAgent supports text, list, checkbox, and date types |
| Custom Fields (Contact) | Contact Custom Fields | Type compatibility must be verified per field |
| Smart Rules | Rules (Automation) | Cannot be migrated; must be rebuilt manually |
| Canned Actions | Predefined Answers | Manual recreation required |
| SLA Policies | SLA Levels | Manual recreation; HappyFox ties SLAs to Categories, LiveAgent configures them separately from Departments |
| Knowledge Base Articles | Knowledge Base Articles | Formatting may need adjustment — different rich-text editors |
| Satisfaction Surveys | Satisfaction Plugin | Different configuration model; survey results typically cannot be migrated as structured data |
| Attachments | Attachments | HappyFox attachment URLs expire in 5 minutes — must be downloaded immediately during extraction |
| Private Notes | Internal Notes | 1:1 mapping within ticket threads; LiveAgent notes are agent-only |
| Assets | No direct equivalent | Keep in external system, flatten into custom fields, or serialize into notes (support.happyfox.com) |
HappyFox Fields LiveAgent Fields
| HappyFox field | LiveAgent field | Notes |
|---|---|---|
| id (Ticket ID) | Custom field (original_id) | Store as reference for validation |
| subject | subject | Direct mapping |
| status | status | Map: New→New (I), Open→Open (T), Pending→Postponed (P), Closed→Resolved (R) |
| priority | priority | Map HappyFox priority IDs to LiveAgent priority levels |
| category | departmentid | Requires pre-created Department mapping table |
| assignee | agentid | Requires pre-created Agent mapping table; match by email |
| created_at | date_created | Preserve original timestamp; HappyFox API returns UTC |
| last_updated_at | date_changed | Preserve original timestamp |
| tags | tags | Direct mapping; pre-create tags in LiveAgent |
| contact.name | customer_name | Direct mapping |
| contact.email | customer_email | Direct mapping; used as unique contact identifier |
| updates [] (replies) | Messages (via API) | Each update becomes a message in the LiveAgent ticket thread |
| updates [].attachments | Attachments | Download from HappyFox (URLs expire in 5 min), upload to LiveAgent |
| Custom fields | Custom fields | Create matching fields in LiveAgent first; map by field ID |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Tickets | medium | Full ticket threads including replies and notes can be migrated via the HappyFox API, but CSV export only captures the initial message, and API pagination and rate limits require careful orchestration. |
| Contacts | low | Contacts map 1:1 between platforms, though custom field schemas differ and type compatibility must be verified per field. |
| Contact Groups / Companies | medium | HappyFox Contact Groups map to LiveAgent Companies, but LiveAgent limits each contact to a single company, potentially breaking multi-group associations. |
| Custom Fields | medium | LiveAgent supports text, list, checkbox, and date custom field types, but HappyFox's hierarchical custom field system may include types or structures that don't map directly and require transformation. |
| Attachments | high | HappyFox attachment URLs expire after only 5 minutes, requiring immediate download during extraction and making large-volume attachment migration particularly error-prone. |
| Tags | low | Tags map directly between HappyFox and LiveAgent with no structural differences. |
| Knowledge Base Articles | medium | Articles can be migrated but formatting may require adjustment due to differences in rich-text editors, and HappyFox's multi-brand KB structure has no direct LiveAgent equivalent. |
| Smart Rules / Automations | high | HappyFox Smart Rules cannot be migrated programmatically and must be manually recreated as LiveAgent Rules, which follow a different configuration paradigm. |
| SLA Policies | high | HappyFox ties SLAs to Categories while LiveAgent configures SLA Levels separately from Departments, requiring complete manual redesign and recreation. |
| Assets | high | LiveAgent has no direct equivalent to HappyFox's asset management objects, so asset data must be flattened into custom fields, serialized into notes, or retained in an external system. |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
CSV Export Data Loss
HappyFox's native CSV export only includes the initial ticket message and subject, completely omitting staff replies, client replies, private notes, and attachments, making it unsuitable for any migration requiring conversation history.
Category-to-Department Mapping
HappyFox Categories bundle email forwarding, SLA rules, visibility settings, and assignment logic into one object, whereas LiveAgent Departments are simple routing containers, requiring this logic to be split across Departments, SLA Levels, and Rules.
Attachment URL Expiration
HappyFox attachment URLs expire after just 5 minutes, requiring download scripts to fetch and buffer attachments immediately during extraction before they become inaccessible.
API Rate Limit Constraints
LiveAgent enforces a rate limit of 180 requests per minute per API key, and HappyFox paginates at a maximum of 50 records per page, requiring careful throttling and exponential backoff for HTTP 429 errors during large migrations.
Non-Migratable Automation Objects
Smart Rules, SLA Policies, Canned Actions, and Satisfaction Survey configurations cannot be migrated programmatically and must be manually recreated in LiveAgent's different configuration model.
Contact Group to Company Mismatch
HappyFox Contact Groups map to LiveAgent Companies, but LiveAgent restricts each contact to only one company, which can break relationships if contacts belong to multiple groups in HappyFox.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Can I migrate conversation history from HappyFox to LiveAgent?
Yes, but only via the HappyFox REST API. HappyFox's native CSV export only includes the initial ticket message — staff replies, client replies, and private notes are not exported. You must use the API endpoint /api/1.1/json/ticket/<id>/ to extract full thread data, then load it into LiveAgent via its REST API v3.
Does LiveAgent have a built-in migration plugin for HappyFox?
No. LiveAgent offers built-in migration plugins for Zendesk, Freshdesk, Help Scout, Intercom, Kayako, Jira, and several others, but HappyFox is not currently supported. You need to use the HappyFox API for extraction and LiveAgent's API for loading, or use a third-party migration service.
How long does a HappyFox to LiveAgent migration take?
A typical mid-size migration (10,000–50,000 tickets) takes 2–4 weeks: 3–4 days for planning and mapping, 3–5 days for extraction, 3–5 days for transformation and test loading, 2–3 days for production loading and delta sync, and 2–3 days for validation and cutover. LiveAgent's 180 requests/minute API rate limit is the primary bottleneck for large datasets.
What data cannot be migrated programmatically from HappyFox to LiveAgent?
Smart Rules, SLA Policies, Canned Actions, satisfaction survey configurations, and asset management data cannot be migrated programmatically. Smart Rules must be rebuilt as LiveAgent Rules, Canned Actions as Predefined Answers, and SLA Policies as SLA Levels — all manually.
What is the hardest data-model mismatch in this migration?
Organization and category mapping. A HappyFox Category bundles email forwarding, SLA rules, visibility, and assignment logic into one object — LiveAgent Departments are simpler routing containers, so you must split that logic across Departments, SLA Levels, and Rules. HappyFox Contact Groups can have overlapping members, but LiveAgent allows only one company per contact.