LiveAgent to Trengo Migration: Technical Guide & API Mapping

LiveAgent to Trengo Migration: Technical Guide & API Mapping

Migrating from LiveAgent to Trengo means moving from a traditional ticket-centric helpdesk into a multi-channel communication platform built around conversations and channels. The two systems share overlapping concepts — contacts, tickets, knowledge bases — but differ enough in architecture that a direct 1:1 copy is not possible.

This guide covers the full entity mapping, dependency ordering, API constraints on both sides, attachment handling, rollback procedures, and the edge cases that catch teams mid-migration. It also walks through the delta sync strategy for achieving a zero-downtime cutover.

Why Teams Move from LiveAgent to Trengo

The most common technical drivers across migration projects:

• Channel consolidation. Trengo natively supports WhatsApp Business, Instagram DM, Facebook Messenger, and voice from a single inbox. Teams running LiveAgent with bolt-on integrations for these channels want a unified experience.
• Omnichannel routing. Trengo's channel-based routing model fits teams managing high volumes across messaging apps, not just email and live chat.
• AI Journeys. Trengo's built-in AI agent and conversational flows appeal to teams that want automation without third-party bot builders.
• Pricing structure. Trengo's per-seat pricing with bundled channels can be more cost-effective for teams paying for LiveAgent add-ons individually.

Whatever the driver, the migration follows the same technical sequence.

The Data Model Mismatch

Before writing a single line of migration code, understand how these two systems model data differently.

LiveAgent uses a classic Ticket model. A single ticket can contain a mix of emails, internal notes, live chats, and phone call recordings. The ticket is the container; messages are events inside it. Customers are stored as contact records with associated companies.

Trengo uses a Conversation model built around specific Channels. Its API expects conversations to be explicitly tied to a channel (Email, WhatsApp, Website Chat, etc.). The identity model is also different: a Contact in Trengo is a channel-specific identity (one email address or one phone number), while a Profile is a roll-up that groups multiple contacts for the same customer. (help.trengo.com)

The practical implication: a single LiveAgent customer who used email and WhatsApp may need to become two Trengo contacts (one per channel) linked to one Profile. And a mixed-media LiveAgent ticket cannot be dumped into a single Trengo conversation without transformation — you need to decide which channel each ticket maps to.

Entity Mapping: LiveAgent → Trengo

This table is the single reference for mapping every relevant LiveAgent object to its Trengo counterpart.

Migration Dependency Order

The order you create objects in Trengo matters. Every ticket references a contact, a channel, and optionally a team or user assignment. If those parent objects don't exist yet, your import will fail silently or create orphaned records.

Follow this sequence:

1. Users (Agents) — Provision manually in Trengo. Record each user's Trengo ID.
2. Teams — Create teams and assign users. Map each LiveAgent department ID to its Trengo team ID.
3. Channels — Configure email, WhatsApp, live chat, and any other channels in Trengo. Every ticket import needs a valid channel_id.
4. Contact Custom Field Definitions — Create the field schema in Trengo before importing contact data.
5. Labels — Create all labels (mapped from LiveAgent tags) via the Trengo API.
6. Contacts / Companies — Import contacts via API, then create contact groups from LiveAgent companies. Attach custom field values immediately after contact creation.
7. Help Center Structure — Create the help center (with languages), then categories, then sections.
8. Help Center Articles — Import articles into existing categories/sections.
9. Quick Replies — Migrate canned messages and predefined answers.
10. Tickets + Messages — The bulk of the migration. Import tickets linked to contacts, channels, and assigned users/teams. Import messages in chronological order per ticket.
11. Webhooks — Recreate and point to new endpoints (see webhook verification note below).
12. Automation Rules / SLA — Rebuild manually after validating ticket data.

Exporting Data from LiveAgent

LiveAgent offers two extraction paths: the API v3 and a database dump (available by request to leaving customers).

API v3 Extraction

The API v3 is the recommended extraction method. Key endpoints:

• GET /api/v3/tickets — paginated ticket list with filters
• GET /api/v3/tickets/{ticketId}/messages — messages and attachments per ticket
• GET /api/v3/customers — contact records with custom fields
• GET /api/v3/companies — company records
• GET /api/v3/tags — all tags
• GET /api/v3/agents — agent list
• GET /api/v3/knowledgebase — KB articles and categories
• GET /api/v3/canned_messages — canned messages
• GET /api/v3/predefined_answers — predefined answers

Rate limit: 180 requests per minute per API key. You can parallelize across multiple keys if your plan allows it. (support.liveagent.com)

Authentication modes: LiveAgent API v3 supports both API key authentication (permanent) and OAuth tokens (expiring). Use API key authentication for long-running extraction jobs. OAuth tokens expire during a 9+ hour extraction run, causing silent mid-run failures that are difficult to detect without explicit token validity checks. Do not use OAuth tokens for automated migration pipelines.

Ticket list cap: LiveAgent limits ticket list retrieval to 10,000 records per filter on API v3 (1,000 on API v1). Export in narrow time windows — week or month slices — instead of trying to pull everything in one query. (support.liveagent.com)

The N+1 Query Problem

The /tickets endpoint returns ticket metadata (subject, status, assignee) but not the conversation threads. To get messages, you must make a separate API call per ticket:

curl -X GET "https://yourdomain.ladesk.com/api/v3/tickets/{ticket_id}/messages" \
     -H "apikey: YOUR_LIVEAGENT_API_KEY"

If you have 100,000 tickets, that is 100,000 additional API calls. At 180 requests per minute, extraction alone takes over 9 hours — just for messages, not counting contacts and attachments. Use asynchronous worker queues: split the ticket IDs into chunks, distribute across multiple workers, and strictly respect Retry-After headers to avoid IP bans.

Pagination Quirks

Most endpoints use _perPage and _page parameters. But some — specifically GET /calls, GET /tickets/history, and GET /phone_numbers — use a cursor-based _cursor parameter instead. The cursor value comes from the next_page_cursor response header. Mixing up pagination styles results in missing data without any error signal.

Timezone Handling

API v3 returns timestamps based on your LiveAgent account's timezone setting, not the requesting user's timezone. Add the Timezone-Offset header to normalize timestamps during extraction. Missing this causes subtle date-shift bugs that are difficult to debug after import.

import requests
import time
 
LA_BASE = "https://youraccount.liveagent.com/api/v3"
LA_API_KEY = "your-api-key"
HEADERS = {
    "apikey": LA_API_KEY,
    "Timezone-Offset": "0"  # Normalize to UTC
}
 
def extract_tickets():
    page = 1
    all_tickets = []
    while True:
        resp = requests.get(
            f"{LA_BASE}/tickets",
            headers=HEADERS,
            params={"_page": page, "_perPage": 50}
        )
        resp.raise_for_status()
        tickets = resp.json()
        if not tickets:
            break
        all_tickets.extend(tickets)
        page += 1
        time.sleep(0.35)  # Stay under 180 req/min
    return all_tickets

Version 5.62 Edge Case

Starting with LiveAgent version 5.62, ticket notes changed type values and note group IDs can be UUID strings instead of integers. Integrations that filter on old note markers or cast IDs to integers will silently miss notes. Treat all note-related IDs as strings and update your extractor to handle both representations. (support.liveagent.com)

Database Dump (Alternative)

For very large accounts (50,000+ tickets), paginating through the API can take days. LiveAgent's support team can provide a raw database dump via secure file transfer. Request this at support@liveagent.com from your account owner email. The dump contains raw database tables — useful for bulk processing but requires significantly more transformation work than the structured API responses. (support.liveagent.com)

Importing Data into Trengo

Trengo's REST API (v2) is your import target. All requests use Bearer token authentication against https://app.trengo.com/api/v2/.

General rate limit: 120 requests per minute. Trengo's dedicated import endpoints (message_import/email_message and message_import/text_message) are stricter at 60 requests per minute. When you hit the limit, Trengo returns HTTP 429 with Retry-After and X-RateLimit-Reset headers. Build backoff logic that reads these headers — don't use fixed sleep intervals. (developers.trengo.com)

Trengo API error reference: The most common validation errors during import are HTTP 422 (Unprocessable Entity). Specific fields that trigger 422 responses include: missing or invalid channel_id, sent_at timestamps set in the future, message_identifier values that exceed length limits or contain disallowed characters, and user_id values referencing non-existent agents. Log the full response body on every 422 — the errors object identifies the offending field. HTTP 409 is returned when a message_identifier collision occurs on retry; implement idempotency by storing the Trengo message ID after each successful import and skipping already-imported identifiers on rerun.

message_identifier uniqueness scope: The message_identifier must be unique per channel, not per account. Collisions across channels are technically possible but functionally invisible — only duplicates within the same channel trigger a 409. On retry after a failure, always check your local import log before re-submitting a message. Blind resubmission without the 409 handler will create duplicate messages in the conversation history.

Does Trengo have a sandbox environment? Trengo does not offer a publicly documented sandbox or test environment separate from production. Validate imports against a dedicated test channel within your production account — create a throwaway email channel, import a representative sample batch, inspect results, then delete the test tickets before running the full migration.

Channel Mapping

Every Trengo ticket belongs to a channel. LiveAgent tickets originate from different sources. You need a mapping table:

Contact Import

Trengo contacts are created on a specific channel via /channels/{channel_id}/contacts. The identifier must match the channel type — email for email channels, phone number for phone-based channels. If the contact already exists on that channel, Trengo returns the existing record instead of creating a duplicate. (developers.trengo.com)

When importing:

• Deduplicate before import. LiveAgent may have multiple contact records for the same person across different channels.
• Create contacts first, then immediately attach custom field values in a follow-up API call.
• Group contacts into Profiles when the same customer appears on multiple channels. Trengo exposes a profile-linking endpoint (POST /api/v2/profiles/{profile_id}/contacts) to associate multiple channel-specific contacts with a single profile. Use this when the same customer appears on both email and WhatsApp channels during migration.
• Create contact groups (from LiveAgent companies) and link contacts after creation.

Concurrent contact creation safety: When distributing import work across multiple parallel workers, two workers may simultaneously attempt to create the same contact (matched by email or phone). Trengo's idempotent contact creation (returning the existing record on duplicate) protects against duplicate contact records in most cases. However, race conditions between contact creation and the immediately following custom field attachment call can leave contacts with incomplete field data. Implement a short retry with exponential backoff on custom field attachment calls, and run a reconciliation pass after bulk import to verify field completeness.

import requests
import time
 
TRENGO_BASE = "https://app.trengo.com/api/v2"
TRENGO_TOKEN = "your-bearer-token"
TRENGO_HEADERS = {
    "Authorization": f"Bearer {TRENGO_TOKEN}",
    "Content-Type": "application/json"
}
 
def create_contact(channel_id, identifier, name):
    resp = requests.post(
        f"{TRENGO_BASE}/channels/{channel_id}/contacts",
        headers=TRENGO_HEADERS,
        json={"identifier": identifier, "name": name}
    )
    if resp.status_code == 429:
        wait = int(resp.headers.get("Retry-After", 60))
        time.sleep(wait)
        return create_contact(channel_id, identifier, name)
    resp.raise_for_status()
    return resp.json()

Ticket and Message Import

This is the most time-consuming step and where most migrations fail.

For email-origin tickets, use Trengo's message_import/email_message endpoint. It accepts INBOUND, OUTBOUND, or NOTE message types, requires a sent_at timestamp in the past, supports body content up to 65,000 characters, and requires a unique message_identifier. When the message type is OUTBOUND, you must pass user_id to preserve the original sender. (developers.trengo.com)

For SMS or WhatsApp-origin tickets, use message_import/text_message. Same rate limit (60 req/min), same timestamp requirements, but allows only one attachment per request. (developers.trengo.com)

Message ordering matters. Import messages in ascending chronological order per ticket. Trengo renders messages in creation order — importing out of sequence makes the conversation history unreadable.

Status mapping: Trengo supports NEW, OPEN, and CLOSED statuses. Map LiveAgent's granular statuses as follows:

Use Trengo Labels to preserve LiveAgent-specific states (like "Postponed" or "Answered") that have no direct Trengo equivalent.

Suppress automations during backfill. Trengo's import endpoints expose a trigger_workflows flag. Set it to false to prevent historical messages from firing current production rules. Re-enable workflows only after validation. (developers.trengo.com)

Handling Attachments

Attachments require a two-step process:

Step 1: Download from LiveAgent. The message payload contains an attachments array with a download_url. You must pass your LiveAgent API key to download the file — these URLs are behind an authentication wall.

Step 2: Upload to Trengo. Use a multipart/form-data upload to Trengo's attachment endpoint, which returns an attachment reference. Include that reference in the message creation call.

curl -X POST "https://app.trengo.com/api/v2/attachments" \
     -H "Authorization: Bearer YOUR_TRENGO_TOKEN" \
     -F "file=@/path/to/local/file.pdf"

The following table consolidates all attachment constraints across both platforms and the handling strategy for each scenario:

GDPR and data residency: If your LiveAgent account is EU-hosted and your migration middleware runs in a non-EU region, attachment data (and all ticket content) temporarily passes through infrastructure outside the EU during the download-transform-upload process. Verify that your middleware server's region is compliant with your data processing agreements before starting extraction. For EU-regulated data, run migration workloads on EU-region cloud instances. This applies to contact PII as well as message content.

Knowledge Base Migration

LiveAgent has a customizable knowledge base structure that can span multiple customer portals. Trengo uses a unified Help Center with a hierarchy: Help Center → Categories → Sections → Articles.

1. Create the Help Center in Trengo with languages and a default language. Trengo does not automatically translate content — handle localization explicitly.
2. Map LiveAgent KB categories to Trengo categories. If you used subcategories or logical groupings in LiveAgent, model these as Trengo sections within categories.
3. Import articles via POST /api/v2/help_center/{help_center_id}/articles.
4. Sanitize HTML. LiveAgent articles often contain proprietary CSS classes or inline styles that don't render in Trengo. Run content through a sanitization pass (DOMPurify or a custom parser) to strip platform-specific markup.
5. Handle inline images. Images hosted on LiveAgent servers must be downloaded, uploaded to a public CDN or Trengo's hosting, and the <img> src attributes rewritten before importing.

LiveAgent forums and suggestion boards have no Trengo equivalent. Export these as static HTML or CSV and archive separately.

Automation, Rules, and Permissions

Automation rules, SLA configurations, and permission structures cannot be migrated via API. These are rebuild work, not history replay.

• Automation Rules: LiveAgent relies on a built-in rule engine for routing and SLA management. Trengo uses condition/action automations with different trigger events. Audit your active LiveAgent rules, map conditions to Trengo's available triggers, and test thoroughly before cutover.
• Quick Replies: LiveAgent has two concepts — Canned Messages and Predefined Answers. Both map to Trengo's Quick Replies. Watch for placeholder/variable syntax differences: LiveAgent uses {ticket_id}, {customer_name}, etc., which won't resolve in Trengo. Replace with Trengo equivalents after import.
• Permissions: LiveAgent departments control routing, access, templates, and communication availability. Trengo users have specific roles (observer, basic_agent, advanced_agent, supervisor, administrator). Don't assume department membership converts cleanly to a Trengo team plus role — review every permission boundary manually. (support.liveagent.com)
• Webhook verification: When you recreate webhooks in Trengo, Trengo sends a verification challenge to your endpoint before activating the webhook. Your receiving endpoint must respond with a 200 and the challenge token within the timeout window. If your webhook endpoint is not live and responsive at cutover time, the webhook will remain inactive. Verify endpoint availability before scheduling the cutover, not during it.

Delta Sync and Cutover

A migration of this scale cannot happen instantly. Extracting, transforming, and loading hundreds of thousands of tickets often takes days. During that time, your team is still working in LiveAgent.

Initial Full Sync

Run the complete migration targeting all data up to a specific freeze date. Don't switch MX records or chat widgets yet. Let the script run over the weekend.

Delta Sync

Once the full sync completes, your migration database should record the last processed ticket_id and last_updated timestamp.

Write a secondary script that queries LiveAgent for tickets created or modified after that timestamp:

curl -X GET "https://yourdomain.ladesk.com/api/v3/tickets?date_changed_from=2023-11-01T00:00:00Z" \
     -H "apikey: YOUR_LIVEAGENT_API_KEY"

This script handles two scenarios:

1. New tickets: Create them in Trengo from scratch.
2. Updated tickets: Fetch new messages from LiveAgent and append them to the existing mapped ticket in Trengo.

Because LiveAgent supports filtered ticket export and Trengo lets you suppress workflow triggers during import, you can backfill history ahead of time instead of waiting for a single big-bang weekend.

The Cutover

Schedule a 60-minute maintenance window:

1. Route your support email addresses (MX records or forwarding rules) from LiveAgent to your new Trengo channels.
2. Swap out the LiveAgent chat widget for the Trengo widget.
3. Run the delta sync script one final time to catch tickets updated in the last few hours.
4. Revoke agent access to LiveAgent to prevent split-brain data entry.
5. Enable automations and workflows in Trengo.
6. Monitor the first day of live traffic with the rollback procedure below documented and ready.

Rollback Procedure

If critical issues appear after cutover, the rollback steps are:

1. Repoint MX records back to LiveAgent's mail server. DNS TTL propagation takes 5–60 minutes depending on your TTL settings. Use a TTL of 300 seconds (5 minutes) on your MX records before cutover to enable fast rollback.
2. Re-enable the LiveAgent chat widget by reverting the JavaScript snippet on your website. If you use a tag manager, this is a single toggle.
3. Restore agent LiveAgent access by re-enabling suspended accounts.
4. Trengo bulk deletion: Trengo does not expose a bulk-delete endpoint for imported tickets via the public API. Individual ticket deletion is available via DELETE /api/v2/tickets/{ticket_id}. For large rollbacks, contact Trengo support to request a bulk data removal — document your ticket ID ranges from the import log before cutover so this request can be scoped quickly.
5. Keep LiveAgent active until you have confirmed the new environment is stable. Do not close your LiveAgent account until at least 30 days post-cutover.

Common Failure Modes

Rate Limit Collisions

The combined rate limits — 180 req/min on LiveAgent extraction, 60 req/min on Trengo's import endpoints — create a throughput ceiling. For 30,000 tickets averaging 5 messages each, that is 150,000+ API calls on the Trengo side. At 60 req/min, that is approximately 42 hours of continuous import. Plan your maintenance window accordingly, or distribute load across multiple Trengo API tokens if you have multiple admin users.

OAuth Token Expiry During Extraction

If you use OAuth tokens rather than API keys for LiveAgent authentication, tokens will expire during a multi-hour extraction run. The failure is silent — the API returns 401 after expiry, and without explicit token validity checks, your script may process the error response as an empty result set rather than an authentication failure. Use LiveAgent API key authentication for all migration workloads.

Orphaned Contact References

If a ticket references a contact that failed to import (duplicate email, validation error), the ticket import will either fail or create an anonymous contact. Run a contact reconciliation pass before starting ticket import. Compare contact counts between your extracted dataset and the Trengo API contact count before proceeding.

Concurrent Worker Race Conditions

When running parallel import workers, two workers may attempt to create the same contact simultaneously. Trengo's idempotent contact creation handles duplicate detection, but the subsequent custom field attachment call may fail if it fires before the contact creation response is fully committed. Implement a short delay (500ms–1s) between contact creation and custom field attachment, and run a post-import field reconciliation pass.

Attachment Size and Count Mismatches

Trengo's per-request attachment limits (20 MB, max 5 files for email import; 1 file for text-message import) may reject files that uploaded fine in LiveAgent's 25 MB limit. Identify oversized attachments during extraction and decide per-attachment whether to downsize, link externally, or skip before starting import.

HTML Content Issues

LiveAgent ticket messages and KB articles contain inline HTML that Trengo may strip or re-render differently. Test a sample batch of HTML-heavy messages before running the full import.

Timezone Drift

LiveAgent's API returns timestamps in the account timezone. If your script doesn't normalize to UTC before importing into Trengo, timestamps will be shifted. This is especially painful for teams spanning multiple timezones, where the drift may be non-uniform across ticket history.

message_identifier Collision on Retry

After an import failure mid-run, naive resubmission of the same batch will trigger HTTP 409 conflicts on already-imported messages within the same channel. Always check your import log before resubmitting. Store the Trengo-assigned message ID alongside the message_identifier in your migration database, and skip any identifier that already has a recorded Trengo ID.

Post-Migration Validation

After import, run these checks before going live:

• Contact count match — Compare totals, accounting for intentional deduplication.
• Ticket count match — Spot-check 20–30 tickets across different date ranges.
• Message integrity — For each spot-checked ticket, verify message count and chronological order.
• Attachment accessibility — Open 10+ attachments across different tickets. Confirm files download correctly.
• Custom field values — Verify fields populated correctly on a sample of contacts and tickets.
• Label assignment — Confirm labels match original LiveAgent tags.
• KB article rendering — Review 10+ articles for formatting, images, and internal links.
• Quick reply variables — Test every quick reply that contained LiveAgent variables. Replace with Trengo equivalents.
• User/Team assignment — Verify assigned agent and team mappings on spot-checked tickets.
• Timestamps — Confirm ticket and message timestamps are accurate (no timezone offset issues).
• Reply threading — Test that email reply threading works correctly with imported message identifiers.
• Webhook activation — Confirm each recreated webhook shows "active" status in Trengo after passing the verification challenge.
• Profile linking — Verify that customers who appeared on multiple channels in LiveAgent have their contacts correctly linked to a single Trengo Profile.
• Custom field completeness — For any contacts that were created by parallel workers, verify no custom field values are missing from the race condition window.
• Status mapping — Spot-check that LiveAgent "Postponed" and "Answered" tickets carry the expected Trengo Label, not just a default OPEN status.

When to Archive Instead of Migrate

Not all LiveAgent data needs to move into the live Trengo inbox. The decision criteria:

How Long Does the Migration Take?

These estimates include extraction, transformation, import, and validation. The 42-hour import ceiling at 60 req/min (for 150,000 message calls) is the binding constraint for large accounts — not engineering effort. The manual setup steps (users, teams, channels) should be completed before the clock starts. Attachment volume significantly extends these estimates: 100 GB of attachments at typical cloud download/upload speeds adds 12–24 hours independent of API rate limits.

Five Highest-Risk Steps in This Migration

Based on the failure modes documented above, these are the steps with the highest probability of causing data loss or requiring rework:

1. Timezone normalization — Silent, discovered late, affects every timestamp in the dataset.
2. Attachment size enforcement — Failures are ticket-specific and inconsistent; easy to miss in spot-checks.
3. Contact custom field completeness after parallel import — Race conditions leave gaps that don't surface until agents notice missing data.
4. OAuth token expiry during extraction — Silent 401 errors processed as empty results; no warning.
5. message_identifier collision on retry — Rerunning a failed import without an idempotency check creates duplicate messages that are visible to agents and customers.

All five are preventable with the controls described in this guide. None are recoverable without re-running significant portions of the migration pipeline.

For more on getting data out of Trengo (if you ever need the reverse direction), see our guide on how to export data from Trengo, as well as our specific teardowns for migrating Trengo to Kustomer or Help Scout. If you're evaluating Trengo alternatives before committing, we've published a detailed Trengo alternatives comparison.