Freshchat to Kayako Migration: A Technical Guide

Freshchat to Kayako Migration: A Technical Guide

What This Migration Actually Involves

Freshchat is Freshworks' conversation-first messaging platform. It handles real-time conversations across web chat, WhatsApp, Facebook Messenger, Instagram, Apple Business Chat, and email. Its data model is conversation-centric: every interaction is a Conversation containing a stream of Messages, each with its own sender, timestamp, and message type (normal, private, system). Conversations have no subject lines. Statuses are limited to four values: new, assigned, waiting, and resolved.

Kayako (this guide applies to Kayako Helpdesk, not Kayako Classic) is a case-based helpdesk, and a Freshchat to Kayako migration has to build those cases from scratch. Interactions are stored as Cases, which require a subject, department, status, priority, and type. Individual replies within a case are stored as Posts. Kayako supports channels including MAIL, HELPCENTER, TWITTER, MESSENGER, FACEBOOK, and NOTE. The bulk import endpoint only supports MAIL and NOTE — other channel types must be stored as metadata.

The structural mismatch between these two models—a common challenge when translating a conversation-centric platform into a ticket-centric one—drives four concrete design decisions:

• One Freshchat conversation maps to one Kayako case. The conversation_id is the most stable thread key across both the messages API and raw transcript exports.
• You must synthesize subject lines. Freshchat has no concept of a ticket subject. The standard approach is to truncate the first text content in message_parts to roughly 50 characters.
• Rich message parts need flattening. Freshchat messages contain a message_parts array that can include text, images, buttons, quick-reply options, and collection cards. Kayako posts accept plain text or HTML. Bot-interaction UI elements (carousels, input controls) lose their interactive structure and must be serialized as readable fallbacks.
• Actor types are broader in Freshchat. Freshchat message actors can be user, agent, bot, or system. Kayako posts require a creator_id referencing a pre-existing Kayako user. Bot and system messages must be mapped to a designated placeholder user account.

Why Teams Move from Freshchat to Kayako

• Ticket-centric workflow needs. Teams that need traditional ticket management with SLA tracking, case types, priorities, and formal resolution workflows find Kayako's model a better fit than Freshchat's conversation-first approach.
• Self-hosted requirements. Kayako Classic offers self-hosted deployment. Freshchat is cloud-only.
• Help center integration. Kayako includes a built-in help center tightly coupled to the case system. Freshchat relies on Freshdesk or external knowledge bases.
• Channel consolidation. Teams already using Kayako for email and ticket support who want to fold Freshchat messaging history into a single system of record.

Freshchat API: Extraction Constraints

The Freshchat REST API v2 is your primary extraction path. There are two practical extraction patterns, and most successful projects use both.

Base URL: https://{subdomain}.freshchat.com/v2

Authentication: Bearer token via API key generated in Freshchat Admin → Settings → API Tokens. Pass as Authorization: Bearer <API_KEY> header.

Key Extraction Endpoints

Rate Limits

Freshchat rate limits are enforced but not fully documented per-plan. The API returns HTTP 429 when limits are exceeded. The dashboard API has a documented limit of 100 requests per minute. Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset — build your extractor to read these headers dynamically instead of hard-coding a fixed request cadence. Implement exponential backoff starting at 2 seconds, doubling on each consecutive 429.

The N+1 Query Problem

The conversations list endpoint (GET /v2/conversations) returns metadata — channel_id, status, user_id — but not the actual message content. For every conversation, you must make at least one separate call to fetch its messages, paginated at 50 per page.

Concrete arithmetic for a 15,000-conversation dataset:

• 15,000 conversations ÷ 100 per page = 150 list API calls
• 15,000 conversations × average 8 messages ÷ 50 per page = ~2,400 message-fetch calls
• Total calls: ~2,550 minimum (more for longer conversations)
• At 100 req/min with a conservative 600ms average call duration: 2,550 calls ÷ 100 req/min = ~25.5 minutes of pure call time under ideal conditions
• In practice, 429 backoff events, network latency, and sequential (non-async) execution multiply this 3–6× — yielding 75–150 hours for a naively synchronous implementation

Run message fetches asynchronously using a worker queue or Python's aiohttp with a semaphore controlling concurrency. Respect X-RateLimit-Remaining on every response. Do not hard-code sleep intervals.

Raw Reports: A Faster Path for Historical Backfill

Freshchat's raw reports API (POST /v2/reports/raw/) emits pre-built CSV datasets designed for reporting and downstream processing. This is faster than per-conversation fetches for large historical ranges, but has strict windowing constraints:

• start cannot be earlier than 15 months from the current date
• end cannot be more than one month after start
• The Chat-Transcript report is limited to 24-hour windows per request

For transcript reconstruction, the most useful fields are: conversation_id, message_id, customer_id, message_type, detailed_message_type, message_parts, and created_time. A multi-day conversation must be stitched together by conversation_id across many daily extracts. Companion datasets (Conversation-Created, Conversation-Resolved, Conversation-Activity) are useful for count reconciliation, reopen detection, and QA validation.

Contact/Agent Split

Freshchat maintains separate object types for contacts (customers) and agents. GET /v2/contacts does not return agents, and GET /v2/agents does not return contacts. Your user-mapping script must pull both endpoints and merge them into a unified freshchat_id → type → kayako_id lookup table before transformation begins.

Handling Multi-Channel Contacts

A single Freshchat contact may have simultaneous conversations across multiple channels — web chat, WhatsApp, and email — resulting in multiple distinct conversation_id values for the same requester. These are not duplicates; they are separate threads. Do not deduplicate by user_id alone. Each conversation should map to its own Kayako case. If you need to link them, store the shared user_id (mapped to the Kayako requester) as a common field — the case-level relationship is established through the shared requester, not through merging threads.

Handling Attachments

Freshchat attachments are returned as signed URLs within the message payload. These URLs are time-limited and will expire — the exact TTL is not publicly documented but is typically hours to days. Download all attachments during the extraction phase, not during transformation. Store them locally or in object storage (S3, GCS) keyed by message_id + filename. Attempting to pass a Freshchat URL directly to Kayako will fail silently for any attachment where the URL has already expired.

Multilingual and Encoding Considerations

Freshchat deployments in Arabic, Japanese, or CJK character sets can produce encoding issues when flattening message_parts to HTML or plain text. Always use ensure_ascii=False when serializing JSON message content in Python. For HTML output, set charset=utf-8 in your content-type headers when uploading to Kayako. Test with a multilingual conversation sample before running the full pipeline.

Extraction Script Pattern

import requests
import time
 
FRESHCHAT_BASE = "https://{subdomain}.freshchat.com/v2"
HEADERS = {
    "Authorization": "Bearer <API_KEY>",
    "Accept": "application/json"
}
 
def fetch_all_conversations():
    conversations = []
    page = 1
    while True:
        resp = requests.get(
            f"{FRESHCHAT_BASE}/conversations",
            headers=HEADERS,
            params={"page": page, "items_per_page": 100,
                    "sort_by": "created_time", "sort_order": "asc"}
        )
        if resp.status_code == 429:
            wait = int(resp.headers.get("Retry-After", 10))
            time.sleep(wait)
            continue
        data = resp.json()
        convos = data.get("conversations", [])
        if not convos:
            break
        conversations.extend(convos)
        if not data.get("pagination", {}).get("next_link"):
            break
        page += 1
    return conversations
 
def fetch_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:
            wait = int(resp.headers.get("Retry-After", 10))
            time.sleep(wait)
            continue
        data = resp.json()
        msgs = data.get("messages", [])
        if not msgs:
            break
        messages.extend(msgs)
        page += 1
    return messages

For a detailed breakdown of all Freshchat export methods, see How to Export Data from Freshchat: Methods, API Limits & Formats.

Kayako API: Import Constraints

Base URL: https://{subdomain}.kayako.com/api/v1

Authentication: HTTP Basic Auth with admin username and password.

Key Import Endpoints

Critical Import Details

• Bulk import preserves timestamps. POST /api/v1/bulk/cases accepts created_at and updated_at in ISO-8601 format (YYYY-MM-DDThh:mm:ssTZD) on both cases and inline posts. The single-case POST /api/v1/cases endpoint and the POST /api/v1/cases/:id/reply endpoint do not support timestamp overrides — they stamp the current server time. Use the bulk endpoint for all historical data. Always verify timestamp preservation behavior in your specific Kayako sandbox instance before full-scale import.
• 200 cases per batch, async execution. Each bulk request can contain up to 200 cases with inline posts. The endpoint returns 202 Accepted with a job ID. You must poll GET /api/v1/jobs/{id} until the job status returns COMPLETED or FAILED before submitting the next dependent batch.
• partial_import post-level behavior. The partial_import=true parameter causes the endpoint to insert valid cases and return invalid ones in the error payload. However, whether a case with one invalid post is inserted as a truncated case (without the failing post) or dropped entirely depends on where the validation failure occurs. In practice: a case-level validation failure (missing required field) drops the entire case; a post-level validation failure (malformed content) may drop only the post. Verify this behavior in your sandbox with a deliberately malformed test payload before relying on it for production. Log both inserted counts and error payloads on every batch.
• legacy_id for cross-referencing and idempotency. The bulk import accepts a legacy_id string field per case. Store the Freshchat conversation_id here. This is the cleanest anchor for idempotency checks — before re-running any batch, query GET /api/v1/cases?legacy_id={conversation_id} to check for existing records. Note: Kayako does not enforce legacy_id uniqueness at the API level, so duplicate imports are possible if you re-run without cleanup.
• Bulk channel types are limited. The bulk import endpoint only supports MAIL and NOTE as channel types. Preserve the original Freshchat channel identity (web chat, WhatsApp, etc.) in a custom case field or tag.
• Rate limits are not publicly documented. Kayako returns HTTP 429 with a Retry-After header. Start at 2–3 bulk requests per second and back off on every 429. Aggressive pacing against the async bulk endpoint can queue jobs faster than Kayako processes them, causing delayed FAILED responses.
• Default page size is 10. When reading back imported data for validation, set limit=100 explicitly. Archived cases are excluded from default queries — append archived=1 to include them.
• Webhook/callback support for bulk jobs. Kayako does not provide webhook callbacks on bulk job completion as of this writing. Polling GET /api/v1/jobs/{id} at 5-second intervals is the supported pattern.

Kayako Status IDs Are Instance-Specific

Kayako status IDs are assigned per instance and vary between deployments. Always call GET /api/v1/cases/statuses on your target Kayako instance to retrieve the actual ID values before building your transformation. The response schema is:

{
  "data": [
    {"id": 1, "label": "NEW", "type": "NEW"},
    {"id": 2, "label": "OPEN", "type": "OPEN"},
    ...
  ]
}

Do not hardcode status IDs. The table below shows the Freshchat-to-Kayako status concept mapping only — the numeric IDs must be resolved from your instance at runtime:

Data Model Mapping: Freshchat → Kayako

Field-Level Mapping

Generating Case Subjects

Freshchat conversations have no subject field. Generate one programmatically from the first message:

def generate_subject(messages):
    if not messages:
        return "Empty Chat Transcript"
    first_text = ""
    for part in messages[0].get("message_parts", []):
        if "text" in part:
            first_text = part["text"].get("content", "")
            break
    if not first_text:
        return "Chat Transcript"
    if len(first_text) > 50:
        return first_text[:47] + "..."
    return first_text

Flattening Rich Messages

Freshchat messages can include structured reply_parts, collections, quick replies, and template content. Kayako posts are text or HTML. Use ensure_ascii=False when serializing non-ASCII content:

import json
 
def flatten_message(msg):
    parts = []
    for part in msg.get("message_parts", []):
        if "text" in part:
            parts.append(part["text"]["content"])
        if "file" in part:
            parts.append("[attachment] " + part["file"]["name"])
        if "image" in part:
            parts.append("[image] " + part["image"]["url"])
    if msg.get("reply_parts"):
        parts.append("[Bot UI elements — original JSON preserved below]")
        parts.append(json.dumps(msg["reply_parts"], ensure_ascii=False))
    header = "[" + msg.get("actor_type", "unknown") + "]"
    return "\n".join([header] + parts)

A plain-text serialization of bot elements is more useful to agents than a partially preserved widget structure that Kayako cannot render. Explicitly label discarded interactive elements with [Button: "Talk to agent"] or similar so agents understand what was there.

Step-by-Step Migration Pipeline

Step 1: Pre-Migration Setup

1. Generate API credentials for both platforms. Freshchat: Admin → Settings → API Tokens. Kayako: use admin username/password for Basic Auth, or Admin → Apps → API Keys if your instance supports token auth.
2. Inventory your Freshchat data. Collect: total conversation count, total message count (estimate from raw reports), total contacts and agents, approximate attachment volume in GB, and oldest conversation date. If data older than 15 months exists, the raw reports API cannot cover it — you must use the per-conversation messages API for that date range.
3. Provision a Kayako sandbox. Request a sandbox instance from Kayako support or use a staging subdomain. Run all timestamp, partial_import, and channel-type tests against the sandbox before touching production. A realistic test dataset should include: one conversation with attachments, one bot-only conversation, one conversation reopened multiple times, and one conversation with non-ASCII characters.
4. Pre-create Kayako infrastructure. Create teams, custom case fields, case types, priorities, and status values in Kayako before import. Query GET /api/v1/cases/statuses, GET /api/v1/departments, GET /api/v1/teams, and GET /api/v1/cases/fields and record all IDs in a local config file.
5. Build a user mapping table. Extract all Freshchat agents (GET /v2/agents) and contacts (GET /v2/contacts) as separate lists. Create corresponding Kayako users via POST /api/v1/bulk/users. Store the mapping as {freshchat_id: {type: "agent"|"contact", kayako_id: ...}}. Map departed agents to a "Legacy Agent" placeholder account to avoid orphaned records. Create a "Bot/System" placeholder user for actor_type = bot and system messages.

Step 2: Extract Freshchat Data

1. Pull conversations using paginated GET /v2/conversations calls (100 per page, sorted ascending by created_time).
2. For each conversation, pull all messages via GET /v2/conversations/{id}/messages (50 per page max). Run message fetches asynchronously. This is the bottleneck step — see runtime estimates below.
3. Download all attachments immediately. Do not defer to the transformation phase. Store locally keyed by {message_id}_{filename}.
4. Export raw reports for CSAT, resolution times, and agent assignments via POST /v2/reports/raw/ in 24-hour windows, covering the full 15-month range available.
5. Store everything in a staging database. PostgreSQL works well. Create tables for conversations, messages, contacts, agents, and attachments with the raw JSON preserved alongside parsed fields. This allows re-running transformation without re-extraction.

Step 3: Transform Data

1. Flatten message_parts into HTML for each message. Replace interactive elements with human-readable text: [Button: "Talk to agent"], [Quick reply: "Yes"].
2. Generate subject lines from the first message of each conversation using the function above.
3. Map users using the lookup table from Step 1. Flag any unmapped actor_id values — these indicate contacts or agents missing from your extraction.
4. Map statuses, priorities, and types to Kayako IDs resolved from your instance API.
5. Upload attachments to Kayako via the file upload endpoint. Receive back file_id values. Associate each file_id with the corresponding message record in your staging database.
6. Build Kayako bulk payloads. Each payload contains up to 200 cases with inline posts, timestamps, legacy_ids, and attachment_file_ids. Validate payload structure against the Kayako API schema before submission.

Step 4: Load into Kayako

1. Submit bulk case batches of up to 200 via POST /api/v1/bulk/cases?partial_import=true.
2. Poll job status via GET /api/v1/jobs/{id} at 5-second intervals until each batch reports COMPLETED or FAILED.
3. Log both successful inserts and error payloads. Record the returned Kayako case IDs alongside the source legacy_id (Freshchat conversation_id) in your staging database.
4. Reprocess failures individually, inspecting the error payload to determine whether failure was at case level or post level.
5. Pace your requests. Start at 1 batch per 5 seconds. Back off on every 429.

import requests
import json
import time
 
KAYAKO_BASE = "https://{subdomain}.kayako.com/api/v1"
AUTH = ("admin@example.com", "password")
 
def submit_batch(cases_batch):
    resp = requests.post(
        f"{KAYAKO_BASE}/bulk/cases?partial_import=true",
        auth=AUTH,
        headers={"Content-Type": "application/json"},
        data=json.dumps({"cases": cases_batch})
    )
    if resp.status_code == 429:
        wait = int(resp.headers.get("Retry-After", 60))
        time.sleep(wait)
        return submit_batch(cases_batch)
    if resp.status_code == 202:
        job_url = resp.json()["data"]["resource_url"]
        return poll_job(job_url)
    raise Exception(f"Unexpected status {resp.status_code}: {resp.text}")
 
def poll_job(job_url):
    while True:
        resp = requests.get(job_url, auth=AUTH)
        data = resp.json()["data"]
        if data["status"] == "COMPLETED":
            return data
        if data["status"] == "FAILED":
            raise Exception(f"Job failed: {data}")
        time.sleep(5)

Step 5: Delta Sync and Cutover

Freezing support operations for 5–9 days is not feasible. Use a delta sync strategy:

1. Initial load: Run the migration on all historical data up to a specific cutover timestamp (e.g., all conversations with created_time before Friday 00:00 UTC). Your team continues working in Freshchat.
2. Delta sync: On cutover day, query only conversations created_time or updated_time after that timestamp. The smaller volume finishes in hours.
3. Cutover: Update DNS records, website widgets, and routing to direct new traffic to Kayako. Team logs out of Freshchat and into Kayako.
4. Final catch-up: Run the delta script one more time to capture conversations updated during the switchover window.
5. Read-only period: Keep Freshchat active in read-only mode for at least 14 days before decommissioning. This preserves access for audit and any discovered migration gaps.

Step 6: Validate

API calls returning success codes does not confirm data integrity. Run all of the following:

• Count reconciliation: Compare total conversations in Freshchat against total cases in Kayako. Compare total messages in your staging database against total posts in Kayako. A >1% discrepancy warrants investigation before cutover.
• Timestamp spot-checks: Sample 20+ cases and verify that created_at in Kayako matches the original Freshchat conversation created_time, not the date your migration script ran. This is the most common silent failure.
• Attachment verification: Sample 5–10% of conversations with attachments. Open each in Kayako and confirm files are accessible and correctly associated with the right post.
• Thread usability checks: Open a sample of bot-heavy conversations, reopened conversations, and multilingual conversations. Verify the flattened content is readable and correctly attributed by actor_type.
• Multi-channel contact check: For contacts with conversations across multiple Freshchat channels, verify that all conversations appear as separate Kayako cases linked to the same requester.
• Archived case access: Use GET /api/v1/cases/{id}/posts?archived=1 for any resolved cases that Kayako has archived. Standard queries exclude archived cases.

What Cannot Be Migrated

Some data and configuration will not transfer programmatically:

• Freddy bot flows and configurations — Must be rebuilt manually in Kayako or a third-party bot tool. As we note in our Freshchat to Ada migration guide, bot migration is always a redesign, never a direct conversion.
• IntelliAssign routing rules — Kayako uses its own assignment automation. Rebuild using Kayako Triggers and Monitors.
• CSAT survey configuration — Raw CSAT scores can be preserved as custom field values, tags, or internal notes (e.g., [Historical Data: Customer rated this interaction 5/5]). Survey logic must be rebuilt natively.
• Canned responses / macros — Must be manually recreated in Kayako's macro engine.
• Widget customizations — Kayako Messenger uses its own configuration interface.
• Marketplace app integrations — Freshchat marketplace apps must be replaced with Kayako equivalents or custom integrations.
• Agent performance metrics and historical reports — Export from Freshchat raw reports before decommissioning. This data does not transfer to Kayako reporting.
• Rich interactive message elements — Carousels, quick-reply buttons, and input controls lose interactivity. They are preserved as labeled text fallbacks only.

Edge Cases and Failure Modes

• Conversations with no messages. Some conversations are created by automation or bots but contain zero messages. The Kayako bulk import requires at least one post per case. Filter these out during transformation or inject a placeholder post: [No messages — automated conversation].
• User creation race condition. Bulk user import jobs run asynchronously. If your user import has not finished when you submit the first case batch, requester_id and creator_id references will fail validation. Always poll user import jobs to COMPLETED status before starting case import.
• partial_import and post-level failures. A post with malformed content (oversized payload, invalid encoding, null creator_id) may be dropped while the parent case is inserted. This produces a case in Kayako with fewer posts than in Freshchat — silent data loss. Log the full error payload from every job and reconcile post counts per case, not just case counts.
• legacy_id is not enforced as unique. Kayako's API does not prevent duplicate legacy_id values. Re-running a migration batch without cleanup creates duplicate cases. Build idempotency into your script: before submitting a batch, query GET /api/v1/cases?legacy_id={conversation_id} for a sample of records to detect prior runs.
• Attachment URL expiration. Freshchat signed attachment URLs expire. Download during extraction. If you discover expired URLs during transformation, you cannot recover those attachments without re-running extraction against the source (which may itself fail if the Freshchat conversation is old).
• Conversation property schema access. Freshchat's conversation property definition API is documented as available only for accounts that are part of Freshsales Suite. Even there, default properties (group, agent, status) are not returned. Capture the custom property schema manually from the Freshchat admin interface early in the project.
• Freshchat interaction_id changes on reopen. Each time a resolved conversation is reopened, Freshchat assigns a new interaction_id while keeping the same conversation_id. If reopen history matters for compliance or audit, store all distinct interaction_id values encountered in a custom field or migration note. Do not discard this data.
• Multi-channel contact deduplication. A single Freshchat contact with simultaneous or sequential conversations across web chat, WhatsApp, and email will appear as multiple distinct conversation_id records, all sharing the same user_id. These should map to separate Kayako cases under the same requester. Do not merge these threads — they represent different channel interactions. Verify that your user mapping correctly resolves the shared user_id to a single Kayako requester.

Runtime Estimates

Calculation basis for 15,000 conversations, ~8 messages average, 5% with attachments:

Larger instances (50K+ conversations) or attachment-heavy datasets scale approximately linearly with conversation count. Extraction is always the bottleneck. Moving from synchronous to async message fetching is the single highest-impact optimization available.

DIY vs. Managed Migration

Handle it in-house if:

• Fewer than 5,000 conversations
• No attachments or minimal attachment volume
• No custom fields requiring complex mapping
• You have a Python or Node.js developer with 2+ weeks available and comfortable with API debugging
• You have a staging environment to test against

Use a managed service if:

• 10,000+ conversations
• Attachment preservation is required
• You need the migration completed in under a week
• Historical timestamps must be exactly preserved and verified
• You cannot afford to discover silent data loss (missing posts, expired attachment URLs, encoding failures) after cutover

Making the Right Call

A Freshchat to Kayako migration is a moderately complex API-to-API data pipeline. The structural advantages: Kayako's bulk import endpoint accepts historical timestamps and supports batch operations with inline posts — this is meaningfully better than target platforms that force current-date stamping or require separate post-creation calls. The structural disadvantages: Freshchat's per-conversation message extraction is rate-limited and sequential by default, rich message content requires careful flattening, and neither platform's rate limit behavior is fully documented.

The most operationally dangerous gaps are post-level silent failures under partial_import=true, expired attachment URLs discovered late in the pipeline, and legacy_id duplicate inserts from re-runs without idempotency checks.

Plan for extraction to be 50%+ of your total timeline. Always use async extraction. Use legacy_id on every imported case. Set partial_import=true on every batch and log every error payload. Reconcile post counts per case, not just total case counts. Keep Freshchat in read-only mode for at least 14 days after cutover.

For related migration guides, see our technical walkthroughs on Freshchat to HappyFox migration and Kayako to Freshdesk migration. If you are evaluating Kayako as a target from other platforms, the Zammad to Kayako guide covers a similar load pattern.