Importing from Zendesk

Prerequisites

• A Zendesk account with Admin role
• A Zendesk API token (see below)
• Your Zendesk subdomain (the part before .zendesk.com, e.g. acme)

Generating a Zendesk API token

1. In Zendesk, go to Admin Center → Apps and Integrations → APIs → Zendesk API.
2. Under Token Access, enable API token access if it is not already on.
3. Click Add API token, give it a description, and copy the token.

Note: The token is only shown once. Store it securely before closing the dialog.

Using the import wizard

1. In Escalated, go to Admin → Import and select Zendesk.
2. Enter your subdomain, admin email address, and API token, then click Test connection.
3. Review the field mappings. Defaults are pre-filled (see table below). Adjust any mappings you want to change.
4. Click Start import. The wizard moves to a progress view showing each entity type as it is processed.

The import fetches entity types in dependency order: agents → tags → custom fields → departments → contacts → tickets → replies → attachments.

Using the CLI

php artisan escalated:import zendesk

You will be prompted for your subdomain, admin email, and API token. Pass --no-interaction to read credentials from environment variables instead:

ESCALATED_IMPORT_ZENDESK_SUBDOMAIN=acme \
ESCALATED_IMPORT_ZENDESK_EMAIL=admin@example.com \
ESCALATED_IMPORT_ZENDESK_TOKEN=your-api-token \
php artisan escalated:import zendesk --no-interaction

Default field mappings

Zendesk field	Escalated field
subject	title
status	status
priority	priority
assignee_id	assigned_to
requester_id	requester
group_id	department
tags	tags

Status mapping

Zendesk status	Escalated status
new	open
open	in_progress
pending	waiting_on_customer
hold	waiting_on_agent
solved	resolved
closed	closed

Priority mapping

Zendesk priority	Escalated priority
low	low
normal	medium
high	high
urgent	urgent

Resuming a failed import

If an import job is interrupted (server restart, timeout, etc.), you can resume it from Admin → Import by clicking Resume next to the failed job. The adapter uses cursor-based pagination, so it picks up from the last successfully processed batch without re-importing records.

From the CLI, pass the job ID:

php artisan escalated:import zendesk --resume=<job-id>

Troubleshooting

"Authentication failed" on test connection Confirm that your email is entered in the form admin@example.com (not admin@example.com/token) and that Token Access is enabled in Zendesk Admin Center.

Tickets are missing Zendesk's incremental export API only returns tickets updated since epoch 0. Deleted tickets are excluded. Archived tickets in Zendesk's long-term storage may not appear in the incremental export.

Rate limit errors during import The adapter backs off automatically on HTTP 429 responses, respecting the Retry-After header. If you see persistent throttling, contact Zendesk support to request a temporary rate limit increase.

Custom field values are not imported Only non-system custom fields are imported. System fields (subject, description, status, priority, group, assignee) are mapped directly and are not surfaced as custom fields.

Importing from Freshdesk

Prerequisites

• A Freshdesk account on the Growth plan or above (API access is not available on the free Sprout plan)
• A Freshdesk API key (see below)
• Your Freshdesk domain (the part before .freshdesk.com, e.g. acme)

Finding your Freshdesk API key

1. Log in to Freshdesk as an agent with admin permissions.
2. Click your avatar in the top-right corner and select Profile Settings.
3. Your API key is shown in the right-hand panel under Your API Key.

Note: The API key is tied to the agent account you are logged in as. Use an admin account to ensure the importer has access to all tickets and groups.

Using the import wizard

1. In Escalated, go to Admin → Import and select Freshdesk.
2. Enter your domain and API key, then click Test connection.
3. Review the field mappings. Defaults are pre-filled (see table below). Adjust any mappings you want to change.
4. Click Start import. The wizard moves to a progress view showing each entity type as it is processed.

The import fetches entity types in dependency order: agents → custom fields → departments → contacts → tickets → replies → attachments.

Note: Freshdesk does not have a dedicated tags endpoint. Tags are collected from ticket records during ticket extraction and written as a separate entity type automatically — no manual step is needed.

Using the CLI

php artisan escalated:import freshdesk

You will be prompted for your domain and API key. Pass --no-interaction to read credentials from environment variables instead:

ESCALATED_IMPORT_FRESHDESK_DOMAIN=acme \
ESCALATED_IMPORT_FRESHDESK_API_KEY=your-api-key \
php artisan escalated:import freshdesk --no-interaction

Default field mappings

Freshdesk field	Escalated field
subject	title
description	body
status	status
priority	priority
responder_id	assigned_to
requester_id	requester
group_id	department
tags	tags

Status mapping

Freshdesk status (code)	Escalated status
2 (Open)	open
3 (Pending)	waiting_on_customer
4 (Resolved)	resolved
5 (Closed)	closed

Priority mapping

Freshdesk priority (code)	Escalated priority
1 (Low)	low
2 (Medium)	medium
3 (High)	high
4 (Urgent)	urgent

Page 300 limit and adaptive date windowing

Freshdesk's ticket list API has a hard limit of 300 pages (30,000 records) per query. For accounts with large ticket histories, the adapter works around this limit automatically using adaptive date windowing:

1. The adapter splits the full ticket history into 30-day windows starting from 2010-01-01.
2. Within each window it pages through tickets filtered by updated_since.
3. If a window fills all 300 pages, it is automatically split in half and re-paged from the midpoint. This process repeats recursively until the window is small enough to fit within the page limit.

No configuration is required. The process is transparent and progress is tracked in the import job so it can be resumed if interrupted.

Resuming a failed import

If an import job is interrupted, you can resume it from Admin → Import by clicking Resume next to the failed job. The adapter's cursor format encodes the current date window and page number, so it resumes from the exact point of failure.

From the CLI:

php artisan escalated:import freshdesk --resume=<job-id>

Troubleshooting

"Authentication failed" on test connection Verify the API key in your Freshdesk Profile Settings. Make sure you are using an admin account — agent-only accounts may not have access to all resources.

"API access not available" error API access requires the Growth plan or above. Upgrade your Freshdesk subscription or contact Freshdesk support.

Tickets appear to be missing The adapter imports tickets ordered by updated_at ascending within each date window. Tickets that have never been updated since creation may fall in an earlier window than expected. If specific tickets are missing, verify they exist in Freshdesk and have not been deleted.

Attachment download URLs expire Freshdesk returns temporary signed URLs for attachments. If a download fails, the framework automatically re-fetches the parent conversation to obtain a fresh URL before retrying.

Importing from Help Scout

Prerequisites

• A Help Scout account with access to My Apps (any paid plan)
• An OAuth app created in Help Scout with an App ID and App Secret (see below)

Creating a Help Scout OAuth app

1. In Help Scout, click your avatar in the top-right corner and select Your Profile.
2. In the left sidebar, click My Apps, then click Create My App.
3. Give the app a name (e.g. "Escalated Import"), enter any valid redirect URL (not used for this flow), and click Create.
4. Copy the App ID and App Secret shown on the app detail page.

The adapter uses the OAuth 2.0 client credentials grant, so no browser redirect or user interaction is required during the import. The App ID and App Secret are used directly.

Using the import wizard

1. In Escalated, go to Admin → Import and select Help Scout.
2. Enter your App ID and App Secret, then click Test connection.
3. Review the field mappings. Defaults are pre-filled (see table below). Adjust any mappings you want to change.
4. Click Start import. The wizard moves to a progress view showing each entity type as it is processed.

The import fetches entity types in dependency order: agents → tags → departments (mailboxes) → contacts → tickets (conversations) → replies (threads) → attachments.

Using the CLI

php artisan escalated:import helpscout

You will be prompted for your App ID and App Secret. Pass --no-interaction to read credentials from environment variables instead:

ESCALATED_IMPORT_HELPSCOUT_APP_ID=your-app-id \
ESCALATED_IMPORT_HELPSCOUT_APP_SECRET=your-app-secret \
php artisan escalated:import helpscout --no-interaction

Default field mappings

Help Scout field	Escalated field
subject	title
status	status
assignee	assigned_to
primaryCustomer	requester
mailboxId	department
tags	tags

Status mapping

Help Scout status	Escalated status
active	open
pending	waiting_on_customer
closed	closed
spam	closed

Note: Help Scout does not have a ticket priority field. All imported tickets are assigned medium priority by default. You can update priorities in bulk after the import using Escalated's bulk actions.

Rate limits

Help Scout's API allows 200 requests per minute. The adapter respects Retry-After headers on HTTP 429 responses and backs off automatically. Large accounts with tens of thousands of conversations may take longer to import than accounts on higher-rate-limit platforms. Plan accordingly and avoid running other API-heavy integrations concurrently during the import.

Resuming a failed import

If an import job is interrupted, you can resume it from Admin → Import by clicking Resume next to the failed job.

From the CLI:

php artisan escalated:import helpscout --resume=<job-id>

Troubleshooting

"Authentication failed" on test connection Confirm the App ID and App Secret are copied exactly as shown in Help Scout My Apps. Note that App ID is distinct from App Secret — double-check you have not swapped the two values.

Some conversations are missing Help Scout's conversations endpoint returns active, pending, and closed conversations. Spam conversations are imported as closed. Deleted conversations are not returned by the API and cannot be recovered.

Merged conversations appear as a 301 redirect When a conversation has been merged in Help Scout, the API returns a 301 redirect to the surviving conversation. The adapter follows redirects automatically; merged conversations will not appear as duplicates.

Thread types other than messages and notes are not imported The adapter only imports thread types that carry content: message, customer, and note. System thread types (reassign, move, lineitem, forward, phone, chat) are skipped.

Importing from Intercom

Prerequisites

• An Intercom workspace with Developer Hub access
• A Bearer token generated from your Intercom app (see below)
• The app must have the following permission scopes granted

Required permission scopes

Scope	Why it is needed
Read admins	Import agents
Read conversations	Import tickets (conversations) and replies
Read contacts	Import contacts
Read tags	Import tags
Read teams	Import departments (teams)

Generating a Bearer token

1. Go to the Intercom Developer Hub.
2. Click New app (or open an existing app you have created for integrations).
3. Under Authentication, select Use access token.
4. Grant the permission scopes listed above.
5. Copy the Access token shown at the top of the Authentication page.

Note: The access token has the same permissions as the workspace admin who created it. Use a dedicated app to keep the token's scope minimal.

Using the import wizard

1. In Escalated, go to Admin → Import and select Intercom.
2. Enter your access token, then click Test connection.
3. Review the field mappings. Defaults are pre-filled (see table below). Adjust any mappings you want to change.
4. Click Start import. The wizard moves to a progress view showing each entity type as it is processed.

The import fetches entity types in dependency order: agents → tags → departments (teams) → contacts → tickets (conversations) → replies (conversation parts) → attachments.

Using the CLI

php artisan escalated:import intercom

You will be prompted for your access token. Pass --no-interaction to read credentials from environment variables instead:

ESCALATED_IMPORT_INTERCOM_TOKEN=your-access-token \
php artisan escalated:import intercom --no-interaction

Default field mappings

Intercom field	Escalated field
title (or first message excerpt)	title
state	status
priority	priority
assignee (admin only)	assigned_to
contacts (first contact)	requester
team_assignee_id	department
tags	tags

Status mapping

Intercom state	Escalated status
open	open
closed	closed
snoozed	waiting_on_agent

Priority mapping

Intercom priority	Escalated priority
not_priority	medium
priority	high

Conversation titles

Intercom conversations do not always have an explicit title. When no title is set, the adapter uses the first 100 characters of the source message body (HTML stripped) as the ticket title.

Rate limits

Intercom allows 1,000 requests per minute, which is generous compared to most helpdesk APIs. The adapter distributes requests evenly across 10-second windows and backs off automatically on HTTP 429 responses. Even very large Intercom workspaces typically import without significant throttling delays.

Resuming a failed import

If an import job is interrupted, you can resume it from Admin → Import by clicking Resume next to the failed job.

From the CLI:

php artisan escalated:import intercom --resume=<job-id>

Troubleshooting

"Authentication failed" on test connection Confirm the access token is correct and that the app has not been deleted or had its access token rotated in the Developer Hub.

Missing permission scope error If the test connection succeeds but certain entity types fail to import, the access token may be missing a required scope. Return to the Developer Hub, add the missing scope, and regenerate the token.

Conversation parts are missing The adapter only imports content-bearing conversation parts: comment and note. Administrative event parts (assignment, open, close, snooze, etc.) are intentionally skipped.

Attachment download URLs expire Intercom attachment URLs are temporary signed URLs. If a download fails due to expiry, the framework re-fetches the parent conversation part to obtain a fresh URL before retrying.

Contacts show as "user" or "lead" — which is imported? Intercom's API v2 unifies leads and users into a single contacts resource. Both roles are imported and mapped to Escalated contacts. The role value (user or lead) is stored in the contact's metadata.

Building an Import Adapter

This guide is for plugin developers who want to add import support for a new source platform.

The ImportAdapter interface

Your adapter class must implement Escalated\Laravel\Contracts\ImportAdapter:

interface ImportAdapter
{
    /** Unique slug, e.g. "zendesk" */
    public function name(): string;

    /** Human-readable name, e.g. "Zendesk" */
    public function displayName(): string;

    /**
     * Fields required for authentication.
     * Each element: ['name' => string, 'label' => string, 'type' => 'text'|'password'|'url', 'help' => string]
     */
    public function credentialFields(): array;

    /** Validate credentials by making a test API call. */
    public function testConnection(array $credentials): bool;

    /** Ordered list of importable entity types. */
    public function entityTypes(): array;

    /** Default field mappings for an entity type. */
    public function defaultFieldMappings(string $entityType): array;

    /** Available source fields for an entity type (fetched from API using credentials). */
    public function availableSourceFields(string $entityType, array $credentials): array;

    /** Extract a batch of records. Returns null cursor in ExtractResult when exhausted. */
    public function extract(string $entityType, array $credentials, ?string $cursor): ExtractResult;
}

ExtractResult format

Every call to extract() must return an ExtractResult:

class ExtractResult
{
    public function __construct(
        /** Normalized records as associative arrays */
        public readonly array $records,
        /** Next cursor value, null when exhausted */
        public readonly ?string $cursor,
        /** Estimated total records, if available from API */
        public readonly ?int $totalCount = null,
    ) {}
}

Return null for $cursor to signal that the entity type is fully extracted. The framework will then move on to the next entity type in the list returned by entityTypes().

Registering the adapter

In your plugin's Plugin.php, register your adapter using the import.adapters filter hook:

use YourNamespace\YourImportAdapter;

escalated_add_filter('import.adapters', function (array $adapters) {
    $adapters[] = new YourImportAdapter();
    return $adapters;
}, 10);

The framework collects all registered adapters and makes them available in the import wizard and CLI.

Entity types and dependency order

Return entity types from entityTypes() in dependency order. The framework imports them in the order you specify; later types can rely on earlier types already being in the database.

Recommended order:

public function entityTypes(): array
{
    return ['agents', 'tags', 'custom_fields', 'departments', 'contacts', 'tickets', 'replies', 'attachments'];
}

Not all entity types are required. Omit any that your source platform does not support. For example, if the platform has no custom fields, leave 'custom_fields' out.

Cursor-based pagination pattern

The extract() method is called repeatedly by the framework until cursor is null. Your adapter decides the cursor format — it just needs to be a string that encodes enough state to resume the next batch.

Simple page-number cursor:

public function extract(string $entityType, array $credentials, ?string $cursor): ExtractResult
{
    $page = $cursor !== null ? (int) $cursor : 1;

    $data = $this->client->getPage($entityType, $page);

    $records = array_map([$this, 'normalize'], $data['items'] ?? []);
    $nextCursor = count($data['items'] ?? []) > 0 ? (string) ($page + 1) : null;

    return new ExtractResult($records, $nextCursor, $data['total'] ?? null);
}

For replies that must be fetched per-ticket, use a compound cursor. See the Zendesk adapter for an example using the idx:N / tid:TICKET_ID|PAGE_URL pattern, and the ImportSourceMap model to iterate over already-imported ticket IDs.

Normalized record formats

All records are plain associative arrays. The required keys for each entity type are described below.

agents

[
    'source_id' => '12345',        // string — ID in the source system
    'name'      => 'Jane Doe',
    'email'     => 'jane@example.com',
    'role'      => 'agent',        // 'agent' or 'admin'
]

tags

[
    'source_id' => 'billing',      // string — often the tag name itself
    'name'      => 'billing',
]

custom_fields

[
    'source_id' => '67890',
    'name'      => 'Account tier',
    'type'      => 'select',       // text | textarea | number | checkbox | date | select | multiselect
    'options'   => ['Free', 'Pro', 'Enterprise'],  // for select/multiselect only
]

departments

[
    'source_id' => '111',
    'name'      => 'Billing',
]

contacts

[
    'source_id' => '222',
    'name'      => 'John Smith',
    'email'     => 'john@example.com',
]

tickets

[
    'source_id'            => '333',
    'title'                => 'Cannot log in',
    'status'               => 'open',              // open | in_progress | waiting_on_customer | waiting_on_agent | resolved | closed
    'priority'             => 'medium',            // low | medium | high | urgent
    'requester_source_id'  => '222',               // contacts source_id
    'assignee_source_id'   => '12345',             // agents source_id
    'department_source_id' => '111',               // departments source_id
    'tag_source_ids'       => ['billing'],         // array of tags source_ids
    'metadata'             => [],                  // arbitrary key/value preserved as-is
    'created_at'           => '2024-01-15T10:00:00Z',
    'updated_at'           => '2024-01-16T08:30:00Z',
]

replies

[
    'source_id'        => '444',
    'ticket_source_id' => '333',    // tickets source_id
    'body'             => '<p>Hello, please reset your password.</p>',
    'is_internal_note' => false,    // true for private/internal notes
    'author_source_id' => '12345',  // agents source_id (null if written by a contact)
    'created_at'       => '2024-01-15T10:05:00Z',
    'updated_at'       => '2024-01-15T10:05:00Z',
]

attachments

[
    'source_id'        => '555',
    'parent_type'      => 'reply',     // 'ticket' or 'reply'
    'parent_source_id' => '444',       // the source_id of the parent ticket or reply
    'filename'         => 'screenshot.png',
    'mime_type'        => 'image/png',
    'size'             => 204800,      // bytes
    'download_url'     => 'https://...',
]

The framework downloads and stores attachments using the download_url. If the URL is a temporary signed URL, ensure your adapter fetches attachments while the URL is still valid, or implement re-fetch logic in your extraction loop.