Front to Freshchat Migration: A Technical Guide

Migrating from Front to Freshchat is a fundamental architecture shift. You are moving from an email-first, shared-inbox paradigm into a session-based messaging platform. There is no native import path from Front into Freshchat, no vendor-provided migration wizard, and no official connector between the two. Every record—contacts, conversations, messages, attachments, tags—requires extraction from Front's API, transformation to match Freshchat's data model, and loading through Freshchat's v2 REST API.

This is not a CSV shuffle. It is a schema translation project.

This guide covers the full technical path: data model differences, migration approaches, API constraints on both sides, object mapping, edge cases, compliance considerations, and validation. If you're a helpdesk admin, IT lead, or CTO evaluating this move, this is the implementation reference.

Why Teams Move from Front to Freshchat

Front is a collaborative inbox platform that unifies email, SMS, chat, and social channels into shared inboxes with rules-based routing, internal comments, and CRM-like contact/account management. It is built for teams that treat email as a primary support channel.

Freshchat is Freshworks' messaging and live chat platform designed for real-time customer engagement across web chat, WhatsApp, Facebook Messenger, Instagram, and email. Freshchat is Freshworks' modern messaging and customer engagement platform that enables sales and support teams to converse with customers across web, mobile, WhatsApp, Facebook Messenger, Instagram, Apple Business Chat, and email. It is increasingly positioned as part of the broader Freshdesk Omni suite.

Common reasons teams migrate:

• Freshworks ecosystem consolidation. Teams already using Freshdesk, Freshsales, or Freshservice want a unified messaging layer rather than managing Front as a standalone tool.
• Chat-first support model. Organizations shifting from email-heavy workflows to real-time messaging find Freshchat's bot builder, AI Agent Studio, and widget-based intake more aligned.
• Cost reduction. Front's per-seat pricing (Starter at $19/seat/month, Growth at $59, Scale at $99, Premier at $229) scales fast for growing teams. Freshchat's free tier (up to 10 agents) and Growth plan ($19/agent/month) attract cost-sensitive operations.
• Marketing automation and proactive engagement. Freshchat includes Contacts and Accounts, FAQs, AI Agent Studio, Campaigns for website/SMS/WhatsApp, and Support Analytics.
• Session-based routing. Shifting from inbox-based triage to skill-based, real-time chat routing with IntelliAssign.

Core Data Model Differences

This is where most migration plans break down. Front and Freshchat model customer support data differently at every level.

In Front, you can add custom fields for contacts, accounts, teammates, inboxes, conversations, and application objects—up to 50 custom fields per category. Freshchat's contact properties are more constrained and vary by plan tier:

Three structural differences matter most:

1. Front conversations are email threads. They contain messages (emails, SMS, chat) and internal comments in parallel. Freshchat conversations are linear chat sessions. Front threads must be flattened into Freshchat's continuous message array.

2. Front has first-class Accounts (companies). Standalone Freshchat does not have an Account or Company object. If your team relies on account-based routing or reporting in Front, you need Freshdesk Omni, which includes company-level contact management. Without it, the account hierarchy is lost entirely.

3. Front allows multi-handle contacts; Freshchat deduplicates on email. A single Front contact can have multiple email handles, phone numbers, and social accounts as separate "handles." Freshchat uses email as the primary unique identifier. Contacts with multiple email addresses in Front must be resolved to a single canonical email during transformation.

The most consequential API caveat in Freshchat is the Contact/Agent object split. Automation that conflates the two—for example, querying /v2/contacts to audit team members—will silently return incomplete or irrelevant data.

Migration Approaches

There are five viable paths. Each has different trade-offs for complexity, fidelity, and engineering investment.

1. Native Export + Manual Import (CSV-Based)

How it works: Request a full data export from Front's support team, receive CSV/EML files, then reformat and import contacts into Freshchat via CSV/XLSX.

You will need to contact Front's Support team to export your team's Front account data. You cannot do this on your own in the app. When you request an account data export, Front provides conversations, messages, and discussions in shared inboxes but will not include attachments, comments, conversations, or discussions from individual inboxes or contact data. They will not export message templates and tags.

When to use: Small teams with fewer than 1,000 contacts who primarily need contact data moved and are willing to lose conversation history.

Pros: No engineering required. Free.

Cons: Front's export excludes attachments, individual inbox data, tags, and templates. The message body extract is limited to 200 characters. Freshchat has no CSV conversation import—contacts only. You lose all conversation threading and history.

Complexity: Low | Scalability: Small datasets only

2. API-Based Migration (Front API → Freshchat API)

How it works: Build a custom script that reads data from Front's Core API (conversations, messages, contacts, tags, attachments) and writes it into Freshchat's v2 REST API.

Front's Core API allows you to read, create, update, and delete a wide range of data across Front's various entities, from Contacts to Comments to Tags. If your use case involves programmatic syncing, export, or modification of Front data, the Core API is likely what you're looking for.

The Freshchat REST API provides programmatic access to agents, users, conversations, messages, channels, bots, and reports for building custom integrations and workflow automations.

When to use: Mid-size to large teams with engineering capacity who need to preserve conversation history and message-level detail.

Pros: Highest fidelity. Full control over transformation logic. Can preserve threading, assignments, and metadata.

Cons: Rate limits on both sides constrain throughput. Front's API rate limit starts at 50 requests per minute and varies depending on your plan. Rate limits are enforced on a per-company basis rather than a per-token basis. Freshchat's API rate limits are similarly restrictive—Freshchat API rate limits vary based on your plan, and the app's request rate limit is typically capped at 50 requests per minute. Building retry logic, pagination handling, and error recovery adds significant development time.

Observed throughput in practice: With both sides at 50 req/min, a typical migration script achieves approximately 40–45 effective requests per minute per side after accounting for retries and pagination overhead. For a dataset of 50,000 conversations averaging 8 messages each, expect roughly 4–6 days of continuous API execution for the conversation and message extraction/loading phases alone.

Complexity: High | Scalability: Enterprise-grade with proper batching

3. Third-Party Migration Tools

Services like Help Desk Migration offer wizard-based migration into Freshchat. To start your Freshchat data import, connect your Source and Target (Freshchat) in the Migration Wizard. To link Freshchat, you'll need the URL of your account and API token.

When to use: Teams without engineering resources who want a guided migration with field mapping.

Pros: Pre-built connectors, field mapping UI, test migration capability.

Cons: Black-box execution. Often fails on complex custom fields, large attachments (>25MB), or nested comments. Per-record pricing (typically $2–$10 per 100 records depending on volume tier) adds up at scale. Limited control over transformation logic means edge cases like multi-handle contacts or HTML email bodies may not be handled correctly.

Complexity: Low–Medium | Scalability: Medium (depends on tool limits)

4. Custom ETL Pipeline

How it works: Build a structured extract-transform-load pipeline. Extract from Front API into a staging database, transform and validate, then load into Freshchat API.

Front provides a sample export application that demonstrates how to export conversations and messages from Front. This is an ETL script, with Front serving as the extract point rather than the load point.

When to use: Large datasets (100K+ conversations), teams that need full audit trails, or migrations requiring intermediate validation and data merging with external CRM data.

Pros: Full control, replayable, testable. Can stage data for validation before loading. Handles rate limits gracefully with queue-based processing. Provides an auditable trail of all transformations. Enables dry runs against staging data without touching the target system.

Cons: Highest engineering investment. Typically requires 2–4 weeks of development and testing for a team of 2 engineers familiar with both APIs. Requires infrastructure (staging database, job queue, monitoring).

Complexity: High | Scalability: Enterprise

5. Middleware Platforms (Zapier, Make)

The Freshchat modules on Make allow you to monitor, create, update, send, retrieve, list, and delete conversations, agents, reports, users, channels, and groups in your Freshchat account.

When to use: Ongoing sync of new records or very small one-time transfers (fewer than 500 records). Strictly for forward-syncing data while running both systems in parallel during a transition period.

Pros: No-code, fast to set up (typically under 2 hours for basic contact sync).

Cons: Not designed for bulk historical migration. Zapier's task limits (Free: 100 tasks/month, Starter: 750, Professional: 2,000) and Make's operation caps make large transfers expensive and slow. Front's Zapier integration does not support custom contact fields. No conversation threading support. Will fail if used for historical backfills—API rate limits and task costs skyrocket.

Complexity: Low | Scalability: Small only

Migration Approach Comparison

Recommendation by scenario:

• Small team (<10 agents, <5K conversations), no dev resources: Third-party migration tool or managed service. Use CSV for contacts and archive Front conversations locally as EML files.
• Mid-size team (10–50 agents, 5K–50K conversations), some engineering: API-based migration with a focused script. Budget 2–3 weeks of dev time.
• Enterprise (50+ agents, 50K+ conversations), dedicated dev team: Custom ETL pipeline with staging database. Budget 4–8 weeks including testing and validation.
• Ongoing sync (not one-time): Webhook-driven pipeline using Front's webhook events to push new conversations to Freshchat in near real-time.
• Low engineering bandwidth but complex data: Managed migration service.

When to Use a Managed Migration Service

Building a Front-to-Freshchat migration in-house sounds straightforward until you hit the edge cases. Both platforms have tight rate limits, undocumented API behaviors, and data model gaps that turn a "two-week project" into a quarter-long effort.

Common failure modes in DIY migrations:

• Broken conversation threading. Front's conversation model (multi-message email threads with comments) doesn't map cleanly to Freshchat's chat sessions. Naive imports create orphaned messages or duplicate conversation records.
• Lost attachments. Front's account export excludes attachments entirely. API extraction requires downloading each file individually, respecting rate limits, then re-uploading to Freshchat. A dataset with 10,000 attachments at 50 req/min takes approximately 3.3 hours of pure download time, plus equivalent upload time.
• Custom field data loss. Front allows 50 custom fields per object category. Freshchat's contact properties are more limited on lower-tier plans, and mismatched field types (e.g., Front's enum/dropdown fields vs. Freshchat's text-only properties on Growth plans) require manual mapping or lossy conversion.
• Rate limit walls. At 50 requests/minute on both sides, a 100K-conversation migration takes 4–7 days of continuous API calls—with zero tolerance for unhandled retry failures.
• Hidden engineering cost. The migration script itself is 20% of the work. Error handling, idempotency, progress tracking, validation, and rollback planning are the other 80%.

When NOT to build in-house:

• Your engineering team is focused on core product features and cannot dedicate 2+ engineers for 4–8 weeks.
• You have more than 50,000 historical conversations.
• You rely heavily on custom objects or external CRM links in Front.
• Your support operations cannot tolerate data drift during a multi-week build.
• You need GDPR-compliant data handling with audit trails during transfer.

Why ClonePartner Fits This Migration

ClonePartner has completed 1,500+ data migrations across help desk platforms, including complex Front extractions. What we bring:

• Pre-built Front extraction pipelines that handle pagination, rate limiting, attachment downloads, and comment threading without custom development.
• Freshchat import logic that correctly maps contacts, creates conversations with preserved timestamps, and handles the agent/contact object split.
• Field-level mapping and transformation for custom fields, tags-to-labels conversion, and picklist normalization.
• Validation and reconciliation built into every migration—record counts, field-level sampling, and relationship integrity checks.
• Zero-downtime execution. Your support team keeps working in Front while we load data into Freshchat.

Pre-Migration Planning

Preparation dictates execution. Run this audit before touching any APIs.

Data Audit Checklist

• Contacts: Total count, custom fields in use, handle types (email, phone, social), duplicate email count
• Accounts: Total count, contact-to-account associations, custom fields, duplicate organizations
• Conversations: Total count by inbox, date range, average messages per thread, conversations with >50 messages (potential edge cases)
• Tags: Full tag list, usage frequency, which tags drive automation rules
• Attachments: Total count, total size in GB, file types, max single file size, conversations with attachments
• Comments: Internal comments on conversations (not exported in CSV), count per conversation
• Rules: Active automation rules that reference tags, contacts, or account fields (document each rule's trigger, condition, and action)
• Custom fields: Full list per object type with data types, dropdown values, and which fields contain PII
• Leads & Opportunities: If synced from a CRM into Front, determine how these will map into Freshsales/Freshchat
• Chatbot integrations: Document any Front chatbot or AI integrations that need equivalent configuration in Freshchat's AI Agent Studio
• Data residency: Confirm Front's data region and Freshchat's data hosting region (US, EU, IN, AU) for compliance

If Front is only one part of your operating stack, audit the system of record for each object instead of assuming it all lives in Front. Leads, opportunities, and activities typically live in a connected CRM such as Freshsales, HubSpot, or Salesforce.

Define Migration Scope

Not everything needs to move. Common decisions:

• Time window: Migrate only the last 12–24 months of conversations. Older data can be archived as EML files or stored in a data warehouse for compliance.
• Active vs. archived: Skip conversations archived for 6+ months with no reopening.
• Unused tags: Drop tags with zero or near-zero usage (typically 30–50% of tag lists in mature Front instances).
• Test/spam data: Exclude test conversations, spam-flagged threads, and internal sandbox data.
• Inactive users: Decide whether to archive or migrate. Inactive contacts with no conversations in 12+ months are candidates for exclusion.
• PII-sensitive records: Flag records subject to GDPR, CCPA, or other data protection regulations for special handling during transfer.

Migration Strategy

For most teams, incremental migration is the safest approach:

1. Historical Load: Move all data up to T-minus 7 days. Run validation.
2. Delta Sync: Move the remaining 7 days of data over a weekend. Re-validate.
3. Cutover: Route new traffic to Freshchat on Monday morning. Keep Front in read-only mode.
4. Stabilization: Monitor for 2 weeks. Fix any data gaps discovered by agents.

GDPR and Data Residency Considerations

Migrating between platforms involves cross-system data transfer that may trigger data protection obligations:

• Data Processing Agreement (DPA): Ensure you have DPAs in place with both Front and Freshworks. Both offer standard DPAs on request.
• Data residency: Front stores data in the US (AWS us-east-1). Freshworks offers data centers in US, EU (Frankfurt), India, and Australia. If you're subject to EU data residency requirements, confirm your Freshchat instance is hosted in the EU before migration.
• Right to erasure: If you've processed deletion requests in Front, verify those records aren't re-imported from cached exports. Filter deleted contacts from your staging database before loading.
• Data minimization: Use the migration as an opportunity to purge data you no longer have a lawful basis to retain. Conversations older than your retention policy should be excluded.
• Transit encryption: Both Front and Freshchat APIs use TLS 1.2+. If you're using a staging database, ensure it's encrypted at rest (AES-256) and in transit.
• Audit trail: Log every record extracted, transformed, and loaded with timestamps for compliance documentation.

Data Model and Object Mapping

This is the most important section of your migration plan. Get the mapping wrong and everything downstream breaks.

Object-Level Mapping

Field-Level Mapping: Contacts

Handling Relationships and Pipeline Data

Front's relationship chain: Account → Contact → Conversation → Messages/Comments

Freshchat's relationship chain: User → Conversation → Messages

The account-level grouping is lost in standalone Freshchat. If your team relies on account-based routing or reporting, evaluate whether Freshdesk Omni is a better target. The cost difference is significant: Freshchat Pro is $47/agent/month; Freshdesk Omni Pro is $79/agent/month, but includes Company objects, advanced reporting, and SLA management.

Front handles sales pipelines via custom fields or CRM integrations. Freshchat natively handles chat routing, not pipeline management. To migrate Front pipeline data, map Front's custom fields into Freshsales Leads/Opportunities and link those records to the Freshchat User profile via the Freshworks unified architecture. Pure Freshchat is not a CRM replacement—deals and pipelines live in Freshsales modules.

Handling Tags

Front tags are flexible, hierarchical, and used in rule automation. Freshchat has no direct tag equivalent. Options:

1. Convert to conversation properties (key-value pairs) — Best for tags that carry semantic meaning (e.g., priority:high, category:billing). Requires Pro or Enterprise plan for dropdown-type properties.
2. Append as a text field on the conversation — Store all tags as a semicolon-delimited string in a custom text property (e.g., cf_front_tags: "billing;urgent;vip"). Works on all plans but loses queryability.
3. Use Freshchat labels if available on your plan — Most direct equivalent, but label management is limited compared to Front's tag system.

Tags used in Front rules must be manually recreated as Freshchat automation conditions. Document every tag-to-automation dependency before migration.

CSV Import Gotchas

Two details worth noting: Front custom contact field headers are case-sensitive in CSV exports, and Freshchat multi-select imports expect values separated by semicolons (not commas).

Migration Architecture

Your pipeline must follow a strict Extract-Transform-Load pattern.

Data Flow

Front API (Extract) → Staging DB (Transform) → Freshchat API (Load)
     ↓                      ↓                        ↓
  Contacts              Normalize              Create Users
  Conversations         Map fields              Create Conversations  
  Messages              Clean data              Post Messages
  Attachments           Resolve IDs             Upload Attachments
  Tags                  Validate                Set Properties
  Comments              Deduplicate             Create Private Notes

Front API: Extraction Details

Base URL: https://api2.frontapp.com Auth: Bearer token (API key from Settings → API & Integrations) Format: JSON API Version: Specify via Accept: application/json header (no explicit versioning as of 2024)

Key endpoints for extraction:

• GET /conversations — list and filter by inbox, status, date. Returns id, subject, status, assignee, tags, created_at, _links.
• GET /conversations/{id}/messages — retrieve full message thread (up to 100 per page). Returns id, type, is_inbound, body, text, author, recipients, attachments, created_at.
• GET /conversations/{id}/comments — internal comments. Returns id, body, author, created_at.
• GET /contacts — list all contacts with handles and custom fields.
• GET /accounts — list accounts with domains and custom fields.
• GET /tags — full tag list with IDs and names.
• GET /inboxes — inbox metadata including type and address.

Front uses cursor-based pagination. The _pagination.next URL in the response provides the next page cursor. The q query object supports filtering on conversation endpoints by statuses [], inboxes [], tags [], and date range (before/after as Unix timestamps).

Front's API rate limit starts at 50 requests per minute and varies depending on your plan. Rate limits are enforced on a per-company basis rather than a per-token basis. Rate limit increases beyond the default limits require the Professional plan or higher.

API rate limit add-ons can be purchased to increase limits (300 additional calls per minute per add-on).

Front API error responses to handle:

Freshchat API: Loading Details

Base URL: https://{account_subdomain}.freshchat.com/v2 Auth: Bearer API tokens generated from the Freshchat admin console.

Key endpoints for loading:

• POST /users — create contacts. Returns id, created_time, email, phone.
• POST /conversations — create conversations with initial message. Returns conversation_id, channel_id, status.
• POST /conversations/{id}/messages — append messages to existing conversation.
• GET /channels — list available channels for routing. Returns channel id, name, type.
• GET /agents — list agents for assignment mapping. Returns id, email, first_name, last_name.
• PUT /users/{id} — update contact properties (full replace, not partial—see warning above).

Freshchat API error responses to handle:

Example Freshchat API response (POST /users):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_time": "2024-01-15T10:30:00.000Z",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+14155551234",
  "reference_id": "cnt_abc123",
  "properties": [
    {"name": "plan_type", "value": "enterprise"}
  ]
}

Pagination: Call GET endpoints with items_per_page=100 to retrieve the first page. Check pagination.next_link in the response; if present, follow the link for the next page. Repeat until next_link is absent or total_items count is reached.

Store Bearer tokens for both platforms securely in a vault (AWS Secrets Manager, HashiCorp Vault, or equivalent), not in your scripts or environment variables in plaintext.

Step-by-Step Migration Process

Step 1: Extract Data from Front

Pull all Front data into a local staging database (PostgreSQL recommended for relational integrity; MongoDB if you prefer to cache raw JSON without schema). Do not transform in transit. Cache the raw JSON responses with the original Front ID as the primary key.

import requests
import time
import json
import logging
 
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
 
FRONT_API_KEY = "your_front_api_token"  # Load from vault in production
BASE_URL = "https://api2.frontapp.com"
HEADERS = {
    "Authorization": f"Bearer {FRONT_API_KEY}",
    "Content-Type": "application/json"
}
 
def fetch_paginated(endpoint, params=None):
    """Fetch all pages from a Front API endpoint with rate limiting."""
    results = []
    url = f"{BASE_URL}{endpoint}"
    retry_count = 0
    max_retries = 3
    
    while url:
        response = requests.get(url, headers=HEADERS, params=params)
        
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60000))
            wait_seconds = retry_after / 1000  # Front returns ms
            logger.warning(f"Rate limited. Waiting {wait_seconds}s")
            time.sleep(wait_seconds)
            continue
        
        if response.status_code >= 500:
            retry_count += 1
            if retry_count > max_retries:
                logger.error(f"Max retries exceeded for {url}")
                break
            wait = (2 ** retry_count) + (time.time() % 1)  # Exponential backoff with jitter
            time.sleep(wait)
            continue
        
        response.raise_for_status()
        retry_count = 0
        data = response.json()
        results.extend(data.get("_results", []))
        url = data.get("_pagination", {}).get("next")
        params = None  # Pagination URL includes params
        time.sleep(1.2)  # Stay under 50 req/min
    
    logger.info(f"Extracted {len(results)} records from {endpoint}")
    return results
 
# Extract contacts
contacts = fetch_paginated("/contacts")
 
# Extract conversations with status filtering
conversations = fetch_paginated("/conversations", 
    params={"q[statuses][]": ["assigned", "unassigned", "archived"]})
 
# Extract messages for each conversation
for conv in conversations:
    conv_id = conv["id"]
    conv["_messages"] = fetch_paginated(f"/conversations/{conv_id}/messages")
    conv["_comments"] = fetch_paginated(f"/conversations/{conv_id}/comments")

Step 2: Transform and Map

Run a transformation script over your staging database to convert Front's email-centric payload into Freshchat's schema.

import re
import phonenumbers
 
def transform_contact(front_contact):
    """Transform a Front contact into Freshchat user format."""
    email = None
    phone = None
    for handle in front_contact.get("handles", []):
        if handle["source"] == "email" and not email:
            email = handle["handle"]
        elif handle["source"] == "phone" and not phone:
            raw_phone = handle["handle"]
            try:
                parsed = phonenumbers.parse(raw_phone, "US")
                phone = phonenumbers.format_number(
                    parsed, phonenumbers.PhoneNumberFormat.E164
                )
            except phonenumbers.NumberParseException:
                phone = raw_phone  # Store as-is, flag for manual review
    
    # Validate email format
    if email and not re.match(r'^[^@]+@[^@]+\.[^@]+$', email):
        email = None  # Invalid format; skip
    
    name = front_contact.get("name") or ""
    name_parts = name.strip().split(" ", 1)
    
    return {
        "email": email,
        "phone": phone,
        "first_name": name_parts[0] if name_parts[0] else "Unknown",
        "last_name": name_parts[1] if len(name_parts) > 1 else "",
        "reference_id": front_contact.get("id"),  # Preserve Front ID for idempotency
        "properties": transform_custom_fields(front_contact.get("custom_fields", {}))
    }
 
def transform_custom_fields(front_fields):
    """Map Front custom fields to Freshchat properties."""
    properties = []
    for field_name, field_value in front_fields.items():
        if field_value is not None:
            fc_name = re.sub(r'[^a-z0-9_]', '_', field_name.lower().strip())
            properties.append({
                "name": fc_name,
                "value": str(field_value)[:1024]  # Freshchat text property max length
            })
    return properties

Key transformations to handle during this step:

• Split contact names into first/last. Handle edge cases: single-word names, names with multiple spaces, names with prefixes (Dr., Mr.)
• Normalize phone numbers to E.164 using phonenumbers library (Python) or libphonenumber (Node.js)
• Convert picklist/enum values to match Freshchat property types. On Growth plans, all custom properties are text—dropdown values become plain strings.
• Map statuses: Front assigned → Freshchat assigned, Front unassigned → Freshchat new, Front archived → Freshchat resolved
• Strip complex HTML from email bodies. Freshchat's chat UI does not render nested HTML tables, <style> blocks, or complex CSS. Use a library like bleach (Python) to whitelist basic HTML tags (<p>, <br>, <a>, <b>, <i>, <ul>, <li>) and strip everything else.
• Deduplicate contacts before loading. Front allows multiple contacts with similar names but different channels; Freshchat deduplicates on email. Merge strategy: keep the most recently updated record as canonical, merge custom fields from duplicates.

Step 3: Load Agents and Users

Push all Teammates (Agents) first, then Contacts (Users) to Freshchat. Store the resulting Freshchat IDs in your staging database to maintain relational links. Agents must exist in Freshchat before importing historical data, or messages will be orphaned with no assigned author.

FRESHCHAT_API_KEY = "your_freshchat_api_token"  # Load from vault
FRESHCHAT_URL = "https://youraccount.freshchat.com/v2"
FC_HEADERS = {
    "Authorization": f"Bearer {FRESHCHAT_API_KEY}",
    "Content-Type": "application/json"
}
 
def create_freshchat_user(user_data, id_map):
    """Create a user in Freshchat with idempotency check."""
    ref_id = user_data.get("reference_id")
    
    # Check if already migrated (idempotency)
    if ref_id in id_map:
        logger.info(f"Skipping already-migrated contact: {ref_id}")
        return id_map[ref_id]
    
    response = requests.post(
        f"{FRESHCHAT_URL}/users",
        headers=FC_HEADERS,
        json=user_data
    )
    
    if response.status_code == 429:
        logger.warning("Freshchat rate limit hit. Waiting 60s.")
        time.sleep(60)
        return create_freshchat_user(user_data, id_map)
    
    if response.status_code == 409:
        # Duplicate email - GET existing user and update
        logger.info(f"Duplicate user for {user_data.get('email')}. Merging.")
        # Handle merge logic here
        return None
    
    if response.status_code in (200, 201):
        result = response.json()
        id_map[ref_id] = result["id"]
        return result
    
    logger.error(f"Failed to create user: {response.status_code} {response.text}")
    return None

Loading order is critical. Always follow dependency order:

1. Agents (must exist before conversations can be assigned)
2. Companies (if using Freshdesk Omni)
3. Users/Contacts (linked to companies if applicable)
4. Conversations (linked to users and channels)
5. Messages (appended to conversations in chronological order)
6. Attachments (uploaded and linked to messages)

Step 4: Load Conversations and Messages

Iterate through Front conversations. For each conversation, create a Freshchat conversation with the initial message, then POST remaining messages in chronological order to the new Freshchat conversation ID.

def create_conversation(user_id, channel_id, messages, agent_id_map):
    """Create a conversation with initial message in Freshchat."""
    # Sort messages chronologically
    sorted_msgs = sorted(messages, key=lambda m: m["created_at"])
    first_msg = sorted_msgs[0]
    
    # Determine actor type and ID
    if first_msg.get("is_inbound"):
        actor_type = "user"
        actor_id = user_id
    else:
        actor_type = "agent"
        actor_id = agent_id_map.get(first_msg.get("author", {}).get("id"))
    
    payload = {
        "app_id": "your_app_id",
        "channel_id": channel_id,
        "users": [{"id": user_id}],
        "messages": [{
            "message_parts": [{
                "text": {"content": sanitize_html(first_msg.get("body", ""))}
            }],
            "app_id": "your_app_id",
            "actor_type": actor_type,
            "actor_id": actor_id
        }]
    }
    
    response = requests.post(
        f"{FRESHCHAT_URL}/conversations", 
        headers=FC_HEADERS, 
        json=payload
    )
    
    if response.status_code in (200, 201):
        conv_id = response.json().get("conversation_id")
        # Append remaining messages
        for msg in sorted_msgs[1:]:
            append_message(conv_id, msg, user_id, agent_id_map)
            time.sleep(1.2)  # Rate limit compliance
        return conv_id
    
    logger.error(f"Failed to create conversation: {response.status_code} {response.text}")
    return None
 
def append_message(conv_id, message, user_id, agent_id_map):
    """Append a single message to an existing Freshchat conversation."""
    is_comment = message.get("_type") == "comment"
    
    if message.get("is_inbound"):
        actor_type = "user"
        actor_id = user_id
    else:
        actor_type = "agent"
        actor_id = agent_id_map.get(message.get("author", {}).get("id"))
    
    payload = {
        "message_parts": [{
            "text": {"content": sanitize_html(message.get("body", ""))}
        }],
        "actor_type": actor_type,
        "actor_id": actor_id,
        "message_type": "private" if is_comment else "normal"
    }
    
    return requests.post(
        f"{FRESHCHAT_URL}/conversations/{conv_id}/messages",
        headers=FC_HEADERS,
        json=payload
    )

Map Front comments to Freshchat private notes by setting message_type: private on the message payload.

Step 5: Upload Attachments

Extract attachment URLs from Front messages, download the binary files, and upload them to Freshchat using multipart/form-data endpoints. Link the resulting Freshchat CDN URL to the message.

At 50 requests/minute, downloading 10,000 attachments takes roughly 3.3 hours of pure API time. Uploading them to Freshchat takes another 3.3 hours. Batch attachment downloads in a separate queue from message extraction to parallelize where possible.

Attachment size limits: Freshchat accepts attachments up to 20MB per file. Front attachments exceeding this limit must be compressed, split, or linked externally (e.g., upload to S3 and include the URL in the message body).

Step 6: Validate

Run validation queries against both platforms after each batch—don't wait until the full migration is complete.

def validate_migration(front_contacts, freshchat_users):
    """Compare record counts and sample field values."""
    front_emails = set()
    for fc in front_contacts:
        for h in fc.get("handles", []):
            if h["source"] == "email":
                front_emails.add(h["handle"].lower())
    
    fc_emails = {u.get("email", "").lower() for u in freshchat_users if u.get("email")}
    
    missing = front_emails - fc_emails
    extra = fc_emails - front_emails
    
    report = {
        "front_contact_count": len(front_contacts),
        "freshchat_user_count": len(freshchat_users),
        "front_unique_emails": len(front_emails),
        "freshchat_unique_emails": len(fc_emails),
        "missing_in_freshchat": len(missing),
        "extra_in_freshchat": len(extra),
        "match_rate": f"{(1 - len(missing) / max(len(front_emails), 1)) * 100:.1f}%"
    }
    
    logger.info(f"Validation report: {json.dumps(report, indent=2)}")
    
    if missing:
        logger.warning(f"Sample missing contacts: {list(missing)[:10]}")
    
    return report

Validation targets:

For error handling throughout the pipeline: log every source ID, target ID, payload hash, response code, and retry attempt. Use exponential backoff with jitter on 429 and 5xx responses. Keep a dead-letter queue for failed records. Make loaders idempotent by storing the legacy Front ID in Freshchat's reference_id—reruns should update or skip rather than duplicate.

Edge Cases and Challenges

Duplicate Contacts

Front allows multiple contacts with the same email across shared and private inboxes. Freshchat deduplicates on email. Run deduplication during the transform step—merge custom fields and pick the most recently updated record as canonical, or you'll hit 409 Conflict errors on load. In practice, expect 5–15% of Front contact lists to contain duplicates by email.

Multi-Inbox Conversations

A Front conversation can appear in one or more inboxes (e.g., if you receive an email on contact@ where support@ is CC'd). Freshchat conversations belong to a single channel. You need to pick a primary channel (the inbox where the conversation was created or most recently active) or duplicate the conversation—neither is perfect. Duplicating inflates metrics; picking one loses routing context.

Inline Images in Emails

Front emails often contain base64 inline images (CID-referenced or directly embedded). Freshchat's API will reject massive base64 strings in the text body—the practical limit is approximately 64KB for message content. You must:

1. Parse the HTML body for <img> tags with base64 src attributes or CID references
2. Extract the binary data and decode from base64
3. Upload each image as an attachment to Freshchat
4. Replace the <img> tag with the new Freshchat CDN URL or an attachment reference

Missing or Departed Teammates

If a Front Teammate has left the company, you cannot map their messages to an active Freshchat Agent without consuming a paid seat. Create a single generic "Legacy Agent" account in Freshchat (e.g., legacy-support@yourcompany.com) and map all departed teammates' messages to it. Store the original author name in the message body as a prefix: [Originally from: Jane Smith] ....

Internal Comments vs. Private Notes

Front's comments are threaded within a conversation but separate from the message timeline. Freshchat's private messages appear inline with regular messages in chronological order. Timestamp ordering may differ, and agents will see a different visual layout. Prepend private notes with [Internal Note] to make them visually distinguishable.

Email Subjects

Freshchat conversations do not have "Subjects" like emails. Map the Front email subject to a custom Conversation Property in Freshchat (e.g., cf_original_subject). This preserves searchability but requires the property to be created in Freshchat admin before migration.

Conversation Model Mismatch

Front's email-thread model supports CC, BCC, and forwarding. Freshchat's linear chat model does not. Forwarded messages and CC chains lose context in translation. Preserve CC/BCC information by appending it to the message body: [CC: alice@example.com, bob@example.com].

Multi-Level Relationship Order

Front Account → Contact → Conversation. If you import a conversation before the Account is created in Freshchat (via Freshdesk Omni), the data will lack organizational context. Always load in dependency order: Companies → Users → Conversations → Messages.

Bot/AI Agent Migration

If your Front instance uses chatbot integrations (e.g., via Intercom, Ada, or custom bots), those flows do not migrate to Freshchat. You must rebuild them in Freshchat's AI Agent Studio, which uses a visual flow builder with intent detection, conditions, and action nodes. Export your Front bot conversation flows as documentation, then recreate the decision trees in AI Agent Studio. Plan 1–2 weeks for complex bot rebuilds.

Mobile SDK Considerations

If your Front integration includes mobile app messaging (via Front Chat SDK or similar), you'll need to replace it with Freshchat's mobile SDK. Freshchat provides native SDKs for iOS (Swift/Objective-C), Android (Java/Kotlin), and cross-platform frameworks (React Native, Flutter). The SDK integration typically requires 2–5 days of mobile development time. Historical conversations from the mobile channel will not automatically appear in the new SDK—they must be migrated via the API like any other conversation.

Limitations and Constraints

Be explicit with stakeholders about what gets lost or degraded:

• No account-level structure in standalone Freshchat. If you use Front accounts for routing or reporting, that hierarchy disappears unless you adopt Freshdesk Omni (starting at $49/agent/month for Growth plan).
• Historical timestamps are not guaranteed to render correctly. Freshchat's public POST /conversations and POST /conversations/{id}/messages endpoints do not clearly expose a created_time input field for backdating messages. Messages are timestamped at creation time by default. Most teams store legacy timestamps in custom properties or prepend them in the message body (e.g., [Original Date: 2023-04-12T14:30:00Z]). Verify what your Freshchat tier supports before assuming backdating works.
• No true custom objects in standalone Freshchat. Front allows flexible custom metadata on conversations. Freshchat relies on standard properties. Complex custom objects must be stored as stringified JSON in a custom text field (max 1024 chars) or moved to Freshsales. Freshchat Suite plans support up to 10 custom modules and 310 fields per module.
• Rules and automations don't migrate. Every Front rule must be manually rebuilt as a Freshchat automation or IntelliAssign configuration. No import path exists. Budget 2–5 hours per complex rule for recreation and testing.
• Analytics history resets. SLA metrics, response times, CSAT scores, and agent performance data from Front don't carry over. Export Front analytics reports before migration for baseline comparisons.
• API rate limits bottleneck large migrations. At 50 req/min on each side, plan for 4–7 days of execution time on datasets exceeding 50K conversations. API rate limit add-ons can be purchased to increase limits (300 additional calls per minute per add-on). Purchasing a rate limit add-on for Front is recommended for migrations exceeding 25K conversations.
• Front's export files are large and incomplete. Front's export files represent about 700MB of data each, alphabetically ordered. The support-assisted export excludes individual inbox data, contact data, message templates, and tags.
• Some Freshchat conversation-property APIs are Suite-only. Certain endpoints (e.g., conversation property creation, advanced custom fields) are available only for chat accounts that are part of Freshsales Suite. Verify which endpoints are available to you before building the pipeline by testing each endpoint in a sandbox.
• Freshchat message content limits. Individual message content is limited to approximately 64KB. Front email messages can be significantly larger—truncate or split oversized messages during transformation.

Validation and Testing

Record Count Comparison

After migration, compare:

Field-Level Validation

Pull 20–50 random records from both platforms. Compare:

• Name, email, phone (exact match)
• Custom field values (type-appropriate match)
• Conversation status (mapped correctly)
• Message body content (first and last message—check for truncation or encoding issues)
• Timestamps (check timezone alignment—Front uses UTC; verify Freshchat timezone setting)
• Attachment presence and accessibility (can you download the file from Freshchat?)

Freshchat's reports/raw export to CSV can be useful for post-load QA against source-side samples.

UAT Process

1. Have 2–3 senior support agents review their assigned conversations in Freshchat.
2. Ask them to locate 5 specific historical, complex customer interactions by searching for customer name or email.
3. Verify that customer context (contact details, history, attachments, internal notes) is visible and correct.
4. Test reply functionality—ensure new messages don't create duplicate threads.
5. Confirm routing rules work as expected in the new channel structure.
6. Test the web chat widget to ensure new conversations are created correctly.
7. If using WhatsApp or other messaging channels, send a test message through each channel.

Rollback Plan

Keep Front active in read-only mode for at least 30 days post-migration. If critical data is missing or corrupted in Freshchat, agents can reference Front while issues are resolved. Do not cancel your Front subscription until:

1. Validation is complete and stakeholders sign off.
2. At least 2 full weeks of live operation on Freshchat with no critical issues.
3. All automation rules have been verified as functioning correctly in Freshchat.
4. Analytics baselines have been established in Freshchat for comparison.

Post-Migration Tasks

• Rebuild automations. Map every Front rule to a Freshchat automation. Document what each rule did (trigger, condition, action), then recreate using Freshchat's automation builder or IntelliAssign. For rebuild planning, see Your Help Desk Migration's Secret Saboteur: Automations, Macros, and Workflows.
• Configure channels. Set up web chat widgets (Freshchat provides a JavaScript snippet for website embedding), WhatsApp Business API integration, Facebook Messenger, and other channels you were using in Front.
• Set up AI Agent Studio. If you were using chatbot integrations with Front, rebuild conversation flows in Freshchat's AI Agent Studio. Start with your top 5 most common customer intents.
• Agent onboarding. Freshchat's interface is fundamentally different from Front's. Train agents on the difference between an email thread (Front) and a continuous chat timeline (Freshchat). Plan at least two 1-hour training sessions covering: the conversation view, team inbox, canned responses, the agent assignment workflow, IntelliAssign behavior, and private notes vs. public messages.
• Update integrations. Any third-party tools that were hitting Front's API (CRM syncs, monitoring tools, analytics dashboards) need to be re-pointed to Freshchat's API. Document all API consumers before migration.
• Configure webhooks. If you relied on Front's webhooks for real-time notifications to external systems, set up equivalent webhooks in Freshchat (Settings → Webhooks). Freshchat supports webhook events for conversation creation, assignment, resolution, and message creation.
• Monitor for inconsistencies. For the first two weeks post-migration, run daily checks on: conversation volumes (compare to Front baselines), response times, unassigned conversation queue depth, failed webhooks, and agent adoption metrics.

Best Practices

• Back up everything before starting. Export contacts via CSV, request a full data export from Front support, and store raw API snapshots in S3 or equivalent. Retain these backups for at least 90 days post-migration.
• Run test migrations first. Migrate a single inbox or 5% of data into a Freshchat sandbox environment end to end. Validate before proceeding to production. Most Freshchat plans allow a sandbox/trial account for testing.
• Validate incrementally. Don't wait until the full migration is complete. Validate Contacts, then Companies, then Conversations after each batch. Fix errors before proceeding.
• Automate the repetitive. Contact deduplication, field normalization, status mapping, and tag-to-label conversion should be scripted, not done by hand.
• Document the ID crosswalk. Maintain a mapping table of Front IDs → Freshchat IDs for every object type. You need this for debugging, for updating external integrations, and for any future data reconciliation.
• Store source IDs everywhere. Every created record in Freshchat should carry a legacy Front ID (in reference_id or a custom field) so reruns can update or skip instead of duplicating.
• Plan for the long tail. The migration itself is 60% of the project. Post-migration cleanup, automation rebuilding, agent training, and monitoring take the remaining 40%. Budget accordingly.
• Monitor API usage costs. If you purchase Front rate limit add-ons ($300/add-on/month), factor this into the migration budget. A typical enterprise migration needs the add-on for 1–2 months.

Sample Data Mapping Table

What to Read Next

If you're evaluating Front alternatives or planning a broader platform migration:

• Front Migration Checklist — Pre-flight checklist for any migration out of Front.
• How to Migrate from Front to Zendesk — If Zendesk is also on your shortlist.
• Help Desk Data Migration Playbook — Framework for deciding what to move and what to leave behind.
• Post-Migration QA Checklist — Detailed test plan for validating your migrated data.