Hi, I need help with my billing.
", "category": 3, "email": "customer@example.com", "name": "Jane Doe", "priority": 2, "assignee": 12, "t-cf-1": "fc-conv-uuid-abc12345", "tags": ["migrated", "chat"] }, { "subject": "Chat conversation def67890", "text": "How do I reset my password?
", "category": 3, "email": "john@example.com", "name": "John Smith", "priority": 1, "t-cf-1": "fc-conv-uuid-def67890", "tags": ["migrated", "chat"] } ] ``` **Notes on the bulk payload:** - Maximum 100 ticket objects per request - Custom field keys use the format `t-cf-{id}` where `{id}` is the custom field's integer ID from `GET /api/1.1/json/ticket_custom_fields/` - The response is an array of created ticket objects, each containing the assigned `id` (ticket number) - If any ticket in the batch fails validation, HappyFox may reject the entire batch — validate payloads individually before batching - Attachments cannot be included in bulk ticket creation; they must be uploaded separately via multipart/form-data POSTs after ticket creation ## Step-by-Step Migration Process ### Step 1: Extract Data from Freshchat ```python import requests import json import time import os FRESHCHAT_BASE = "https://yourcompany.freshchat.com/v2" HEADERS = { "Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json" } CHECKPOINT_FILE = "extraction_checkpoint.json" def load_checkpoint(): if os.path.exists(CHECKPOINT_FILE): with open(CHECKPOINT_FILE) as f: return json.load(f) return {"conversations_page": 1, "completed_conversations": []} def save_checkpoint(state): with open(CHECKPOINT_FILE, "w") as f: json.dump(state, f) def dynamic_backoff(response): """Back off based on X-RateLimit-Remaining header.""" remaining = int(response.headers.get("X-RateLimit-Remaining", 100)) if remaining < 10: time.sleep(5) elif remaining < 30: time.sleep(1) else: time.sleep(0.3) def extract_conversations(): checkpoint = load_checkpoint() conversations = [] page = checkpoint["conversations_page"] while True: resp = requests.get( f"{FRESHCHAT_BASE}/conversations", headers=HEADERS, params={"page": page, "items_per_page": 50} ) if resp.status_code == 429: retry_after = int(resp.headers.get("Retry-After", 60)) time.sleep(retry_after) continue if resp.status_code == 401: # Token expired — refresh and retry HEADERS["Authorization"] = f"Bearer {refresh_token()}" continue resp.raise_for_status() data = resp.json() convos = data.get("conversations", []) if not convos: break conversations.extend(convos) page += 1 save_checkpoint({"conversations_page": page, "completed_conversations": checkpoint["completed_conversations"]}) dynamic_backoff(resp) return conversations def refresh_token(): """ Freshchat API keys don't expire, but if using OAuth tokens via Freshworks Marketplace, refresh here. Returns the new token string. """ # Implementation depends on your auth method raise NotImplementedError("Implement OAuth token refresh for your setup") def extract_messages(conversation_id): messages = [] page = 1 while True: resp = requests.get( f"{FRESHCHAT_BASE}/conversations/{conversation_id}/messages", headers=HEADERS, params={"page": page, "items_per_page": 50} ) if resp.status_code == 429: retry_after = int(resp.headers.get("Retry-After", 60)) time.sleep(retry_after) continue resp.raise_for_status() data = resp.json() msgs = data.get("messages", []) if not msgs: break messages.extend(msgs) page += 1 dynamic_backoff(resp) # Sort chronologically — Freshchat may return newest-first messages.sort(key=lambda m: m["created_time"]) return messages def download_attachment(url, dest_dir="attachments"): """Download attachment immediately — Freshchat signed URLs may expire.""" os.makedirs(dest_dir, exist_ok=True) resp = requests.get(url, stream=True) filename = url.split("/")[-1].split("?")[0] # strip query params filepath = os.path.join(dest_dir, filename) with open(filepath, "wb") as f: for chunk in resp.iter_content(chunk_size=8192): f.write(chunk) return filepath ``` ### Step 2: Transform Data The transformation layer does the heavy lifting: 1. **Sort messages** by `created_time` ascending within each conversation 2. **Classify each message** by `actor_type`: user messages become contact replies, agent messages become staff updates, system/bot messages become private notes or are excluded 3. **Convert `message_parts`** to HTML: text parts stay as-is, image parts become `{text}
") elif part_type == "image": url = content.get("url", "") html_parts.append(f'{text} {opts_str}
") elif part_type == "carousel": # Flatten carousel cards to text descriptions cards = content.get("cards", []) for card in cards: title = card.get("title", "") desc = card.get("description", "") html_parts.append(f"{title}: {desc}
") else: # Unknown part type — preserve as text html_parts.append(f"[{part_type}: {json.dumps(content)}]
") return "\n".join(html_parts) if html_parts else "(empty message)
" # Status mapping: Freshchat status string → HappyFox status integer ID # Populate HF status IDs from GET /api/1.1/json/statuses/ STATUS_MAP = { "new": 1, # Map to your HappyFox "New" status ID "assigned": 2, # Map to your HappyFox "In Progress" status ID "resolved": 3, # Map to your HappyFox "Resolved" status ID "reopened": 2, # Map reopened to "In Progress" } def transform_to_ticket(conversation, messages, field_map, category_map, staff_map): # First user message becomes ticket description first_msg = next((m for m in messages if m["actor_type"] == "user"), None) if first_msg: description = flatten_message_parts(first_msg["message_parts"]) else: # Proactive/bot-initiated conversation — use first agent message first_msg = messages[0] if messages else None description = flatten_message_parts(first_msg["message_parts"]) if first_msg else "(no initial message)" conv_id = conversation["conversation_id"] user_email = conversation.get("user", {}).get("email") if not user_email: user_email = f"anonymous-{conv_id[:8]}@migration.placeholder" ticket_payload = { "subject": f"Chat conversation {conv_id[:8]}", "text": description, "category": category_map.get(conversation.get("group_id"), DEFAULT_CATEGORY_ID), "email": user_email, "name": f"{conversation.get('user', {}).get('first_name', '')} {conversation.get('user', {}).get('last_name', '')}".strip() or "Unknown", "priority": 2, # default to medium "status": STATUS_MAP.get(conversation.get("status", "new"), 1), "t-cf-1": conv_id, # Store Freshchat ID in custom field (use your actual field ID) "tags": ["migrated", "freshchat"] } # Map labels to tags labels = conversation.get("labels", []) if labels: ticket_payload["tags"].extend(labels) if conversation.get("assigned_agent_id"): staff_id = staff_map.get(conversation["assigned_agent_id"]) if staff_id: ticket_payload["assignee"] = staff_id # Map custom conversation properties for prop_key, prop_val in conversation.get("conversation_properties", {}).items(): hf_field_key = field_map.get(prop_key) if hf_field_key: ticket_payload[hf_field_key] = prop_val # Remaining messages become updates updates = [] for msg in messages: if msg == first_msg: continue actor = msg.get("actor_type", "user") if actor == "agent": update_type = "staff_update" elif actor in ("system", "bot"): update_type = "private_note" # or skip: continue else: update_type = "user_reply" updates.append({ "type": update_type, "body": flatten_message_parts(msg["message_parts"]), "timestamp": msg["created_time"], "staff_id": staff_map.get(msg.get("actor_id")) if actor == "agent" else None, "attachments": [ p for p in msg.get("message_parts", []) if p.get("type") in ("image", "file") ] }) return ticket_payload, updates ``` ### Step 3: Load into HappyFox ```python import requests from requests.auth import HTTPBasicAuth HF_BASE = "https://yourcompany.happyfox.com/api/1.1/json" HF_AUTH = HTTPBasicAuth("YOUR_API_KEY", "YOUR_AUTH_CODE") # Track POST calls for rate limiting post_count = 0 post_window_start = time.time() def throttle_post(): """Enforce <200 POST/min to stay safely under 300/min limit.""" global post_count, post_window_start post_count += 1 elapsed = time.time() - post_window_start if elapsed < 60 and post_count >= 200: sleep_time = 60 - elapsed + 1 time.sleep(sleep_time) post_count = 0 post_window_start = time.time() elif elapsed >= 60: post_count = 1 post_window_start = time.time() def create_tickets_bulk(ticket_payloads): """Create up to 100 tickets per request. Payload is a JSON array at root level.""" batch_size = 100 results = [] for i in range(0, len(ticket_payloads), batch_size): batch = ticket_payloads[i:i + batch_size] throttle_post() resp = requests.post( f"{HF_BASE}/tickets/", auth=HF_AUTH, json=batch # JSON array at root level, not wrapped in an object ) if resp.status_code == 429: print("Rate limited — waiting 10 minutes") time.sleep(610) # 10-minute lockout + buffer throttle_post() resp = requests.post(f"{HF_BASE}/tickets/", auth=HF_AUTH, json=batch) if resp.status_code == 400: # Log validation errors and continue with remaining batches print(f"Validation error on batch {i//batch_size}: {resp.json()}") # Optionally: retry individual tickets to find the bad one for ticket in batch: throttle_post() single_resp = requests.post(f"{HF_BASE}/tickets/", auth=HF_AUTH, json=ticket) if single_resp.status_code == 201: results.append(single_resp.json()) else: print(f"Failed ticket: {ticket.get('subject')} — {single_resp.json()}") continue resp.raise_for_status() results.extend(resp.json()) # Response is an array of created ticket objects return results def append_update(ticket_number, message_body, staff_id=None, is_staff=True): endpoint = "staff_update" if is_staff else "user_reply" payload = {"text": message_body} if is_staff and staff_id: payload["staff"] = staff_id throttle_post() resp = requests.post( f"{HF_BASE}/ticket/{ticket_number}/{endpoint}/", auth=HF_AUTH, json=payload ) if resp.status_code == 429: time.sleep(610) throttle_post() resp = requests.post( f"{HF_BASE}/ticket/{ticket_number}/{endpoint}/", auth=HF_AUTH, json=payload ) return resp def upload_attachment(ticket_number, filepath, filename): """Upload attachment via multipart/form-data — JSON payloads do not support attachments.""" throttle_post() with open(filepath, "rb") as f: resp = requests.post( f"{HF_BASE}/ticket/{ticket_number}/", auth=HF_AUTH, files={"attachments": (filename, f)}, data={"text": f"Attachment: {filename}", "staff": 1} # staff ID required ) if resp.status_code == 429: time.sleep(610) with open(filepath, "rb") as f: resp = requests.post( f"{HF_BASE}/ticket/{ticket_number}/", auth=HF_AUTH, files={"attachments": (filename, f)}, data={"text": f"Attachment: {filename}", "staff": 1} ) return resp ``` ### Step 4: Rebuild Relationships After tickets are created: - Store the Freshchat `conversation_id` → HappyFox `ticket_id` mapping in a crosswalk database (SQLite or PostgreSQL) for traceability and reruns. - Verify contact-to-ticket associations by querying each ticket and checking the user field. - If contacts were created during ticket creation (HappyFox auto-creates contacts by email), merge duplicates. - Apply tags by updating tickets post-creation if they were not included in the initial payload. ### Step 5: Validate Run validation queries against both systems: - Total conversation count in Freshchat vs. total ticket count in HappyFox (minus documented exclusions) - Message count per conversation vs. update count per ticket - Contact count comparison (expect fewer in HappyFox due to email-based deduplication) - Spot-check 5–10% of tickets for content accuracy, threading order, and attachment accessibility ## Edge Cases and Challenges ### Duplicate Contacts Freshchat users may exist with the same email but different UUIDs (e.g., across channels). Freshchat also creates anonymous users based on browser sessions. HappyFox deduplicates contacts by email — if you create tickets referencing the same email, HappyFox associates them to the same contact automatically. This is usually the desired behavior, but verify that contact custom fields from different Freshchat user records do not overwrite each other. Deduplicate by email address before loading into HappyFox. For anonymous Freshchat users (no email), assign a deterministic placeholder email like `anonymous-{user_uuid_first8}@migration.placeholder` to ensure traceability without polluting your real contact data. ### Bot Conversations Freshchat bot interactions (Freddy AI, custom bots) generate conversations with `actor_type: system` or `actor_type: bot` messages. Decide upfront: do these become tickets, or are they excluded? Most teams exclude bot-only conversations and only migrate conversations where a human agent was involved. Filter criterion: if every message in a conversation has `actor_type` in `("system", "bot")`, exclude it. If at least one message has `actor_type == "agent"`, include it. ### Conversations with No User Message Some Freshchat conversations are initiated by proactive agent messages or bot triggers. These have no initial user message. HappyFox requires an `email` and `text` field on ticket creation. Use the agent's outbound message as the ticket description and assign a placeholder contact email. ### Attachments Freshchat message attachments are referenced as URLs in the `message_parts` array. These URLs are signed and may expire within minutes to hours. You cannot simply pass the URL to HappyFox — download all files to your staging server during extraction, then re-upload to HappyFox via multipart/form-data. HappyFox's ticket creation with attachments only works via HTTP POST with `multipart/form-data` payloads, not JSON. Note that HappyFox attachment URLs returned in ticket GET responses also expire in approximately 5 minutes. ([support.happyfox.com](https://support.happyfox.com/kb/article/1039-tickets-endpoint/?section_id=131)) ### CSAT Responses Freshchat collects CSAT at the conversation level. HappyFox has its own satisfaction survey system, but there is no API to import historical satisfaction ratings. Preserve CSAT data as a private note on the ticket (e.g., "Original CSAT: 4/5, Feedback: 'Quick and helpful'") or as a custom field value for reporting. ### Multi-Channel Conversations A single Freshchat user may have conversations across web chat, WhatsApp, and Messenger. Each conversation migrates as a separate ticket in HappyFox. Tag them with the source channel (e.g., `channel:whatsapp`, `channel:web`) for reporting continuity. ### Timestamps HappyFox's standard ticket creation API sets `created_at` to the time of the API call, not a custom timestamp. There is no documented public API parameter to backdate ticket creation timestamps. Store the original Freshchat timestamp in a custom field (`cf_original_date`), and work with HappyFox support to discuss backdating options if historical date accuracy matters for SLA reporting or compliance. > [!WARNING] > **Timestamp preservation is the most commonly overlooked issue in messaging-to-ticket migrations.** If historical date accuracy matters for SLA reporting or compliance, confirm HappyFox's backdating capabilities with their support team before committing to the migration. Some teams have reported that HappyFox support can perform server-side timestamp adjustments as a one-time accommodation — confirm this for your account. ## Limitations and Constraints ### HappyFox Constraints - **No true custom objects.** HappyFox has tickets, contacts, contact groups, and assets. There is no equivalent to complex relational data beyond custom fields. - **Contact pagination limited to 50 per page.** Extracting large contact lists from HappyFox (for validation) is slower than expected. - **No bulk update endpoint for ticket updates.** Each staff update or contact reply is a separate POST call. For a conversation with 20 messages, that is 19 individual API calls after the initial ticket creation. This is the primary driver of load-phase duration. - **10-minute API lockout on rate limit breach.** This is the most punishing rate limit behavior of any major help desk API. - **Attachment URLs returned in ticket payloads expire in about 5 minutes.** ([support.happyfox.com](https://support.happyfox.com/kb/article/1039-tickets-endpoint/?section_id=131)) - **No public API for KB article creation.** KB migration must be done via UI, CSV import (check with support), or browser automation. ### Freshchat Constraints - **Rate limits are not explicitly published.** You must monitor response headers (`X-RateLimit-Remaining`) and implement dynamic throttling. Empirically, 2–3 requests/second is sustainable on Growth and Pro plans. ([developers.freshchat.com](https://developers.freshchat.com/api/)) - **Messages API max page size is 50.** For conversations with hundreds of messages, expect many paginated calls per conversation. - **Chat-Transcript CSV exports are limited to 24-hour windows**, and raw report extraction cannot start more than **15 months** back. ([developers.freshchat.com](https://developers.freshchat.com/api/)) - **Signed attachment URLs may expire.** Download attachments immediately during extraction — do not defer to the load phase. - **OAuth tokens can expire during long-running extractions.** Build in 401 handling and automatic token refresh. (Note: static API keys generated in the admin console do not expire, but OAuth tokens from Freshworks Marketplace integrations do.) ## Validation and Testing ### Record Count Comparison | Metric | Freshchat Source | HappyFox Target | Expected Difference | Status | |---|---|---|---|---| | Total conversations | Count from API | Ticket count | Subtract excluded bot conversations | Must match | | Total contacts/users | Count from API | Contact count | Fewer in HappyFox (email dedup) | Document delta | | Messages per conversation | Sum per conversation | Updates per ticket | Subtract excluded bot messages | Must match | | Attachments | Count from extraction | Count in HappyFox | Must match | Must match | ### Field-Level Validation For a random sample of 5–10% of tickets: - Verify subject/description matches first message content - Verify agent assignment matches original conversation assignee - Verify category matches original group - Verify custom field values are correctly mapped - Verify chronological order of updates matches message order - Verify attachment count and file names match - Verify `cf_freshchat_id` custom field contains the correct conversation UUID ### UAT Process 1. Run a test migration with 100–200 conversations (select a representative sample including multi-message, attachment-heavy, bot-involved, and multi-channel conversations) 2. Have 2–3 agents review migrated tickets for accuracy and readability 3. Verify that searching for a contact shows all associated tickets 4. Test that custom field filters work on migrated data 5. Confirm attachments are downloadable 6. Verify that tags and categories are correctly applied 7. Check that the `cf_original_date` custom field displays correctly in views and reports ### Rollback Planning Before running the production migration: - Document the current state of HappyFox (existing ticket count, contact count) - HappyFox does not have a point-in-time restore. If you need to roll back, you will need to bulk-delete migrated tickets via API (`DELETE /api/1.1/json/ticket/{ticket_number}/`) - Tag all migrated tickets with a `migration-batch-{date}` tag for easy identification and potential cleanup - Use the ID crosswalk database to identify and delete all migrated records if validation fails ## Post-Migration Tasks ### Rebuild in HappyFox These cannot be migrated programmatically: - **Smart Rules** (HappyFox automations) — recreate trigger conditions and actions - **SLA policies** — configure response and resolution time targets per category - **Canned Actions** — rebuild saved response templates - **Satisfaction surveys** — configure HappyFox's built-in survey settings - **Agent roles and permissions** — set up staff roles and category access - **Email parsing rules** — configure incoming email routing to categories ### User Training - Freshchat agents are accustomed to a messaging interface. HappyFox uses a traditional ticket queue. Plan for 1–2 training sessions covering the workflow differences. - Demonstrate how to search for migrated conversations (by original conversation ID stored in the `cf_freshchat_id` custom field). - Train on HappyFox's category-based routing vs. Freshchat's group-based assignment. - Help agents understand SLA timers, category routing, and contact group visibility. ### Monitor for 30 Days - Watch for duplicate contacts created by incoming tickets from existing customers - Verify that custom field values display correctly in reports - Check that SLA clocks are calculating correctly on migrated tickets (timestamps stored in `cf_original_date` may differ from HappyFox's `created_at`) - Set up HappyFox webhooks to monitor for data inconsistencies or failed email parsing - Track agent feedback on migrated ticket readability ## Best Practices 1. **Back up everything first.** Extract all Freshchat data to a local staging store (JSON files or SQLite database) before writing anything to HappyFox. 2. **Run at least two test migrations.** The first will surface mapping errors. The second will validate your fixes. 3. **Throttle conservatively.** Target 60–70% of HappyFox's rate limit ceiling (200 POST/min). The 10-minute lockout is not worth the time saved by pushing to 280/min. 4. **Use idempotency keys.** Store the Freshchat `conversation_id` in a HappyFox custom field. If a migration run fails midway, query HappyFox for existing tickets with that custom field value before creating duplicates. 5. **Filter bot conversations early.** Do not extract, transform, and load data you will just delete later. Apply the bot filter at extraction time. 6. **Validate at every stage.** Check data at extraction (row counts), transformation (payload schema validation), and load (response status codes and record counts) — not just at the end. 7. **Migrate during off-hours.** Both APIs perform better under lighter load. Schedule production runs for nights or weekends in your primary time zone. 8. **Keep Freshchat active until validation is complete.** Do not cancel your Freshchat account until you have confirmed all data is accurately represented in HappyFox. Maintain at least one billing cycle of overlap. 9. **Use configuration files for mappings.** Do not hard-code field mappings if you have more than 10. Define them in a JSON or YAML config file that can be version-controlled and audited. 10. **Treat CRM data as a separate stream.** If your Freshchat data includes Freshsales Suite objects, migrate them separately into HappyFox custom fields or keep them in the CRM. 11. **Download attachments during extraction.** Do not defer attachment downloads to the load phase — Freshchat signed URLs expire and will be inaccessible later. 12. **Persist checkpoints.** Save extraction and load progress (last page, last conversation ID, last created ticket ID) so that restarts resume from where they left off rather than restarting from scratch. ## Sample Data Mapping Table | # | Freshchat Source | API Path | HappyFox Target | Transform | |---|---|---|---|---| | 1 | Conversation ID | `/v2/conversations` → `conversation_id` | Custom field `t-cf-{id}` | String copy | | 2 | Status | `status` | Status ID | Enum → integer ID lookup via `GET /statuses/` | | 3 | Assigned agent | `assigned_agent_id` | Assignee | UUID → staff ID (email match) | | 4 | User email | `users [].email` | Contact email | Direct | | 5 | User name | `users [].first_name` + `last_name` | Contact name | Concatenate | | 6 | Group | `group_id` | Category | UUID → category ID lookup | | 7 | First message | `messages [0].message_parts` | Ticket description | Flatten parts to HTML | | 8 | Subsequent messages | `messages [1..n].message_parts` | Updates | Per-message POST (staff_update / user_reply) | | 9 | Label | `labels []` | Tag | Name match | | 10 | Attachment URL | `message_parts [].url` | Attachment file | Download + multipart upload | | 11 | CSAT score | CSAT response | Private note or custom field | Formatted text | | 12 | Created time | `created_time` | Custom field `t-cf-{id}` | ISO 8601 string | | 13 | Channel source | Conversation metadata | Tag (`channel:web`, `channel:whatsapp`) | String prefix + channel name | ## Automation Script Outline High-level structure for a Python-based migration script: ```python # migration.py — Freshchat to HappyFox migration import json import os class FreshchatExtractor: """Handles paginated extraction from Freshchat v2 API.""" def __init__(self, base_url, api_key): ... def get_agents(self) -> list: ... # GET /v2/agents def get_users(self) -> list: ... # GET /v2/users (paginated, 100/page) def get_conversations(self) -> list: ... # GET /v2/conversations (paginated, 50/page) def get_messages(self, conv_id) -> list: ... # GET /v2/conversations/{id}/messages (50/page) def download_attachment(self, url, dest_dir) -> str: ... # Returns local filepath class Transformer: """Maps Freshchat data to HappyFox payloads.""" def __init__(self, field_map, category_map, staff_map, status_map): ... def conversation_to_ticket(self, conv, msgs) -> tuple: ... # (ticket_payload, updates) def flatten_message_parts(self, parts) -> str: ... # message_parts → HTML def map_status(self, fc_status) -> int: ... # status → HF status ID def user_to_contact(self, user) -> dict: ... class HappyFoxLoader: """Handles writes to HappyFox v1.1 API with rate limiting.""" def __init__(self, base_url, api_key, auth_code): ... def create_contacts_bulk(self, contacts) -> list: ... def create_tickets_bulk(self, tickets, batch_size=100) -> list: ... def append_staff_update(self, ticket_num, staff_id, body) -> dict: ... def append_user_reply(self, ticket_num, body) -> dict: ... def upload_attachment(self, ticket_num, filepath, filename) -> dict: ... def _throttle(self): ... # Enforce <200 POST/min with counter and timer class Validator: """Post-migration checks.""" def compare_counts(self, fc_data, hf_data) -> dict: ... def sample_check(self, sample_size_pct=10) -> list: ... def verify_threading(self, ticket_num, expected_messages) -> bool: ... def verify_attachments(self, ticket_num, expected_count) -> bool: ... class CrosswalkDB: """SQLite-backed ID mapping for idempotency and rollback.""" def __init__(self, db_path="crosswalk.db"): ... def record_mapping(self, fc_conv_id, hf_ticket_id): ... def get_hf_ticket_id(self, fc_conv_id) -> int | None: ... def get_all_hf_ticket_ids(self) -> list: ... if __name__ == "__main__": # Load configuration with open("migration_config.json") as f: config = json.load(f) # 1. Extract extractor = FreshchatExtractor(config["freshchat_base"], config["freshchat_key"]) agents = extractor.get_agents() users = extractor.get_users() conversations = extractor.get_conversations() # 2. Build lookup maps from HappyFox # Requires pre-created staff, categories, custom fields in HappyFox staff_map = build_staff_map(agents, hf_staff) # FC agent UUID → HF staff int ID category_map = build_category_map(fc_groups, hf_categories) # FC group UUID → HF cat int ID field_map = build_field_map(fc_properties, hf_custom_fields) # FC prop name → HF "t-cf-{id}" status_map = build_status_map() # FC status string → HF status int ID # 3. Transform and load contacts transformer = Transformer(field_map, category_map, staff_map, status_map) loader = HappyFoxLoader(config["hf_base"], config["hf_key"], config["hf_auth"]) crosswalk = CrosswalkDB() contacts = [transformer.user_to_contact(u) for u in users] loader.create_contacts_bulk(contacts) # 4. Transform and load tickets + updates for conv in conversations: # Check idempotency — skip if already migrated existing = crosswalk.get_hf_ticket_id(conv["conversation_id"]) if existing: continue msgs = extractor.get_messages(conv["conversation_id"]) ticket, updates = transformer.conversation_to_ticket(conv, msgs) result = loader.create_tickets_bulk([ticket]) ticket_num = result[0]["id"] crosswalk.record_mapping(conv["conversation_id"], ticket_num) for update in updates: if update["type"] == "staff_update": loader.append_staff_update(ticket_num, update.get("staff_id"), update["body"]) elif update["type"] == "user_reply": loader.append_user_reply(ticket_num, update["body"]) # Handle attachments for att in update.get("attachments", []): filepath = extractor.download_attachment(att["content"]["url"]) loader.upload_attachment(ticket_num, filepath, att["content"].get("name", "file")) # 5. Validate validator = Validator(extractor, loader) report = validator.compare_counts(fc_data=conversations, hf_data=loader) sample_results = validator.sample_check(sample_size_pct=10) print(json.dumps(report, indent=2)) print(f"Sample check: {sum(1 for r in sample_results if r['pass'])}/{len(sample_results)} passed") ``` **Configuration file example (`migration_config.json`):** ```json { "freshchat_base": "https://yourcompany.freshchat.com/v2", "freshchat_key": "YOUR_FRESHCHAT_API_KEY", "hf_base": "https://yourcompany.happyfox.com/api/1.1/json", "hf_key": "YOUR_HF_API_KEY", "hf_auth": "YOUR_HF_AUTH_CODE", "default_category_id": 3, "default_priority": 2, "exclude_bot_only": true, "status_map": { "new": 1, "assigned": 2, "resolved": 3, "reopened": 2 } } ``` Persist checkpoints for users, conversations, last message page, and HappyFox IDs so restarts are safe and reruns are idempotent. ## What to Do Next If your team has the engineering bandwidth and a dataset under 10,000 conversations, the API-based approach outlined here is achievable in 2–4 weeks of part-time engineering effort. For larger datasets, complex custom fields, or zero-downtime requirements, the engineering cost of building, testing, and debugging a custom migration script often exceeds the cost of working with a specialist. Use the throughput calculation above to estimate your specific timeline: count your conversations, multiply by average messages per conversation, add attachment counts, divide by your target POST rate, and add a 50% buffer. That gives you the load-phase runtime. Double it for the full migration including extraction, transformation, and validation. For further reading on moving data into and out of HappyFox, review our guides on [How to Migrate from Happy ## Frequently asked questions ### Can I migrate Freshchat conversations to HappyFox using CSV export? Not effectively. Freshchat's CSV export flattens entire chat transcripts into a single text field, losing message-level timestamps, sender attribution, and threading. The Chat-Transcript report is limited to 24-hour windows with a 15-month lookback cap. HappyFox has no native CSV import for tickets. For anything beyond small archival needs, use the API-based approach. ### What are HappyFox's API rate limits for migration? HappyFox allows 500 GET requests per minute and 300 POST requests per minute. Exceeding these triggers a 429 error with a 10-minute lockout — all API access is blocked for 10 minutes. Target 200 POST/min maximum during migration to avoid hitting this limit. ### How long does a Freshchat to HappyFox migration take? For mid-size datasets (10,000–50,000 conversations), plan for 5–15 business days. The primary bottleneck is the per-message API calls required to recreate conversation threading in HappyFox, combined with HappyFox's rate limits. Small datasets under 5,000 conversations can complete in 3–5 days. ### Can I preserve original timestamps when migrating to HappyFox? HappyFox's standard ticket creation API sets the created_at field to the time of the API call. There is no documented public API parameter to backdate ticket creation. Store the original Freshchat timestamp in a custom field, and contact HappyFox support to discuss backdating options. ### What Freshchat data cannot be migrated to HappyFox? Bot conversation flows (interactive elements like carousels and quick replies), CSAT survey results (no import API), smart assignments, automation rules, and real-time analytics data cannot be migrated programmatically. These must be rebuilt manually or preserved as notes. CRM-side objects like Leads and Opportunities from Freshsales Suite are also not native to either platform's chat/ticket model.