LiveChat to Tidio Migration: The Technical Guide

LiveChat to Tidio Migration: The Technical Guide

Moving from LiveChat to Tidio means trading a mature, integration-heavy live chat platform for an all-in-one customer service tool with built-in AI (Lyro) and multichannel support at a lower price point. The migration is straightforward in concept — extract chats and customers from LiveChat's API, transform them to Tidio's data model, and load via Tidio's OpenAPI — but the details make it demanding: differing object models, tight rate limits, several data types that can't be migrated programmatically, and no rollback tooling if something goes wrong mid-run.

Chat data is particularly hard to move. Unlike email-based ticketing systems where messages have clear headers and threading, chat platforms treat conversations as continuous event streams. LiveChat relies on a highly structured, event-driven model where a chat contains multiple threads, each containing an array of events — messages, system notes, file uploads, rich interactive cards, form fills. Tidio operates on a more streamlined model centered on the Contact object, with conversations tied to contacts through a merged live-chat-plus-ticketing interface (Tidio has two distinct modules: a live chat inbox for real-time conversations and a Help Desk ticketing system — imported historical conversations land in Help Desk, not the live chat inbox). Bridging these two models requires strict payload transformation and hard decisions about what to preserve.

This guide covers the full technical methodology based on the LiveChat Agent Chat API v3.5 and the Tidio OpenAPI.

Migration Object Mapping: LiveChat → Tidio

Before writing any code, understand how LiveChat's data model translates to Tidio's:

LiveChat Event Type Taxonomy

LiveChat events arrays contain several distinct types. Each requires a different handling strategy during transformation:

Example flattening for rich_message:

[System - Product Card] "Blue Widget Pro" — https://shop.example.com/blue-widget — $49.99

Example flattening for system_message:

[System - 2024-03-15 14:38 UTC] Chat transferred to Billing team

Pre-Migration Checklist

Walk through this list before touching any code:

• Audit LiveChat data volume: Count archived chats, customers, and agents. LiveChat's in-app export is limited to 100,000 records — larger datasets require the API.
• Confirm Tidio plan level: Tidio's OpenAPI requires a Plus plan or above. Free through Growth tiers only get access to the Products endpoint. Rate limits differ by plan (Plus: 60 req/min; Premium: 120 req/min).
• Generate LiveChat credentials: Create a Personal Access Token (PAT) in the LiveChat Developer Console under Tools → Personal Access Tokens. For list_archives you need the chats--all:ro scope. For Configuration API (agents, groups) you need agents--all:ro and groups--all:ro scopes. PATs work for both the Agent Chat API and Configuration API but require different scope sets.
• Generate Tidio API credentials: Get your X-Tidio-Openapi-Client-Id and X-Tidio-Openapi-Client-Secret from Tidio's admin panel under Settings → OpenAPI.
• Create Operators in Tidio: Agents cannot be created via the Tidio API. Manually create each operator account before importing tickets. Ensure email addresses match the ones used in LiveChat — this is critical for attribution.
• Create Departments in Tidio: If you use LiveChat Groups to route chats, recreate those as Departments in Tidio first. Record the resulting UUIDs.
• Define Custom Properties in Tidio: Go to Settings → Contact Properties and create any fields you want to preserve from LiveChat's pre-chat survey or custom variables. If you attempt to pass a custom property via the API that doesn't exist in the schema, Tidio will silently drop the data with no error returned.
• Map Tags: Inventory your LiveChat tags and recreate them in Tidio's Help Desk settings. Use GET /tickets/tags to retrieve IDs, then include tag_ids in ticket creation payloads.
• Retrieve custom field IDs: Use GET /tickets/custom-fields to retrieve IDs for any ticket-level custom fields you plan to populate.
• Plan rollback procedure: Decide how you will undo a partial import before you start. See the Rollback Strategy section.
• Check GDPR/DPA coverage: If you handle EU customer data, verify that your Data Processing Agreements cover the transfer between platforms.

Step 1: Extract Data from LiveChat

LiveChat separates its APIs into the Configuration API (for agents, groups, and settings) and the Agent Chat API (for retrieving conversation archives). Both use the same PAT for authentication but require different permission scopes.

Extracting Chat Archives

The primary extraction endpoint is list_archives on the Agent Chat API v3.5:

curl -X POST 'https://api.livechatinc.com/v3.5/agent/action/list_archives' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_PAT_TOKEN>' \
  -d '{
    "filters": {
      "from": "2020-01-01T00:00:00Z",
      "to": "2026-08-01T00:00:00Z"
    },
    "limit": 100,
    "sort_order": "asc"
  }'

Key details:

• Pagination: Results use cursor-based pagination via page_id. Each response includes next_page_id — pass it in subsequent requests.
• Limit: Between 1 and 100 chats per page.
• Sort order: Use asc (oldest first) for chronological import consistency.
• Data returned: Each chat includes users (customer + agents), threads containing events (messages, filled forms, system messages), properties, tags, and access (group IDs).

Because chat histories can be massive, write raw JSON payloads to local disk or a staging database before attempting any transformation:

import requests
import json
import time
 
LIVECHAT_PAT = "your_personal_access_token"
HEADERS = {
    "Authorization": f"Bearer {LIVECHAT_PAT}",
    "Content-Type": "application/json"
}
 
def fetch_livechat_archives():
    url = "https://api.livechatinc.com/v3.5/agent/action/list_archives"
    payload = {
        "filters": {
            "from": "2023-01-01T00:00:00Z",
            "to": "2024-01-01T00:00:00Z"
        },
        "sort_order": "asc",
        "limit": 100
    }
 
    page = 0
    has_more = True
    while has_more:
        response = requests.post(url, headers=HEADERS, json=payload)
 
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 5))
            time.sleep(retry_after)
            continue
 
        data = response.json()
 
        with open(f"archive_page_{page}.json", "w") as f:
            json.dump(data.get('chats', []), f)
 
        if data.get('next_page_id'):
            payload['page_id'] = data['next_page_id']
            page += 1
        else:
            has_more = False

Extracting Agents and Groups

Use the Configuration API with agent and group scopes:

# List agents (requires agents--all:ro scope)
curl -X POST 'https://api.livechatinc.com/v3.5/configuration/action/list_agents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_PAT_TOKEN>' \
  -d '{}'
 
# List groups (requires groups--all:ro scope)
curl -X POST 'https://api.livechatinc.com/v3.5/configuration/action/list_groups' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_PAT_TOKEN>' \
  -d '{}'

These give you agent IDs → names/emails and group IDs → department names. Build lookup tables from these before processing archive data.

Extracting Customer Data

Customer details are embedded in each chat's users array. There is no standalone "list all customers" endpoint on the Agent Chat API v3.5. Deduplicate customers from your chat export by email address.

What You Can't Export via API

• Canned responses: No export endpoint exists. Plan to manually recreate them in Tidio.
• Automation rules: No export format. Rebuild in Tidio's workflow editor.
• Real-time/in-progress chats: The list_archives endpoint only covers completed chats. For a live cutover with minimal data gap, consider LiveChat's RTM (Real-Time Messaging) API or webhook-based event capture to catch any chats that close during the migration window.

Step 2: Prepare Your Tidio Environment

Before loading any data, Tidio needs manual configuration. The API is read-only for Operators (GET /operators) and Departments (GET /departments) — you must create these through the admin panel.

Operators: Create an account for every agent. Make sure email addresses match the ones used in LiveChat — this is critical for data attribution in Tidio's ticketing system.

Departments: Recreate your LiveChat Groups as Tidio Departments. Record the resulting UUIDs; you'll need assigned_department_id when creating tickets.

Contact Properties: LiveChat captures custom visitor data through pre-chat surveys, post-chat surveys, and custom variables. In Tidio, the equivalent is Contact Properties, defined under Settings → Contact Properties. Once the schema exists, you can populate values via the properties object in the contact creation payload. Properties not pre-defined in the schema are silently dropped — no 400 error, no warning.

Tags and Custom Fields: Create tags in Help Desk settings. Use GET /tickets/tags to retrieve IDs, then include tag_ids in ticket creation payloads. Ticket custom fields work the same way — define them in the admin panel, retrieve field IDs via GET /tickets/custom-fields, and include them in the custom_fields array.

Step 3: Transform and Load Contacts

Deduplicate the customer records extracted from your chat archives by email, then use idempotent check-before-create logic to avoid duplicates:

import requests
 
TIDIO_CLIENT_ID = "your_client_id"
TIDIO_CLIENT_SECRET = "your_client_secret"
TIDIO_HEADERS = {
    "X-Tidio-Openapi-Client-Id": TIDIO_CLIENT_ID,
    "X-Tidio-Openapi-Client-Secret": TIDIO_CLIENT_SECRET,
    "Content-Type": "application/json"
}
 
def get_existing_contact(email: str) -> dict | None:
    """Check if a contact already exists in Tidio by email."""
    response = requests.get(
        "https://api.tidio.com/contacts",
        headers=TIDIO_HEADERS,
        params={"email": email}
    )
    if response.status_code == 200:
        data = response.json()
        contacts = data.get("contacts", [])
        return contacts[0] if contacts else None
    return None
 
def create_or_get_contact(contact_data: dict) -> str:
    """Return existing Tidio contact_id or create new. Returns contact_id."""
    email = contact_data.get("email")
    if email:
        existing = get_existing_contact(email)
        if existing:
            return existing["id"]
 
    response = requests.post(
        "https://api.tidio.com/contacts",
        headers=TIDIO_HEADERS,
        json=contact_data
    )
    response.raise_for_status()
    return response.json()["id"]

For bulk creation, use the batch endpoint:

curl -X POST 'https://api.tidio.com/contacts/batch' \
  -H 'Content-Type: application/json' \
  -H 'X-Tidio-Openapi-Client-Id: <CLIENT_ID>' \
  -H 'X-Tidio-Openapi-Client-Secret: <CLIENT_SECRET>' \
  -d '{
    "contacts": [
      {
        "email": "customer@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "properties": {
          "company": "Acme Corp",
          "livechat_customer_id": "b7eff798-f8df-4364-8059-649c35c9ed0c"
        }
      }
    ]
  }'

Key constraints:

• Batch limit: Maximum 100 contacts per request.
• All-or-nothing: If one contact in the batch is invalid, the entire batch fails. Validate every record before sending — don't mix clean and suspect records in the same batch.
• No deduplication on create: The POST /contacts endpoint always creates a new contact. It will not merge or overwrite even if the email already exists. The get_existing_contact check above is your guard.
• Required fields: At least one of email, first_name, last_name, or phone must be present.

CSV Import Alternative

If your team prefers a no-code path for contacts, Tidio supports importing contacts from CSV and TXT files via the admin panel (Contacts → Import). Files must be UTF-8 encoded. This works for smaller datasets but lacks the idempotency controls and automation of the API approach.

Step 4: Import Tickets and Conversation History

This is the most demanding phase. Each LiveChat archived chat maps to a single Tidio ticket. All imported tickets land in Tidio's Help Desk module, not the live chat inbox.

Creating Tickets

Use the POST /tickets/as-contact endpoint:

curl -X POST 'https://api.tidio.com/tickets/as-contact' \
  -H 'Content-Type: application/json' \
  -H 'X-Tidio-Openapi-Client-Id: <CLIENT_ID>' \
  -H 'X-Tidio-Openapi-Client-Secret: <CLIENT_SECRET>' \
  -d '{
    "contact_email": "customer@example.com",
    "subject": "[2024-03-15] Chat with Jane Doe",
    "message_content": "[Customer - 2024-03-15 14:32 UTC] Hello, I need help with my order #12345",
    "assigned_department_id": "<DEPARTMENT_UUID>",
    "tag_ids": [1, 5],
    "custom_fields": [
      { "id": 42, "value": "livechat-imported" }
    ]
  }'

Critical constraints:

• No bulk ticket creation: There is no batch endpoint for tickets. Each ticket is created individually, gating high-volume migrations entirely by rate limits.
• One message at creation: The POST /tickets/as-contact call creates the ticket with a single message_content. All subsequent messages must be added via POST /tickets/{ticketId}/reply.
• No historical timestamps: Tidio's API does not accept custom created_at timestamps. Tickets and replies are timestamped at the moment of API call execution. Embed the original date in the ticket subject or a custom field as a workaround.
• No author attribution on replies: The reply API doesn't support author_id. Prefix each message with the original sender name and timestamp to preserve readability and auditability.

Adding Replies to Tickets

After creating a ticket, append each message from the original LiveChat conversation as a reply:

def import_chat_as_ticket(chat: dict, contact_email: str, department_id: str) -> str:
    """
    Create a Tidio ticket from a LiveChat archived chat.
    Returns the created ticket ID.
    Checks for existing ticket by subject to support idempotent re-runs.
    """
    # Flatten all events to ordered reply strings
    events = []
    for thread in chat.get("threads", []):
        events.extend(thread.get("events", []))
    events.sort(key=lambda e: e.get("created_at", ""))
 
    if not events:
        return None
 
    def format_event(event: dict) -> str | None:
        etype = event.get("type")
        author = event.get("author", {})
        author_name = author.get("name", "Unknown")
        author_type = author.get("type", "agent").capitalize()
        ts = event.get("created_at", "")[:16].replace("T", " ")
 
        if etype == "message":
            text = event.get("text", "")
            return f"[{author_type} - {author_name} - {ts} UTC] {text}"
        elif etype == "file":
            url = event.get("url", "")
            name = event.get("name", "attachment")
            return f"[{author_type} - {author_name} - {ts} UTC] Sent file: {name} — {url}"
        elif etype == "rich_message":
            elements = event.get("elements", [{}])
            title = elements[0].get("title", "Rich message")
            url = elements[0].get("url", "")
            return f"[System - {ts} UTC] Sent card: {title} — {url}"
        elif etype == "system_message":
            text = event.get("text", "")
            return f"[System - {ts} UTC] {text}"
        elif etype in ("form", "filled_form"):
            fields = event.get("fields", [])
            summary = "; ".join(f"{f.get('label')}: {f.get('answer', {}).get('value', '')}" for f in fields)
            return f"[Form submission - {ts} UTC] {summary}"
        return None
 
    formatted = [format_event(e) for e in events if format_event(e)]
    if not formatted:
        return None
 
    chat_id = chat.get("id", "unknown")
    chat_date = events[0].get("created_at", "")[:10]
    subject = f"[{chat_date}] LiveChat import — {chat_id}"
 
    # Idempotency: check if ticket already exists by searching subject
    existing = search_ticket_by_subject(subject)
    if existing:
        return existing["id"]
 
    # Create ticket with first message
    ticket_payload = {
        "contact_email": contact_email,
        "subject": subject,
        "message_content": formatted[0],
        "assigned_department_id": department_id,
        "custom_fields": [{"id": 42, "value": "livechat-imported"}]
    }
 
    resp = requests.post(
        "https://api.tidio.com/tickets/as-contact",
        headers=TIDIO_HEADERS,
        json=ticket_payload
    )
    resp.raise_for_status()
    ticket_id = resp.json()["id"]
 
    # Append remaining messages as replies
    for message in formatted[1:]:
        reply_resp = requests.post(
            f"https://api.tidio.com/tickets/{ticket_id}/reply",
            headers=TIDIO_HEADERS,
            json={"message_content": message}
        )
        reply_resp.raise_for_status()
        time.sleep(0.5)  # conservative throttle at 120 req/min
 
    return ticket_id

Your prefix format should be consistent across all tickets for readability:

[Customer - Jane Doe - 2024-03-15 14:32 UTC] Hi, I need help with my invoice.
[Agent - John Smith - 2024-03-15 14:33 UTC] I can help with that. Can you provide the invoice number?
[Customer - Jane Doe - 2024-03-15 14:34 UTC] It is INV-1002.
[System - 2024-03-15 14:38 UTC] Chat transferred to Billing team
[Agent - Sarah Lee - 2024-03-15 14:40 UTC] Here is the corrected PDF: https://your-s3-bucket.com/inv-1002-fixed.pdf

Alternative: Contact Notes for Historical Transcripts

If you don't need conversations in Tidio's ticketing system, you can flatten entire chat threads into formatted text blocks and append them as Contact Notes via POST /contacts/{contact_id}/notes. This is simpler and faster — one API call per conversation instead of N+1 — but the data won't be searchable or reportable through Tidio's ticket analytics.

When using this approach, maintain an in-memory mapping table (local SQLite or Redis) keyed by livechat_customer_id → tidio_contact_id. You'll need it for every note attachment call.

Handling Attachments and Rich Media

Attachment URLs exported from LiveChat are often authenticated or have expiration policies. If you simply reference the LiveChat URL, the link will eventually break, resulting in permanent data loss.

To preserve attachments:

1. Parse the LiveChat JSON for event.type == "file".
2. Download the file using your LiveChat PAT (include the Authorization header — these URLs are not publicly accessible).
3. Upload to secure, long-term storage (AWS S3, Google Cloud Storage).
4. Generate a signed URL or public URL depending on your security posture.
5. Inject the new URL into the ticket reply or contact note as plaintext.

The Tidio ticket reply API does not support inline file attachments via REST — you can only include URLs as plaintext in the message body.

For many teams, historical chat attachments are low-value artifacts. Decide early if they're worth the re-hosting engineering effort.

Rate Limits and Throughput Planning

Both APIs enforce rate limits that gate migration speed:

Tidio 429 responses include an x-ratelimit-remaining: 0 header and a Retry-After header indicating seconds to wait. Always check Retry-After before falling back to exponential backoff.

For a typical migration of 5,000 chats with an average of 8 messages each:

• 5,000 ticket creation calls + 35,000 reply calls = ~40,000 Tidio API requests
• At 60 req/min (Plus): ~11 hours of continuous import
• At 120 req/min (Premium): ~5.5 hours of continuous import
• Add ~10–15% overhead for contact creation calls, tag lookups, and idempotency checks

Build your migration script with:

• Exponential backoff on 429 responses. Check Retry-After first; if missing, start at 5 seconds and double on subsequent failures (cap at 60 seconds).
• Checkpointing — log the last successfully imported chat ID to a local file or database so you can resume after failures without re-processing completed records.
• Dry-run mode — validate payloads against Tidio's schema before sending by logging the payload structure without making the API call.
• Serial execution only — do not run concurrent threads against Tidio's API unless you have explicitly negotiated a rate limit increase with their support team. Concurrent threads share the same rate limit bucket and will cause cascading 429s.

Common API Errors and Fixes

Rollback Strategy

Before starting any import run, define your rollback procedure. There is no bulk undo in Tidio.

Contacts: Tidio provides DELETE /contacts/{contactId} to remove individual contacts. There is no batch delete endpoint. For a rollback, you must iterate over the contact IDs you created (log them during import) and issue individual delete calls, subject to rate limits.

Tickets: Similarly, DELETE /tickets/{ticketId} removes individual tickets. Log every created ticket ID during import.

Practical approach for large datasets:

1. Run a pilot import of 50–100 records into a staging environment (if Tidio allows sandbox access on your plan) or a dedicated test project.
2. Log all created entity IDs to a created_ids.json file during every run.
3. Write a rollback script that reads created_ids.json and issues DELETE calls with rate-limit handling before starting a full re-run.
4. Never run the full migration without a complete created_ids.json checkpoint you can restore from.

If you discover a data quality issue after a full import (e.g., all contacts missing a required property), a full rollback at 60 req/min against 5,000 contacts + 5,000 tickets = ~167 minutes of delete calls before you can re-run cleanly.

What You'll Lose in the Migration

Be honest with stakeholders about what doesn't survive the move:

Validation and Post-Migration Audit

After the import completes:

1. Count check: Compare contacts created in Tidio against your deduplicated customer list from LiveChat. Paginate GET /contacts to get a total count.
2. Ticket count: Compare tickets in Tidio against your archived chat count. Paginate GET /tickets and count.
3. Message fidelity: Pick 10–20 tickets at random and compare message content and ordering against the original LiveChat archive JSON. Look for encoding issues with emoji, special characters, and non-Latin scripts.
4. Custom property validation: Fetch a sample of contacts via GET /contacts/{contactId} and verify properties populated correctly. Any silent drops will show as missing fields here.
5. Department assignment: Confirm tickets landed in the correct departments by filtering GET /tickets by department ID.
6. Attachment links: For any re-hosted attachments, verify the S3/GCS URLs resolve successfully. Test both authenticated and public access depending on your configuration.
7. Event type coverage: Verify that system_message and rich_message events appear correctly formatted in a sample of tickets — these are the most error-prone transformations.

When the Engineering Cost Doesn't Make Sense

This migration is achievable for teams with API experience, but the combination of single-ticket creation (no bulk endpoint), no timestamp preservation, tight rate limits, manual pre-configuration requirements, and no native rollback tooling makes it labor-intensive at scale.

For reference: a 10,000-chat dataset with 8 messages average generates ~90,000 API calls. At Premium tier rate limits, that's approximately 12.5 hours of execution time, not counting error recovery, rollback testing, or validation. Datasets above 10,000 conversations typically require a dedicated migration engineer for 2–5 days of build, test, and run time.

At ClonePartner, we've handled LiveChat-to-Tidio migrations with datasets ranging from a few hundred to hundreds of thousands of conversations. Our scripts handle rate-limit orchestration, timestamp preservation in metadata fields, attachment re-hosting, idempotent re-runs, and end-to-end validation.

For related migrations, see our guides on Zendesk to Tidio, Zendesk to LiveChat, or Tidio to Zendesk.