Switch from another helpdesk

This guide assumes the quickstart is done and inbound email works as in Receive email. Contacts, companies and canned replies move over from CSV files. Conversation history moves over as JSON Lines, one conversation per line, once you have mapped the old tool's export to that shape; until then the history stays readable in the old tool.

Run the two tools side by sideCopy Anchor Link

Pick a cutover date. From that date every new conversation starts in Better Helpdesk, and the old tool stays open read-only for 60 to 90 days, so an agent can look up what a customer said last month. Once support@ points here, a reply to an old thread arrives as a new conversation; the earlier messages are in the old tool.

Import contacts, companies and canned repliesCopy Anchor Link

Export what you have as CSV and run the import CLI against the same database as the migrations:

HELPDESK_DATABASE_URL=postgres://… npx better-helpdesk-import contacts people.csv
HELPDESK_DATABASE_URL=postgres://… npx better-helpdesk-import canned replies.csv

It prints how many rows it created, updated and left alone, and a line for each value it had to leave out. The file needs a header row, and column names are read without regard to case. A quote that is never closed stops the import with its line number, before anything is written.

A contacts file needs an email column and may add name, tags, lead_stage, and the company as domain or company. A canned replies file needs title and body, and may add locale. CLI lists every column and its limits.

A missing company is created; an existing one is never renamed, and only gains a domain it did not have. The lead stages are the defaults, lead, qualified, customer and churned, unless you set leadStages in your config; then pass the same list:

npx better-helpdesk-import contacts people.csv --lead-stages Lead,Trial,Customer

When an agent inserts a canned reply, {firstName} and {reference} in it are filled in. Rewrite the old tool's placeholders to those two.

Running the import again is safe, also after agents have started working. A contact whose email is already known only gains what it lacks: empty fields are filled and tags are added, and nothing an agent changed is undone. A canned reply whose title and locale exist is left alone. So fix the export and run the whole file again.

An imported contact is not linked to anyone's login. When the same person later writes in or signs in, they may arrive as a second contact; open the older one and use Merge another contact into this one.

Import conversation historyCopy Anchor Link

The old tool's threads can come along as conversations of their own. Write a script that turns its export into one JSON object per line in the export format, then import the file:

HELPDESK_DATABASE_URL=postgres://… npx better-helpdesk-import conversations history.jsonl --source Freshdesk

Each line needs the inbox and type it should land in, when it was opened, the customer by email, and its messages with their authors and times. People are matched by email, so a customer who later writes in lands on the same contact. Agents are matched by email to your team; a message from someone who is not on it stays an agent message without a name. The old reference and the --source are kept with the conversation, so an agent can still quote the old number. Attachments are not imported: keep the old tool's files where they are, or copy them into your storage and link them from a note. Run the import once; running it again opens every conversation a second time.

better-helpdesk-export writes the same format, so the next tool can take over from this one the same way.

Move each tool overCopy Anchor Link