Freshchat to Ada Migration: A Technical Guide

Freshchat to Ada Migration: A Technical Guide

Migrating from Freshchat to Ada means moving data from a messaging-first helpdesk to an AI-powered conversational automation platform. These are fundamentally different systems. Freshchat stores conversations, messages, contacts, agents, groups, channels, bot flows, and custom properties. Ada stores end users, knowledge articles, variables, custom instructions, and AI agent conversations. A straight data dump will land most of it in the wrong shape or not land at all.

The hardest constraint to internalize upfront: Ada's Conversations API creates new, live conversations — it does not accept historical records. There is no endpoint that lets you POST a Freshchat conversation transcript into Ada as a historical artifact. This single fact shapes the entire migration architecture—a fundamental platform constraint that similarly dictates the strategy for Ada to Ada migrations. (docs.ada.cx)

This guide covers extraction from Freshchat, Ada's import surface, data mapping, what transfers and what doesn't, rollback procedures, validation methodology, and how to handle the gaps.

What Changes Architecturally

Freshchat's Freddy bots operate on scripted dialog trees: decision nodes, conditional branches, API actions, and carousels. Ada's generative AI agent resolves inquiries by reasoning over knowledge articles, applying custom instructions, and executing actions — there are no dialog trees.

This is not a feature parity gap. It is a model difference. Freddy flows are imperative (do X, then Y, if Z branch to W). Ada is declarative (here is knowledge; here are instructions; let the model reason). Bot migration from one to the other is always a redesign, never a conversion.

Common reasons teams make this move include:

• Bot maintenance overhead: Freshchat's dialog tree model requires manual updates for every variation in customer phrasing. Ada's knowledge-grounded approach scales resolution coverage without proportional bot-building effort.
• Channel flexibility: Ada's Conversations API allows teams to build custom channels, powering a single AI agent across proprietary messaging interfaces.
• Automation depth: Freddy's scripted flows require anticipated paths. Ada handles unanticipated phrasings by reasoning over knowledge sources.

Note: Deflection rate improvements depend entirely on knowledge article quality, Ada configuration, and baseline Freshchat bot maturity. These are not automatic.

Freshchat Data Model: What You're Extracting

Before planning the migration, understand what Freshchat stores and what the API exposes.

Core objects:

Custom data:

• Conversation properties: Up to 50 custom fields per account (text, dropdown, number, decimal, date, checkbox, multiline text, multi-select dropdown).
• User properties: Permanent attributes attached to contacts (location, language, plan type).
• Bot variables: Scoped to a bot flow session — expire when the conversation resolves. There is no equivalent persistent session variable in Ada.

Freshchat webhook events useful during parallel-run periods:

Freshchat emits webhooks for conversation.created, message.create, conversation.assignment, and conversation.resolved. During a parallel-run window, these events can feed a real-time sync process that keeps your external archive current with new conversations. Configure webhook subscribers in the Freshchat admin console before cutover to avoid gaps.

For bulk transcript extraction, Freshchat offers raw reports via POST /reports/raw. The Chat-Transcript event can look back up to 15 months, but each request is limited to a 24-hour window — transcript backfills must be batched day by day. Freddy Self-service raw conversation and message exports are only available for 90 days, which matters if you need historical bot data before retiring flows. (developers.freshchat.com, support.freshworks.com)

The Freshchat REST API base URL is https://api.freshchat.com/v2. Authentication uses a Bearer API token generated from the Freshchat admin console. Pagination uses page and items_per_page query parameters, with next_link in the response for cursor-based traversal.

Freshchat Marketplace app inventory: Freshchat's marketplace includes integrations across CRMs (Salesforce, HubSpot), ticketing (Freshdesk, Zendesk, Jira), e-commerce (Shopify), and communication (Slack, Teams). Ada does not have a marketplace in the same sense — it exposes integrations through Actions (webhook-based). Every Freshchat Marketplace app must be evaluated individually: some have Ada Action equivalents, some require custom webhook middleware, and some (particularly native Freshworks suite integrations like Freshdesk ticket creation) have no direct Ada equivalent and must be rebuilt against target system APIs.

For a deeper look at extraction methods, see our guide on how to export data from Freshchat.

Ada Data Model: What You're Loading Into

Ada's API surface is organized around five main APIs:

Ada's default API rate limits are 10,000 requests/day, 100 requests/minute, and 10 requests/second. The Knowledge API has higher limits: 60,000 requests/day, 1,000/minute, and 200/second. (docs.ada.cx)

Ada webhook/event model: Ada's Data Export API provides read-only export of conversation and message data post-cutover. (Note that this API typically caps queries at 60-day ranges and retains only 12 months of history, a limitation we explore further in our Ada to Desk365 migration guide). This is the mechanism for feeding your external archive after Freshchat is decommissioned. There is no real-time Ada webhook push equivalent to Freshchat's message.create events — exports are pull-based. Build a scheduled export job to maintain archive continuity after cutover.

Key data constraints:

• Maximum knowledge articles: 50,000 by default. Higher limits available on eligible plans.
• Maximum article size: 100KB per article.
• Maximum request body: 10MB.
• Indexing latency: After a Knowledge API upsert, content typically starts indexing within ~30 seconds and becomes available to generative answers within about 5 minutes.
• End user auto-deletion: End users created through the API and not associated with a conversation within 24 hours are automatically deleted. Do not preload your entire Freshchat user base. (docs.ada.cx)
• Conversation metadata: Capped at 4KB, accepts only scalar values, and is storage-only — it does not set AI-readable metavariables. Use the End Users API when the AI agent needs data during the conversation. (docs.ada.cx)

Ada uses a single platform API token (v2) across all endpoints.

The Critical Constraint: No Historical Conversation Import

Ada's Conversations API is designed to create new, live conversations — not accept historical records. When you call POST /v2/conversations/, you start a real conversation that triggers Ada's AI agent. There is no way to insert a backdated Freshchat conversation with its original timestamps, agent assignments, and message threading into Ada as a read-only historical record. (docs.ada.cx)

On the custom-channel path, end-user messages are text only at launch — images and structured messages are not yet supported. This makes replaying old Freshchat transcripts that included buttons, text inputs, or media-rich bot steps impossible even as a workaround.

This means:

• Freshchat conversation history cannot live inside Ada. You need an external archive.
• Reporting continuity breaks. Ada's analytics start from zero on cutover day.
• CSAT data stays behind. Freshchat CSAT scores and conversation ratings have no import path in Ada.
• Post-cutover archiving requires a different mechanism. Ada's Data Export API (pull-based) must replace Freshchat's webhook-driven sync in your archive pipeline.

Compliance and Data Residency Considerations

Before extracting anything, address these:

GDPR deletion propagation: If you archive Freshchat conversations in a data warehouse, those records fall under your GDPR/CCPA obligations independently of Freshchat's deletion. Build a deletion propagation mechanism: when a subject deletion request arrives, it must reach both your Freshchat account (via the Freshchat contacts delete endpoint) and your external archive. Hardcode the freshchat_contact_id in your archive schema specifically to support this lookup.

Subject access requests: After cutover, subject access requests that span pre- and post-migration history require querying both your Freshchat archive and Ada's Data Export API. Document the data lineage before you decommission Freshchat.

Data residency: Freshchat and Ada may have different data residency options. Verify that your archive destination is compliant with applicable jurisdiction requirements before extracting and copying conversation data cross-region.

Retention schedule: Establish a documented retention period for the Freshchat archive before migration begins. Archiving indefinitely creates compliance risk. Establish deletion triggers aligned with your existing retention policy.

Data Mapping: Freshchat → Ada

What transfers directly

What requires significant transformation

What cannot be migrated

• Conversation history — No import endpoint. Archive externally.
• CSAT scores and ratings — No import path in Ada.
• Bot flow logic — Freddy dialog trees don't translate to Ada's generative model. Must be rebuilt.
• Conversation-scoped bot variables — Expire on resolution in Freshchat; no equivalent in Ada.
• Agent records — Ada doesn't have an "agent" object in the same sense. Human handoff is configured per-platform.
• Rich message parts (images, buttons, collections, input controls) — Freshchat's message model is richer than Ada's text-first custom-channel model. Archive or redesign.
• Freshchat widget customizations — Ada's Chat SDK uses its own configuration.
• Marketplace app integrations — Must be reconfigured or rebuilt using Ada's Actions (webhook-based).
• Reporting and analytics data — All historical agent performance reports, conversation metrics, and volume trends remain in Freshchat. Export before decommissioning.

Freddy bot flow migration taxonomy

Based on the structural patterns common in Freshchat Freddy bot deployments, flows fall into three categories:

Category A — Knowledge replacement (partial salvage): Flows that answer static questions (FAQs, policy explanations, hours/location). These typically convert cleanly to Ada Knowledge Articles. The dialog tree structure is discarded; only the terminal content (the answer) is preserved.

Category B — Conditional logic (redesign required): Flows that branch based on user input, account status, or external API responses. The branching logic has no direct Ada equivalent. Rebuild as Ada custom instructions that tell the AI agent how to reason through conditions, combined with Actions that fetch external data.

Category C — Process automation (full rebuild): Flows that execute multi-step processes (order cancellation, appointment booking, account changes). These require Ada Actions connected to backend systems, with custom instructions defining the process boundaries. This is the highest effort category — expect 3–8 hours per flow for analysis, Action development, testing, and instruction authoring.

The ratio across typical Freshchat deployments varies significantly by industry and bot maturity, but Category B and C flows combined usually represent the majority of migration hours regardless of their count relative to Category A.

Step-by-Step Migration Architecture

The right mental model: extract → archive → transform → load → rebuild → validate → cutover → monitor.

Step 1: Extract everything from Freshchat

Pull all data from the Freshchat v2 API into a staging store (database, S3, or local JSON files).

For object-level data (contacts, conversations, messages), use the REST API endpoints with pagination:

import requests
import time
 
BASE_URL = "https://api.freshchat.com/v2"
HEADERS = {
    "Authorization": "Bearer YOUR_FRESHCHAT_API_TOKEN",
    "Accept": "application/json"
}
 
def fetch_all_contacts():
    contacts = []
    page = 1
    while True:
        resp = requests.get(
            f"{BASE_URL}/contacts",
            headers=HEADERS,
            params={"items_per_page": 100, "page": page}
        )
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 60)))
            continue
        data = resp.json()
        contacts.extend(data.get("contacts", []))
        if not data.get("links", {}).get("next_link"):
            break
        page += 1
    return contacts

Repeat this pattern for conversations, messages (per conversation), agents, and groups. For messages, respect the items_per_page=50 ceiling.

For bulk transcript history, use Freshchat raw reports:

{
  "start": "2026-07-01T00:00:00.000Z",
  "end": "2026-07-01T23:59:59.000Z",
  "event": "Chat-Transcript",
  "format": "csv"
}

Run this one UTC day at a time, poll GET /v2/reports/raw/{id} until the status is COMPLETED, then download the returned extraction links. If you also used Freddy Self-service, export that data separately before cutover — raw bot message and conversation data is only available for 90 days.

Attachment warning: Freshchat message payloads include URLs for attachments. These are often signed S3 URLs that expire. Your extraction script must download the binary files and re-host them in your own storage bucket before the URLs expire — and before you decommission your Freshchat account.

Configure Freshchat webhooks for parallel-run coverage: Before extraction is complete, configure conversation.created and message.create webhook subscribers pointing to your archive pipeline. This ensures conversations created during the extraction and testing window are captured without requiring a second full extract.

Step 2: Archive conversations externally

Since Ada can't receive historical conversations, store them in a durable, queryable format:

• Data warehouse (BigQuery, Snowflake, Redshift) — Best for teams that need reporting continuity and plan to run BI queries against historical data.
• S3/GCS as JSON or Parquet — Best for compliance-only retention at lowest cost.
• Relational DB — Good for teams that want to build a custom search interface for support leads reviewing old transcripts.

Store conversations with their full message threads, CSAT data, conversation properties, and agent assignments. You will not get this data back from Ada.

Flatten nested JSON structures into relational tables (e.g., freshchat_conversations_archive and freshchat_messages_archive linked by conversation_id) for easier querying. Preserve raw message_parts JSON alongside flattened exports if rich bot UI details matter for auditing.

Archive schema minimum: Include conversation_id, contact_id, freshchat_contact_id (for deletion propagation), created_at, resolved_at, channel, assigned_group, assigned_agent, csat_score, conversation_properties (JSON), and the full message thread. The freshchat_contact_id field is essential for GDPR subject deletion propagation.

Post-cutover archive continuity: After Freshchat is decommissioned, switch the archive pipeline to Ada's Data Export API (GET /api/v2/export/conversations). This is a pull-based endpoint — build a scheduled job (daily or hourly depending on volume) to maintain conversation archive continuity in Ada's operational period.

Step 3: Mine intents from historical data

Your Freshchat transcripts contain the actual language your customers use. Extract the first user message from every conversation to build a query distribution:

def extract_initial_utterance(conversation_payload):
    for message in conversation_payload.get('messages', []):
        if message.get('message_type') == 'normal' and message.get('actor_type') == 'user':
            return message.get('message_parts')[0].get('text').get('content')
    return None

Aggregate these utterances, strip PII using a scrubbing library (e.g., presidio-analyzer), and cluster them by topic (k-means or topic modeling against embeddings works at scale). This clustering informs your Ada knowledge article structure and produces a baseline query distribution — a ranked list of what customers actually ask. Save this distribution: it is your pre-migration baseline for post-cutover validation.

Also extract the resolution path for each conversation (which bot flow or agent resolved it, and what the resolution was). Category A flows with high volume and clean resolutions are your highest-priority knowledge articles. Category C flows with high volume are your highest-risk rebuild items.

Step 4: Load knowledge into Ada

Freshchat FAQ articles, canned responses, and documented resolution procedures map to Ada Knowledge Articles.

1. Create a Knowledge Source via POST /v2/knowledge/sources/ — name it something like "Migrated from Freshchat".
2. Bulk upsert articles via POST /v2/knowledge/articles/ — each article needs a name (max 255 chars), body (max 100KB), and a source_id.
3. Apply tags if you need to control which articles are available to specific coaching configurations.

The Knowledge API's rate limits (1,000 requests/minute) mean a library of 2,000 articles loads in under 3 minutes of API time, though indexing latency adds ~5 minutes before articles are active in generative answers.

Formatting requirements:

• Ada's AI parses text to generate answers. Deeply nested HTML tables, complex inline CSS, or heavy reliance on images will degrade answer synthesis quality.
• Run a transformation script to strip unnecessary HTML tags and convert content into clean text or markdown before pushing.
• Ada documents a defined set of supported knowledge languages. Multilingual Freshchat estates need a language audit before import.
• Rewrite internal links pointing to other Freshchat articles to their new public URLs, or remove them if the articles will only live inside Ada.

Knowledge coverage validation (pre-cutover): After loading articles, test Ada's generative answers against your top-N queries from Step 3's baseline distribution. Use Ada's test console or the Conversations API with a test channel to submit real historical utterances and evaluate response quality. Define a threshold (e.g., "90% of top-50 query types must receive a substantive answer") before cutover. Document failed queries as knowledge gaps requiring additional articles.

Step 5: Create Ada end users just in time

Ada's End Users API supports create and update with an external_id, plus profile data and metadata. But end users created through the API and not associated with a conversation within 24 hours are automatically deleted. Do not bulk-load your Freshchat contacts. (docs.ada.cx)

Instead, create or update Ada end users when a session starts:

{
  "external_id": "ca03d5ea-9615-4069-8938-bc39e522a436",
  "profile": {
    "email": "alice@example.com",
    "first_name": "Alice",
    "last_name": "John",
    "metadata": {
      "freshchat_contact_id": "121",
      "plan_type": "enterprise"
    }
  }
}

If your Freshchat customer key is the UUID-style user.id, it usually fits Ada's 36-character external_id limit exactly. If your stable identifier is longer, hash it for external_id and store the original key in metadata. Freshchat's restore_id is for restoring conversation history across devices — it is not automatically the best long-term cross-system identifier. Use a stable customer identifier like user.id for Ada's external_id.

Store a mapping table of freshchat_contact_id → ada_external_id (and any intermediate hashes). This mapping is required for: reconciliation if Ada records need to be corrected, GDPR subject deletion propagation across both systems, and rollback if Ada deployment fails during the transition window.

Step 6: Rebuild bot logic as Ada knowledge and instructions

This step cannot be automated and is the primary cost driver in most migrations.

Using the taxonomy from the data mapping section:

Category A flows (knowledge replacement):

• Extract the terminal answer content from each flow branch.
• Write a Knowledge Article per distinct topic. Aim for one clear question and one clear answer per article rather than omnibus FAQ documents — Ada's retrieval performs better on focused articles.
• No action required beyond article creation.

Category B flows (conditional logic):

• Map conditions to Ada custom instructions: "If the user asks about X and mentions Y, respond with Z."
• Where conditions depend on external data (account status, order status), build an Ada Action that fetches the data, then write instructions for how the AI agent uses that data.
• Test each condition branch explicitly in the Ada test console.

Category C flows (process automation):

• Design the Action endpoints first — what data does the AI agent need, what does it send, what does it receive?
• Two constraints that affect Action design: Ada Actions process only the data returned in a single response page (no auto-pagination), and a 429 or other error response is treated as a failed Action rather than retried automatically. If your Freshchat bot depended on paginated APIs, async callbacks, or browser-side JS behavior, you need middleware or reworked endpoints before the Ada rebuild is production-safe. (docs.ada.cx)
• Write custom instructions after Actions are validated — instructions reference Action outputs.

Effort benchmarks: Category A flows: 30–60 minutes per flow (content extraction and article authoring). Category B flows: 2–4 hours per flow (instruction design, Action build if needed, branch testing). Category C flows: 4–8 hours per flow (Action development, middleware if required, end-to-end process testing). These estimates assume the engineer is familiar with both the source flow logic and Ada's instruction model.

Step 7: Configure handoffs and routing

If Freshchat routes unanswered conversations to human agents via groups and IntelliAssign, configure the equivalent in Ada:

• Set up the target handoff platform (Zendesk, Salesforce, Freshdesk, or a custom handoff via the Conversations API).
• Configure Ada's handoff rules in the dashboard.
• Test escalation paths end-to-end before cutover.

Ada's handoff management allows up to five active handoffs at a time. (docs.ada.cx)

Ada's public docs list handoff guides for Zendesk, Salesforce, Amazon Connect, ServiceNow, Genesys, Gorgias, Help Scout, Kustomer, Twilio Flex, and Gladly. A dedicated Freshchat handoff guide was not present in the public docs as of August 2026. If the intended architecture is "Ada for automation, Freshchat for human escalation," verify this integration path exists and test it before rebuilding bot logic — discovering it doesn't work after a full rebuild is a significant setback.

Step 8: Validate before cutover

Validation is a distinct step, not a 24-hour monitoring window after go-live. Define pass/fail criteria before cutover:

Knowledge coverage test: Submit your top-50 historical query types (from Step 3's baseline distribution) against Ada using a test channel. Define a minimum pass rate (e.g., 90% receive substantive answers, 0% produce harmful or incorrect responses). Fail items become knowledge gaps requiring additional articles before cutover is approved.

Action integration test: Execute each Ada Action against production endpoints (or staging equivalents). Verify response handling for success, empty response, 4xx, and 5xx cases. Document which failure modes result in graceful AI agent fallback vs. conversation failure.

Handoff test: Trigger handoff conditions deliberately and verify the full escalation path — from Ada conversation to human agent queue — with correct context passing.

Escalation threshold baseline: Record Ada's fallback rate (conversations escalated to human or ended without resolution) during test traffic. This is your day-one baseline. A significant increase post-cutover is the primary signal of knowledge gaps.

Go/no-go criteria: Define explicit numeric thresholds before the cutover window. If they are not met, cutover does not proceed.

Step 9: Cutover

1. Freeze Freshchat bot and knowledge changes 48 hours before cutover.
2. Run a final data sync to capture any new contacts and knowledge articles created during testing.
3. Swap the widget — deploy Ada's Chat SDK embed while removing the Freshchat JS snippet.
4. Monitor Ada's Conversations View for the first 24–48 hours. Compare fallback rate against your pre-cutover baseline from Step 8. Watch for unexpected escalation spikes, missing knowledge, and broken actions.
5. Keep Freshchat in read-only mode for 30–60 days. Customers with open browser tabs may still attempt replies on the old widget. Agents should monitor and close legacy threads while all new traffic routes to Ada.

Rollback procedure:

If the post-cutover fallback rate exceeds your defined threshold, or if a critical Action failure is discovered:

1. Re-enable the Freshchat widget embed and disable the Ada Chat SDK embed. DNS and CDN cache TTLs determine how quickly this propagates — pre-stage the rollback configuration so it is a one-command deploy, not a manual edit under pressure.
2. Route new traffic back to Freshchat by restoring the original JavaScript snippet. For WhatsApp and social channels with BSP routing, rollback requires contacting the BSP — pre-arrange a rollback contact and SLA before cutover.
3. Set Freshchat bot flows back to active.
4. Preserve all Ada configuration (articles, instructions, Actions) — do not delete. Diagnose the failure against the go/no-go criteria, address gaps, and re-validate before attempting cutover again.
5. Notify affected teams (support, product, engineering) with a defined incident timeline and root cause.

The 30–60 day Freshchat read-only window serves double duty: customer session continuity and rollback availability. Do not decommission Freshchat until that window closes and post-cutover metrics are stable against baseline.

WhatsApp channel rollback specifics: Switching from Freshchat to Ada for WhatsApp Business API means re-associating your WhatsApp Business Account with Ada's infrastructure, coordinated through your BSP. Rollback reverses this association. Pre-arrange rollback procedures with your BSP — this is not a self-serve operation and has coordination lead time. Expect potential downtime on the WhatsApp channel during both forward migration and rollback.

Timeline and Effort Estimates

The bulk of engineer-hours goes to bot flow analysis and rebuild — not data extraction or loading. Extraction is scriptable in 1–3 days depending on volume. Loading knowledge articles takes hours at Ada's API rate limits. Bot flow redesign (Categories B and C) is the primary cost driver and scales with flow count and complexity, not contact or conversation volume.

Validation (Step 8) is often under-budgeted. Plan for at least one full iteration of testing → gap identification → article/instruction updates → re-testing before cutover is approved.

Edge Cases and Gotchas

Multi-brand setups: If you use Freshchat's siteId to separate users across multiple websites, each site creates separate user pools. Decide whether these merge into one Ada instance or map to separate Ada bots before extraction begins.

Custom modules: Freshchat allows up to 10 custom modules for customer data management. These have no direct equivalent in Ada. Map the data to Ada end-user metadata (flat key-value pairs) or maintain it in an external system that Ada queries via Actions.

Reporting data: All analytics, agent performance reports, and conversation metrics stay in Freshchat. Export any reports you need before decommissioning. Historical dashboard views are lost when the account is decommissioned — export raw datasets via Freshchat's Reporting APIs before cutover.

Rich bot UI does not survive the move: Freshchat message parts (images, buttons, collections, input controls) are richer than Ada's current custom-channel end-user message model. Plan for redesign, not replay.

Conversation metadata is not routing data: Do not assume that importing user fields into Ada conversation metadata makes them available for routing or personalization logic. Conversation metadata is storage-only. Use the End Users API when the AI Agent needs data during a conversation.

Ada Actions do not retry on errors: A 429 or 5xx response from an external API called by an Ada Action is treated as a failed Action, not retried. If your backend systems have variable latency or rate limits, implement retry logic in a middleware layer between Ada and the target API.

Signed attachment URLs expire: Freshchat attachment URLs in message payloads are time-limited. Download and re-host all attachments during extraction — do not rely on Freshchat URLs surviving in your archive.

When DIY Extraction Is Viable vs. When It's Not

DIY extraction and loading is viable when:

• You have fewer than 5,000 contacts and under 100 knowledge articles.
• Your Freshchat setup has no bot flows, or only Category A (FAQ-type) flows.
• You have an engineer available for 1–2 weeks who understands REST APIs and both data models.
• You don't need conversation history preserved (or you already archive it elsewhere).
• Your compliance requirements are straightforward (single region, no complex deletion propagation).

Specialist help is worth evaluating when:

• You have complex Category B or C Freddy bot flows that need re-architected as Ada knowledge, instructions, and Actions.
• Your Freshchat instance uses extensive conversation properties, custom modules, or API-driven bot logic.
• You're running multi-brand or multi-region setups.
• You need zero-downtime cutover with parallel running during transition.
• You have WhatsApp channel continuity requirements involving BSP coordination.
• Your compliance obligations (GDPR deletion propagation, data residency) require a documented migration audit trail.