Pylon to Kayako Migration: The Complete Technical Guide

Pylon to Kayako Migration: The Complete Technical Guide

Migrating from Pylon to Kayako means moving from a Slack-first, AI-native B2B support platform to a multi-channel helpdesk built around email conversations, live chat, and social channels. There is no checkbox, no wizard, no one-click migration tool. You need a custom API-based ETL pipeline — extract from Pylon's REST API (api.usepylon.com), transform the data model, and load into Kayako's REST API.

The realistic timeline is 5–12 business days — broken down as approximately 1 day for audit and pre-creation, 2–4 days of pipeline runtime (dominated by message extraction at Pylon's 20 req/min limit), 1–2 days for QA, and 1 day for delta sync and cutover. The single biggest constraint is Pylon's issue list endpoint, rate-limited to 10 requests per minute with a mandatory time range parameter capped at 30 days per call.

For teams evaluating alternative migration paths, see our guides on migrating from Pylon to Zendesk, Missive, or eDesk.

Why Teams Move from Pylon to Kayako

Pylon is purpose-built for B2B support where conversations happen in shared Slack channels, Microsoft Teams, and Discord. Its core object is the Issue — a conversational thread tied to an Account with messages, internal notes, custom fields, and CRM-synced metadata.

Kayako is a multi-channel helpdesk where the core object is the Conversation (API field: cases) — a structured support record with messages, notes, SLAs, custom fields, and automation triggers.

Teams make this move for three concrete reasons:

• Multi-channel requirements. Kayako natively supports email, live chat (Kayako Messenger), Facebook, Twitter, and Help Center forms. Pylon is limited to Slack Connect, MS Teams, and Discord — no email-first workflow.
• eCommerce or SMB support workflows. Kayako's conversation-centric model with customer Journey timelines and built-in CSAT ratings suits high-volume, customer-facing support. Pylon's Account Intelligence (health scores, CRM sync, partner account hierarchies) is designed for B2B account management, not ticket volume throughput.
• Self-hosted option. Kayako Classic is available as an on-premise deployment — a hard requirement for some regulated industries. Pylon is cloud-only with no self-hosted option.

When extracting data from Pylon, you are pulling unstructured, chat-based interactions containing Slack Block Kit JSON. When loading into Kayako, you must force those interactions into a rigid schema of Conversations, Messages, and standardized user profiles. If you fail to map this correctly, your Kayako instance will be flooded with unreadable, out-of-order chat fragments containing raw Slack markup.

Pylon vs. Kayako: Data Model Mapping

The mapping is not one-to-one. Pylon's data model is account-centric and conversational. Kayako's is conversation-centric with organizations as a secondary grouping.

Status Mapping

Kayako Cloud's default conversation statuses are New, Open, Pending, and Completed. Custom statuses require Kayako Classic. Kayako uses status as the API field name on the cases resource.

API Constraints: Extraction from Pylon

Pylon's REST API lives at api.usepylon.com and uses Bearer token authentication (Authorization: Bearer {token}). Only Admin users can generate API tokens via the Pylon dashboard under Settings → API.

The issues endpoint is the bottleneck. At 10 requests per minute with a mandatory 30-day window, you must chunk your export into 30-day intervals. For a workspace with 2 years of history, that is a minimum of 24 API calls for the issue index alone — before fetching any messages.

Message extraction dominates pipeline runtime. Each issue requires at least one GET /issues/{id}/messages call. At 20 requests per minute with no retries or pagination overhead, extracting messages for 10,000 issues takes a minimum of 500 minutes (8.3 hours). In practice, expect 1.3–1.8× that figure after accounting for retries, backoff, and cursor pagination on issues with long thread histories.

Slack formatting is the hidden transformation cost. Pylon's API returns message bodies as Slack Block Kit JSON or raw Slack Markdown. This is not valid HTML. You must build a translation layer in your middleware before loading into Kayako. Pushing raw Slack markup directly to Kayako renders as literal characters (*bold*, <@U1234|alice>) — unreadable for agents.

# Pseudocode: Chunked issue extraction from Pylon
import datetime
import time
 
start = datetime.datetime(2023, 1, 1, tzinfo=datetime.timezone.utc)
end = datetime.datetime.now(datetime.timezone.utc)
chunk_days = 30
all_issues = []
request_count = 0
 
current = start
while current < end:
    chunk_end = min(current + datetime.timedelta(days=chunk_days), end)
    # Enforce 10 req/min: sleep 6 seconds between calls
    if request_count > 0:
        time.sleep(6)
    issues = pylon_client.list_issues(
        start_time=current.isoformat(),
        end_time=chunk_end.isoformat(),
        limit=20000
    )
    all_issues.extend(issues)
    request_count += 1
    current = chunk_end

API Constraints: Loading into Kayako

Kayako exposes two API versions depending on your deployment target:

• Kayako Cloud: REST API at https://{domain}.kayako.com/api/v1/, JSON responses, Basic Auth (email + password) or OAuth 2.0. Rate limits exist but are not publicly documented.
• Kayako Classic (self-hosted): REST API at https://{domain}/api/index.php?/, XML responses by default, API key + secret authentication with HMAC-SHA256 signature. No documented rate limits — throttle conservatively at 30–60 req/min to avoid server saturation.

Kayako Cloud key endpoints for import:

Pagination on read: Kayako Cloud defaults to 10 results per page; use ?limit=100 for maximum throughput during verification. Pagination uses offset-based parameters (?page=2).

Kayako Cloud vs. Classic: Decision Criteria

Recommendation: Target Kayako Cloud unless you have a hard on-premise requirement. Kayako Classic is not receiving new feature development, and migrating from Classic to Cloud is a separate, subsequent project.

Step-by-Step Migration Process

Step 1: Audit and Pre-create Kayako Structure

Before moving any data:

1. Map custom fields. List all Pylon custom fields (GET /custom-fields) and create matching fields in Kayako under Administration → Custom Fields. Critically, Kayako separates custom fields by scope — conversation, user, and organization — while Pylon does not. A Pylon field attached to Issues maps to a Kayako conversation field; a field attached to Accounts maps to an organization field. Misclassifying scope means the field is invisible in the wrong context.
2. Create teams. Map Pylon Teams to Kayako Teams before importing conversations. Conversations assigned to non-existent teams will fail validation.
3. Create agent accounts. Every Pylon User (agent) needs a corresponding Kayako agent account with an assigned role. Agents must exist before conversations can be assigned to them — the API returns HTTP 404 on assigned_agent_id if the agent does not exist.
4. Set up Help Center structure. If migrating knowledge base content, create Kayako Help Center categories and sections that mirror your Pylon Knowledge Base and Collections hierarchy before importing articles.

Step 2: Export Users, Organizations, and Contacts from Pylon

Extract in dependency order:

1. Accounts (GET /accounts) → Kayako Organizations
2. Contacts (GET /contacts) → Kayako Users (customer type)
3. Users (GET /users) → Kayako Agents

Build a persistent lookup table mapping Pylon entity IDs to Kayako entity IDs for every object. Store this as a file (JSON or SQLite) — not in memory — so the mapping survives pipeline restarts.

The email address problem: Pylon contacts are often identified exclusively by Slack user IDs (U0123ABCD). Kayako requires a valid email address as the unique identifier for Users. If you POST a user to Kayako without an email address, the API returns HTTP 422 (email_required). Contacts without email addresses must be resolved before import by cross-referencing your CRM or querying the Slack API (users.info method) using the Slack user ID. Contacts that cannot be resolved to an email address should be created with a placeholder (migrated-{slack_id}@placeholder.internal) and flagged for manual review post-migration.

Step 3: Export Issues and Messages from Pylon

This is the long pole of the pipeline. Extract issues in 30-day chunks, then fetch messages per issue.

For each issue, capture: title, description, status, priority, assignee (agent ID), team ID, tags, custom field values, account ID (→ Organization), contact ID (→ User), created_at, updated_at.

For each message, capture: body (HTML or plain text), author ID and type (agent vs. customer), message type (reply vs. internal note), attachment URLs, created_at timestamp.

Attachment URL expiry is a silent failure mode. Download all attachments immediately after extracting message data. Pylon's pre-signed attachment URLs have a time-limited validity window. If you defer the download step and the URL expires before you attempt the pull, the attachment is silently lost — the message body will contain a broken reference with no error in your extraction log.

Step 4: Transform and Load into Kayako

The transformation layer handles several non-trivial conversions:

Status mapping per the table in the Data Model section above.

User/Organization ID translation using the lookup table built in Step 2.

Custom field value mapping. Pylon custom fields are flat key-value pairs referenced by field name. Kayako custom fields must reference the numeric field ID assigned during pre-creation in Step 1. Build a field-name-to-field-ID lookup table alongside your entity ID map.

Channel assignment. Pylon Issues do not map to a single Kayako channel. For historical imports, use MAIL as the channel value — it is the most permissive channel type and does not trigger live chat session logic or social media webhooks.

Slack formatting translation. Pylon messages contain Slack Markdown (*bold*, _italic_) and Slack-specific constructs (<@U1234|username>, <!here>, <https://example.com|link text>). Kayako expects standard HTML for conversation message bodies. Pushing raw Slack syntax into Kayako results in unreadable agent-facing text.

// Slack Markdown → Kayako HTML (simplified examples)
// Input from Pylon API
const slackText = "Hey <@U1234|alice>, please review this *urgent* issue. See <https://example.com|this link>.";
 
// Required output for Kayako API
const kayakoHtml = "<p>Hey Alice, please review this <strong>urgent</strong> issue. See <a href=\"https://example.com\">this link</a>.</p>";
 
// User mention resolution requires the Pylon/Slack ID → agent name lookup table
// built during Step 2. Without it, mentions become "[unknown user]".

Message ordering is mandatory. Import messages in strict chronological order by created_at. Kayako Conversations display messages in creation sequence, and out-of-order imports produce permanently scrambled thread histories that cannot be reordered post-import without deleting and recreating messages.

# Pseudocode: Transform Pylon Issue → Kayako Conversation payload
def transform_issue(pylon_issue, id_map, field_id_map):
    return {
        "subject": pylon_issue["title"],
        "channel": "MAIL",
        "requester_id": id_map["contacts"][pylon_issue["contact_id"]],
        "assigned_agent_id": id_map["users"].get(pylon_issue["assignee_id"]),
        "assigned_team_id": id_map["teams"].get(pylon_issue["team_id"]),
        "status": STATUS_MAP[pylon_issue["state"]],
        "tags": pylon_issue.get("tags", []),
        "custom_fields": [
            {"id": field_id_map[k], "value": v}
            for k, v in pylon_issue.get("custom_fields", {}).items()
            if k in field_id_map
        ],
    }

Step 5: Migrate Attachments

Pylon's pre-signed attachment URLs require a multi-step process:

1. Download all attachments immediately after message extraction. Do not batch this step separately — URL expiry will silently break attachment recovery.
2. Store files in a secure temporary staging volume with a manifest file linking Pylon message ID → local file path → Kayako message ID.
3. Re-upload to Kayako using multipart/form-data POST to /api/v1/conversations/{id}/messages/{msg_id}/attachments.
4. Record the Kayako File ID returned in the response. Update the manifest. Do not assume the upload succeeded — verify HTTP 201 for each file.

File size limit: Kayako Cloud rejects attachments over 12MB per file with HTTP 422. When this occurs, the error response body contains file_size_exceeded. Write explicit error-handling to catch HTTP 422 on attachment uploads, drop the oversized file, and append an inline text note to the conversation message body: [Attachment "{filename}" ({size}MB) exceeded Kayako's 12MB limit and was not migrated. Original file archived at {staging_path}.]. Log all dropped attachments to a separate report for post-migration review.

Step 6: Migrate Knowledge Base

Pylon's Knowledge Base API exposes knowledge bases, collections, and articles. Kayako's Help Center uses a three-level hierarchy for Cloud:

• Pylon Knowledge Base → Kayako Help Center Category
• Pylon Collection → Kayako Help Center Section (within a Category)
• Pylon Article → Kayako Help Center Article (within a Section)

Kayako Classic uses a two-level hierarchy (Category → Article) with no intermediate Section. When targeting Classic, you must either flatten the structure (combining Collection context into the Article title) or create placeholder categories per Collection.

Article body content from Pylon is typically HTML or Markdown. Verify rendering in Kayako's preview before bulk import — some HTML constructs that Pylon renders correctly are sanitized by Kayako's Help Center editor.

Step 7: Validate Timestamp Preservation

Before running a full migration, run a timestamp validation test:

1. Create 10 test conversations via the Kayako API with explicit created_at values (e.g., set to 2022-01-01T00:00:00Z).
2. Retrieve those conversations via GET /api/v1/conversations/{id} and check the returned created_at field.
3. If Kayako stores the migration timestamp instead of the value you provided, implement the fallback: store the original Pylon created_at value in a dedicated Kayako conversation custom field (e.g., "Original Created Date") and document this in your team's runbook.

This test takes under 30 minutes and prevents discovering the problem at scale after 20,000 conversations have been created with incorrect timestamps.

Step 8: Execute Delta Sync for Zero-Downtime Cutover

You cannot freeze support operations for the duration of pipeline runtime. A production-grade migration requires:

1. Initial Full Sync: Copy all historical Pylon data up to a specific cutoff timestamp (e.g., Sunday 00:00:00 UTC). Record this timestamp precisely.
2. Validation: QA the data in Kayako (see Step 9). Check field mappings, attachment integrity, and timestamp accuracy on a 5–10% sample.
3. Delta Sync: Query Pylon for issues with updated_at > [Cutoff Timestamp]. This captures new Issues and Messages created or modified during the QA window. Apply the same transform-and-load pipeline.
4. Final Cutover: Update DNS (MX records for email), update email forwarding rules, update customer-facing Help Center links, update any embedded support widgets. Run one final delta sync to capture activity during the cutover window itself (typically minutes to hours depending on DNS propagation).

For a detailed treatment of delta sync methodology, see our guide on Zero-Downtime Help Desk Data Migration.

Step 9: Validate Migrated Data

After loading:

• Spot-check 5–10% of conversations for correct message ordering, attachment accessibility, and custom field values. Weight toward recent issues (high operational relevance) and oldest issues (most likely to have formatting anomalies).
• Verify user-organization associations. Kayako displays Organization context in the conversation sidebar. Broken associations mean agents lose account context during live support — test with actual agent accounts, not admin accounts.
• Confirm tag and custom field integrity. Export a sample from Kayako's API (GET /api/v1/conversations?limit=100) and diff against source data programmatically. Manual spot-checking misses systematic mapping errors.
• Test automation rules. Kayako triggers and monitors are not migrated — they must be rebuilt manually in Kayako Administration → Automations. Validate each rule fires correctly against imported conversations before going live.
• Audit dropped attachments. Review the attachment error log from Step 5. Confirm text notes were appended for all oversized files. Communicate dropped attachments to affected team leads before cutover.

Edge Cases and Failure Modes

Timestamp Preservation

The most common failure mode in help desk migrations is overwriting historical timestamps. Kayako Cloud's conversation creation API does not guarantee historical timestamp preservation via the created_at parameter. This was empirically observed when creating test conversations with created_at set to past dates — Kayako stored the request timestamp instead. Validate this behavior on your specific Kayako instance during Step 7 before running a full migration, since behavior may vary by account configuration or API version.

Pylon Slack Thread Context

Pylon Issues originating from Slack Connect channels contain conversational artifacts — emoji reactions, threaded sub-replies, channel mentions, Slack workflow outputs — that have no representation in Kayako's data model. This context is permanently stripped during migration. If your team relies on Slack thread history for case context, archive the raw Pylon JSON export (per-issue) alongside the Kayako import. Store the archive location in a Kayako conversation custom field (e.g., "Pylon Archive Reference") for retrieval.

Archived Conversations in Kayako

Kayako automatically archives conversations marked as Completed more than 30 days prior. If your Kayako instance has existing data and you import historical Pylon issues as Completed, they will be immediately archived. To retrieve archived conversations via API, append &archived=1 to the cases endpoint query. Document this for your agents — the standard Kayako UI does not display archived conversations by default.

Rate-Limit Math for Large Migrations

For a workspace with 20,000 issues averaging 8 messages per issue:

The 5-day floor assumes: fewer than 10,000 issues, minimal attachments, pre-validated field mapping, and no significant Kayako rate-limit throttling. The 12-day ceiling assumes: 20,000+ issues, heavy attachments, complex custom field structures, and one QA iteration requiring targeted re-imports.

What Cannot Be Migrated

Some Pylon data has no Kayako destination. For each item, the table below identifies what is lost, the downstream operational impact, and the best available workaround.

When to Self-Serve vs. When to Get Help

Self-serve is viable when:

• Fewer than 3,000 issues with simple, flat custom fields (no conditional logic)
• Total attachment volume under 1GB
• No inline images embedded in message bodies
• An engineer available for 40–60 hours to build and debug the pipeline
• Historical timestamp accuracy is not a reporting requirement

A managed migration is justified when:

• 5,000+ issues or heavy attachment volumes (>1GB)
• Complex custom field mapping: multi-select dropdowns, conditional fields, fields with dependent logic
• Historical timestamp preservation is required and you cannot afford trial-and-error API testing
• Migration must run during active support operations (delta sync coordination)
• Knowledge base contains inline images requiring CDN rewrite
• Pylon's 10 req/min rate limit on issues is the bottleneck and you need pipeline optimization to minimize total runtime

The tightest constraints specific to Pylon-to-Kayako migrations are: Pylon's issue rate limit (10 req/min), Pylon's time-limited attachment URLs (must download immediately), and Kayako's undisclosed Cloud rate limits (require adaptive backoff). These three factors, combined with the Slack-to-HTML translation requirement, account for the majority of failures in DIY migrations.