Desk365 to LiveChat Migration: A Technical Guide

Desk365 to LiveChat Migration: A Technical Guide

Migrating from Desk365 to LiveChat is not a simple data transfer — it is an architectural shift. Desk365 is built to operate inside the Microsoft 365 ecosystem, relying on Azure Active Directory for identity and Microsoft Teams for agent workflows. LiveChat is an independent, real-time engagement platform with its own identity system. If you are executing this migration, you are likely moving from a ticket-first internal helpdesk model toward a customer-facing, chat-first support model.

This guide covers how to extract your data from the Microsoft ecosystem, transform it for the LiveChat/HelpDesk data model, and execute a zero-downtime cutover.

What This Migration Actually Involves

Desk365 is a cloud-based helpdesk built for Microsoft 365. Its data model revolves around tickets with full conversation threads — replies, internal notes, attachments — plus contacts, companies, custom fields (using a cf_ prefix in API v3), categories, subcategories, groups, SLA policies, knowledge base articles, and asset management.

LiveChat handles real-time conversations. Its hierarchy is Chats → Threads → Events. For asynchronous ticket-based support, LiveChat now relies on HelpDesk, a separate product by Text (LiveChat's parent company). The native Tickets feature was sunset across all plans by January 31, 2025.

This means your migration requires a split-target architecture:

1. HelpDesk — For all ticket-based data: emails, web form submissions, Teams-originated tickets, and their full conversation threads. This is where 95%+ of your Desk365 data lands.
2. LiveChat — For deploying the new real-time chat widget and configuring forward-looking chat operations. Since Desk365 has no native live chat, the LiveChat leg is typically pure configuration, not data migration.

The core data-model challenge is similar to a Zendesk to LiveChat migration: Desk365 organizes conversations as replies and notes on tickets (each with an author, body, timestamp, and public/private visibility). HelpDesk organizes conversations as events within tickets (each with a type, date, and payload). A direct field-copy will produce malformed records.

API references used in this guide:

• Desk365 API v3 — per-subdomain docs at https://<yoursubdomain>.desk365.io/apis/api-docs.html
• HelpDesk API v1 — imported tickets endpoint requires access request via support@helpdesk.com
• LiveChat Agent Chat API v3.5

Why Teams Move from Desk365 to LiveChat

This migration is typically driven by a shift in support philosophy:

• Moving from ticket-first to chat-first support. Teams that adopted Desk365 for structured ticket management now want to meet customers in real-time on their website or in-app.
• Leaving the Microsoft 365 ecosystem. Desk365 connects deeply with Microsoft 365, Azure, and Power Automate. Organizations moving away from Teams as their primary collaboration tool lose much of Desk365's differentiation.
• Consolidation under the Text platform. Teams already using LiveChat for sales chat want to unify support under LiveChat + HelpDesk instead of running Desk365 separately.

Data Model Mapping: Desk365 → HelpDesk

This is where most migrations break. The two platforms don't share a data model, and a naive field-to-field copy will produce broken tickets.

What Doesn't Migrate

Several Desk365 capabilities have no import path in HelpDesk:

• Automation rules, SLA policies, and triggers — configuration, not data. Rebuild from scratch in HelpDesk.
• Knowledge base articles — Desk365's KB has its own API endpoint for retrieval, but HelpDesk doesn't have a KB import API. Recreate manually or migrate to a standalone knowledge base tool.
• Asset management data — Desk365 supports hardware and software asset tracking. HelpDesk has no asset module.
• Approval workflows — Desk365 supports sequential and non-sequential approval workflows on tickets. No equivalent exists in HelpDesk.
• Microsoft Teams integration context — Tickets created via the Desk365 Support Bot in Teams lose their Teams-specific metadata and conversation context.
• Time entries — Desk365 exports time entries via a separate API surface. HelpDesk's import payload has no time-entry object. Preserve this data in reporting exports or summarized custom fields.

Extraction: Getting Data Out of Desk365

You have two extraction paths. Only one works for a real migration.

CSV Export (Metadata Only)

Desk365's CSV export is view-based and delivered by email. It contains ticket metadata (subject, status, priority, custom fields) but not full conversation threads — no replies, notes, or attachments. You also need to export both "All Tickets" and "Archived Tickets" separately for complete coverage. The CSV is useful for audit snapshots and record-count verification, not as a migration source.

Desk365 API v3 (Full Extraction) — Required

The Desk365 REST API v3 is the only path to full ticket data. It is subdomain-based, uses an API key in the Authorization header, and supports 30, 50, or 100 tickets per call via the ticket_count parameter, with a maximum of 10,000 tickets per hour.

Key endpoints:

# List tickets (paginated, max 100 per call)
GET https://<subdomain>.desk365.io/apis/v3/tickets?ticket_count=100&page=1&description=1
 
# Get single ticket with conversations
GET https://<subdomain>.desk365.io/apis/v3/tickets/<ticket_id>?include_conversations=1
 
# List contacts
GET https://<subdomain>.desk365.io/apis/v3/contacts
 
# Knowledge base articles (if migrating KB separately)
GET https://<subdomain>.desk365.io/apis/v3/kb/articles

Critical API behaviors:

• Description is excluded by default. The "Get all tickets" operation does not include the ticket description unless you set description=1. Miss this and you lose every original ticket body.
• Conversations endpoint excludes the description. /v3/tickets/conversations returns replies and notes but not the original ticket description. A complete extract must combine /v3/tickets (with description=1) with /v3/tickets/conversations.
• Custom fields use a cf_ prefix. API v3 standardized custom field keys (e.g., cf_department, cf_employee_id).
• Rate limits are plan-specific. The documented ceiling is 10,000 tickets per hour. Test your actual plan's limits with a small batch before running full extraction — observed throughput with 429 backoffs and per-ticket conversation requests typically runs at 30–50% of theoretical maximum.

Pagination Loop for Desk365 API

The Desk365 API uses page-based pagination. Increment page until the response returns fewer tickets than ticket_count (or an empty array), which signals the final page.

import time
import requests
 
def extract_all_tickets(subdomain, api_key):
    tickets = []
    page = 1
    page_size = 100
    headers = {"Authorization": api_key}
    
    while True:
        url = (
            f"https://{subdomain}.desk365.io/apis/v3/tickets"
            f"?ticket_count={page_size}&page={page}&description=1"
        )
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            # Desk365 returns 429 on rate limit; back off 60 seconds
            print(f"Rate limited on page {page}. Waiting 60s...")
            time.sleep(60)
            continue
        
        response.raise_for_status()
        batch = response.json().get("tickets", [])
        tickets.extend(batch)
        
        if len(batch) < page_size:
            break  # Final page reached
        
        page += 1
        time.sleep(0.5)  # Conservative throttle to stay under hourly limit
    
    return tickets

Pre-Migration Identity Mapping

The most common failure point in a Desk365 migration is identity resolution. Desk365 uses Azure AD Object IDs and User Principal Names (UPNs) as primary identifiers. HelpDesk uses standard email addresses.

Before transforming tickets, build an identity map. Extract all agents and contacts from Desk365 via /apis/v3/contacts and map each Desk365 user_id to the corresponding HelpDesk agent_id or requester_email.

{
  "id": "d365_usr_8f9a2b",
  "name": "Jane Doe",
  "email": "jane.doe@company.com",
  "azure_ad_id": "a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d6",
  "role": "agent"
}

Store this mapping in a local database or key-value store. During transformation, every ticket creator, assignee, and note author must be swapped for the corresponding HelpDesk email or ID. If an agent has left the company and is not provisioned in HelpDesk, fall back to a generic "Legacy Support" agent ID to prevent import failures from unmapped authors.

Handle duplicate contacts early. Desk365 may contain duplicate contacts — same email, different records. HelpDesk uses email as the primary identifier. Deduplicate before migration by merging contact records in Desk365 or keying on email in the transform layer. Desk365 also supports multiple secondary email addresses per contact, while HelpDesk imported tickets require a single requester email. Establish a canonical-email rule and preserve secondary emails in custom fields or migration notes.

Transform: Reshaping Desk365 Data for HelpDesk

The transform layer is the most engineering-intensive phase.

Conversation Thread → Event Array

Desk365 returns a conversation thread as an ordered array of messages, each with a type (description, contact reply, agent reply, private note, public note), author, HTML body, timestamp, and attachment references.

HelpDesk expects an array of events. The first event must be a message. All events must be chronological and set in the past. Agent-authored events require agentID, agentName, and isPrivate.

def transform_conversation(desk365_ticket, desk365_conversations, identity_map):
    events = []
    
    # First event: the original ticket description (mandatory message)
    events.append({
        "date": desk365_ticket["created_at"],
        "type": "message",
        "message": {
            "text": desk365_ticket["description"]
        }
    })
    
    for msg in desk365_conversations:
        if msg["type"] == "private_note":
            agent = identity_map.get(msg["author_id"])
            events.append({
                "date": msg["created_at"],
                "type": "message",
                "agentID": agent["helpdesk_id"],
                "agentName": agent["name"],
                "isPrivate": True,
                "message": {"text": msg["body"]}
            })
        elif msg["type"] in ["contact_reply"]:
            events.append({
                "date": msg["created_at"],
                "type": "message",
                "message": {"text": msg["body"]}
            })
        elif msg["type"] in ["agent_reply", "public_note"]:
            agent = identity_map.get(msg["author_id"])
            events.append({
                "date": msg["created_at"],
                "type": "message",
                "agentID": agent["helpdesk_id"],
                "agentName": agent["name"],
                "isPrivate": False,
                "message": {"text": msg["body"]}
            })
    
    return events

Status Mapping

Desk365 uses configurable statuses. HelpDesk uses a fixed set. Map carefully:

HelpDesk's import API also accepts status events — the last status event becomes the final state. Custom Desk365 statuses that don't map cleanly should be preserved in a dedicated custom field for reporting.

Note: In HelpDesk, requester replies automatically reopen Pending and Solved tickets to Open. Pending, Solved, and Closed tickets auto-archive after 60 days of inactivity. This differs from Desk365's behavior — brief agents before go-live.

Priority Mapping

Desk365 uses Low, Medium, High, and Urgent. HelpDesk's imported ticket priorities map to numeric values in the import payload: -10 (low), 0 (medium), 10 (high), 20 (urgent). Verify these values against the HelpDesk API v1 schema when you receive API access, as numeric priority representations may be updated in future API revisions.

Categories → Tags

Desk365 organizes tickets into categories and subcategories — a two-level hierarchy. HelpDesk uses a flat tag structure. The recommended approach:

Desk365: Category = "Billing", Subcategory = "Refunds"
HelpDesk: Tags = ["billing", "billing:refunds"]

This encodes the hierarchy as searchable, filterable tags without data loss. Pre-create all tags in HelpDesk before import; the API does not auto-create tags on ticket load.

Custom Field Handling

Desk365 supports multiple custom field types: text, dropdown, checkbox, date, number, nested sections, and read-only fields. Before loading, pre-create matching custom fields in HelpDesk with compatible types. HelpDesk custom fields don't support nested sections or conditional visibility — flatten any dependent field logic.

Character limits to enforce during transform:

• HelpDesk singleLine custom fields: 120 characters maximum
• HelpDesk multiLine custom fields: 1,000 characters maximum

Long Desk365 metadata values must be truncated or restructured before load. Truncate at a word boundary and append [truncated] so agents know the record was modified.

Handling Attachments

Attachments are the single biggest variable in migration time. A 50K-ticket migration with an average of two attachments per ticket can easily double total extraction and load time.

Desk365 stores attachments behind authenticated URLs. These URLs may expire or require the API key for access. HelpDesk does not accept external authenticated URLs — you must download and re-upload.

HelpDesk uses a transaction-based flow for attachment imports:

1. Create an import transaction via the HelpDesk API.
2. Upload attachments to the transaction.
3. Create the imported ticket referencing that transactionID.

All uploaded attachments in a transaction must be used. Transactions expire after 24 hours. Message and attachment events are grouped when their dates match. LiveChat enforces a 10MB per-file size limit and rejects executable file types — apply these filters during the download phase before attempting upload.

Loading Data into HelpDesk

As noted in our Thena to LiveChat migration guide, the HelpDesk imported tickets endpoint (POST /v1/importedTickets) is not listed in the standard public API reference — request access by emailing support@helpdesk.com before starting your migration. Confirm the endpoint URL and authentication requirements at that time, as access arrangements may change.

Key characteristics of the endpoint based on current behavior:

• Authentication: Basic auth (account ID + token) or OAuth 2 Bearer token. Base URL: https://api.helpdesk.com.
• Import speed: Approximately 10,000 tickets per hour.
• Pagination on reads: Cursor-based. Each response includes a next_cursor field; iterate until the cursor is empty.
• User-Agent header required. Requests missing it may be blocked by intermediary services.

Common Import Errors and Causes

The HelpDesk import API returns standard HTTP status codes. The most frequent failures during migration:

Loading Order

1. Create agents and teams in HelpDesk matching your Desk365 groups and agent list.
2. Create custom fields matching Desk365's cf_* fields.
3. Create all tags corresponding to your category/subcategory hierarchy.
4. Import closed/resolved tickets first — these are read-only and safe to load in bulk.
5. Import open/pending tickets last — these appear in agent queues, so coordinate timing with your support team.
6. Validate record counts and spot-check conversation threads.

Preserving Source Ticket IDs

HelpDesk generates its own ticket IDs on import. Store a mapping table (Desk365 ticket number → HelpDesk ticket ID) during loading. You need this for post-migration validation, cross-reference lookups, and any external systems that reference Desk365 ticket IDs. Preserve the original Desk365 ticket number in a dedicated HelpDesk custom field so agents can cross-check records during QA.

Example HelpDesk Import Payload

{
  "subject": "Printer not syncing in Teams",
  "requester": {
    "email": "ava.morris@company.com",
    "name": "Ava Morris"
  },
  "priority": 10,
  "customFields": {
    "desk365-ticket-number": "HD-10452"
  },
  "events": [
    {
      "date": "2024-03-01T09:15:00Z",
      "type": "message",
      "message": {
        "text": "Original Desk365 ticket description"
      }
    },
    {
      "date": "2024-03-01T09:18:00Z",
      "type": "message",
      "agentID": "42e113f9-9353-4e89-9f68-69b92f423b0c",
      "agentName": "Maya Chen",
      "isPrivate": true,
      "message": {
        "text": "Imported private note from Desk365"
      }
    }
  ]
}

Rollback Procedure

Before starting any load run, confirm with HelpDesk support whether your account has bulk-delete access for imported tickets. Currently, there is no public bulk-delete endpoint in HelpDesk API v1. If a load run produces malformed records at scale, your options are:

1. Pre-production trial environment: Request a HelpDesk trial account (separate from production) and run all dry-run imports there before touching production. This is the only safe rollback strategy.
2. Partial load cleanup: For small batches with errors, delete individual tickets via DELETE /v1/tickets/{id} in the HelpDesk API.
3. Fallback to Desk365: Keep Desk365 fully active until the HelpDesk import is validated. Do not decommission Desk365 until you have confirmed record counts and spot-checked conversation fidelity.

There is no undo for a completed bulk import. Always run a 100–500 ticket dry run in a trial environment before loading production data.

Zero-Downtime Cutover Strategy

A big-bang migration — shut down Desk365 on Friday, turn on LiveChat/HelpDesk on Monday — is high risk. Use a staged approach.

Step 1: Build the Target Environment

Create LiveChat groups and routing rules. Create HelpDesk teams, custom fields, tags, statuses, and canned responses before importing anything. If you skip this, imported data lands in generic buckets and you spend cutover week cleaning structure instead of validating records.

Step 2: Load Historical Data

Select a cutoff date (e.g., three days before go-live). Export and migrate all closed and resolved tickets from Desk365 up to this date. This moves the bulk of your data volume without impacting active operations. HelpDesk uses the first message event date as the ticket creation date, so chronology stays clean.

Step 3: Delta Sync

Right before cutover, re-pull any tickets created or updated since the baseline. Transform and load this final batch into HelpDesk. Key the delta sync on source ticket ID (stored in a HelpDesk custom field) — matching by subject or requester email produces false duplicates on any ticket where the subject or requester changed.

Step 4: Switch Inbound Channels

Only after historical and delta imports validate: repoint website chat to LiveChat, switch email routing from Desk365 to HelpDesk, deploy the LiveChat widget, and disable Desk365 inbound channels.

Email threading continuity: When HelpDesk takes over email routing, existing reply-to headers referencing Desk365's mail domain will no longer route correctly. For any open tickets migrated to HelpDesk, send a brief re-introduction email from HelpDesk's domain so subsequent customer replies thread correctly in HelpDesk. Failing to do this causes customer replies to land in Desk365 (if still active) or bounce entirely.

Step 5: Handle Open Tickets

For tickets that were open in Desk365 at cutover, you have two options:

1. Work them down in Desk365. Allow agents to log into Desk365 for one final week to close existing open tickets. Migrate them to HelpDesk once closed.
2. Migrate them as open. Push them into HelpDesk as open tickets, ensuring the current assignee receives them in their new queue.

Option 1 is safer. Migrating active, in-progress tickets often disrupts ongoing customer conversations and breaks email threading continuity.

Step 6: Decommission Desk365

Keep Desk365 active in read-only mode for 30–90 days as a reference archive. This gives agents a fallback for edge cases the migration may have missed. Do not cancel the Desk365 subscription until you have confirmed no external systems (webhooks, Power Automate flows, Azure Logic Apps) are still calling Desk365 endpoints.

Post-Migration QA Checklist

Run these checks before turning Desk365 off:

• Descriptions present? Confirm the first customer message exists on every sampled imported ticket. This is the most common extraction bug — caused by missing description=1 on the list endpoint.
• Archived history present? Sample records from Desk365 Archived Tickets, not just active views. CSV and API views default to active tickets only.
• Private notes private? Verify internal Desk365 notes arrived as isPrivate agent events and are not visible to requesters.
• Attachments complete? Spot-check large files. Attachment transactions expire after 24 hours. LiveChat rejects files over 10MB or executable types.
• Custom field values correct? Verify cf_* fields mapped to the right HelpDesk custom fields with expected values and within character limits.
• Record counts match? Compare totals by status, priority, and assignee between Desk365 and HelpDesk exports.
• Email threading working? Send a test reply to a migrated open ticket from an external email address and confirm it routes to HelpDesk correctly.
• Reopened-ticket behavior understood? In HelpDesk, requester replies reopen Pending and Solved tickets to Open. Pending, Solved, and Closed tickets auto-archive after 60 days of inactivity. Confirm agents know this differs from Desk365's behavior.
• Webhooks and integrations redirected? Confirm all Desk365 outbound webhook destinations have been updated or disabled.
• No unmapped agent IDs? Query your identity map for any agents that fell back to the "Legacy Support" placeholder — review whether those tickets need reassignment.

Edge Cases and Failure Modes

Microsoft Teams Channel History

Tickets resolved entirely within a Microsoft Teams channel thread using the Desk365 integration carry Teams-specific metadata (channel name, message ID, thread context). That raw channel history either does not appear in the Desk365 API payload or is appended as a single block of text. The native Teams UI context is lost permanently — this is not recoverable through any API call after migration.

HTML Content Rendering

Desk365 stores ticket descriptions and replies in HTML format. HelpDesk also accepts HTML, but rendering differences exist for complex markup. Test a sample batch of 20–50 tickets with tables, inline images, embedded links, and multi-level lists before running the full load. Identify any systematic rendering failures and handle them in the transform layer before bulk processing.

PHI/PII Fields

Desk365 enables secure handling of sensitive data through dedicated PHI/PII fields with role-based permissions. HelpDesk does not have a dedicated PHI/PII field type. Before migrating that data, evaluate whether standard HelpDesk custom fields with appropriate access controls meet your compliance requirements (HIPAA, GDPR, or equivalent). Consult your legal or compliance team — this is not a technical decision.

LiveChat Limitations for Historical Data

If you try to load Desk365 history into LiveChat chats instead of HelpDesk tickets, expect significant fidelity loss. start_chat allows only up to four additional agents and one customer in chat.users, and initial events are visible to all users in the chat. That makes LiveChat a poor fidelity target for long tickets with many historical agents or private notes. If you need a small subset of conversations accessible in LiveChat, create them as inactive threads and treat them as reference transcripts, not reconstructions.

Migration Timeline Estimates

These estimates include development, testing, dry runs on a trial HelpDesk environment, and validation — not just raw data transfer time. The largest time variable is attachment volume: migrations with high attachment-to-ticket ratios (>3 attachments/ticket average) should add 30–50% to the large and enterprise estimates.

Making the Switch Work

The Desk365 to LiveChat + HelpDesk migration is a platform paradigm shift — from a Microsoft 365-native helpdesk to a chat-first engagement platform with a companion ticketing product. The technical difficulty concentrates in the transform layer: reshaping conversation threads into events, flattening category hierarchies to tags, resolving Azure AD identities to email addresses, managing the attachment pipeline, and handling email threading continuity after cutover.

The strategic decision matters more than the technical execution. If your team relies on SLA enforcement, asset tracking, and approval workflows, migrating away from Desk365 means rebuilding or abandoning those capabilities. Verify that the move to a chat-first model is driven by actual customer demand before committing to the migration.

DIY is viable if you have fewer than 5,000 tickets, minimal attachments, no PHI/PII fields, and an engineer who can dedicate 40–80 hours. A managed migration makes sense when you have 10,000+ tickets with attachments, PHI/PII compliance requirements, a hard zero-downtime requirement, or active downstream integrations that cannot tolerate a cutover gap.

Whatever path you take, run a sample migration first against a HelpDesk trial environment. Load 100–500 tickets — including complex email threads, inline images, Teams-generated tickets, archived records, and private notes — and validate the output before running the full dataset. That is where most hidden mapping problems surface.