Browse docs

From HelpSpot

Beta

The HelpSpot ticket importer in workspace settings

Overview

The HelpSpot importer reads tickets through HelpSpot's private API and adds them to one There There email channel. It imports ticket details, messages, notes, recipients, staff attribution, and attachments. It does not send any email to customers or external contacts.

Create a HelpSpot API token

  1. In HelpSpot, go to Admin → Settings → Web Services API and enable the private API.
  2. Choose a staff member that can read every category and ticket you want to import. The token receives the same rights as this staff member.
  3. Open that staff member's profile, scroll to API authentication tokens, enter a name such as There There import, and select Issue New Token.
  4. Copy the token and keep it somewhere safe until you start the import.

HelpSpot documents these steps under Private API authentication. You do not need to give There There the staff member's username or password.

Start the import

Open Settings → Import tickets → HelpSpot in There There, then enter:

  • HelpSpot installation URL: the HTTPS address where you open HelpSpot, such as https://support.example.com or your HelpSpot Cloud address. Do not add /api/index.php.
  • API token: the token created in HelpSpot.
  • Channel: the There There email channel that should receive the tickets.
  • Ticket limit: optional. Leave this empty to import every ticket returned by HelpSpot. A small limit is useful for a first test.
  • Import all tickets as closed: optional. Select this if you do not want imported open tickets to appear in your inbox.

There There checks the connection before creating an import. It does not show the installation URL or token again after submission. Both values are encrypted while the import is active and deleted when it completes, fails, or is cancelled.

API calls made by the importer

The importer uses these read-only private API calls:

Call Why it is needed
private.version Confirms that the token can access the private API.
private.request.search Finds ticket identifiers in newest-first pages.
private.request.getStatusTypes Finds the status that HelpSpot identifies as Spam without relying on a fixed status identifier.
private.util.getAllStaff Reads current and historical staff names and email addresses so ticket assignees and authors can be matched.
private.request.get Reads the complete ticket and request history for one xRequest.
private.document.get Downloads one normal or inline attachment by xDocumentId.

The HelpSpot API field definitions explain the property names returned by these calls.

Ticket and message mapping

HelpSpot data There There result
xRequest Stable source identifier used to prevent duplicate tickets.
sTitle Ticket subject.
sEmail, sFirstName, sLastName, fullname Customer email and name. A ticket without a valid customer email is skipped with a warning.
fOpen, dtGMTOpened, dtGMTClosed Open or closed status and original timestamps. The force-closed option overrides fOpen.
xStatus Compared with the Spam status found during connection checks. A matching request is skipped; other status identifiers are not treated as Spam.
xPersonAssignedTo Assignee, matched to a There There member by the current or historical HelpSpot staff email address. If no member matches, the ticket stays unassigned.
request_history.item Customer messages, staff replies, internal notes, and External messages, ordered by dtGMTChange. Empty entries, request-change logs, and EMAIL ERROR: system entries are skipped.
xPerson on a history item Message author. 0 means the customer. Other values are matched through the safe staff map.
fPublic Public customer entries become inbound messages, public staff entries become outbound messages, and non-public entries become notes. External entries also remain notes because they are not visible to the customer in HelpSpot.
to, cc, bcc Message recipients. The importer uses these dedicated fields, not tEmailHeaders. HelpSpot added them to request history in HelpSpot 5.6.10.

If a HelpSpot staff email matches a There There workspace member, that member becomes the author or assignee. Otherwise, the imported message keeps the available HelpSpot author name and email, while the ticket remains unassigned when no matching assignee exists.

Attachments

Every file listed on a request history item is downloaded separately with private.document.get.

  • Normal attachments keep their safe filename and are stored privately on the imported message.
  • Inline images use sCID to match the image in the message HTML. Matching images are rewritten to the private stored attachment and shown inline.
  • Attachment size, filename, extension, MIME type, and storage checks are the same as for normal There There email attachments.
  • A missing, unsafe, invalid, or oversized attachment is skipped. The ticket and its other attachments continue importing, and the warning download explains what was skipped.
  • If an inline cid: reference does not match a HelpSpot document, the original reference stays in the message and a warning is recorded.

Discovery and safe reruns

Ticket discovery calls private.request.search in newest-first pages. With the default page size, the calls use start=0&length=100, then start=100&length=100, and continue until HelpSpot returns a short page. Each discovered xRequest is then loaded and imported one at a time.

The search reads a live list, not a saved snapshot. New HelpSpot activity during discovery can move tickets between pages. Running the importer again is safe: the installation fingerprint plus HelpSpot request, history, and document identifiers prevent imported tickets, messages, and attachments from being duplicated. A rerun can therefore collect an eligible ticket that moved during an earlier discovery.

Progress, warnings, and cancellation

The imports page shows the same ticket and attachment progress used by the other importers. If an item cannot be imported safely, the run records a warning that you can download as a CSV file.

Cancelling stops the import after the current ticket finishes. Tickets and messages already imported stay in the selected channel. The remaining tickets are not processed, and the stored HelpSpot connection details are deleted.

First-version limits

  • HelpSpot's paginated request search does not return tickets in Spam or Trash. Move any ticket you need out of Spam or Trash before starting the import.
  • A ticket without a valid customer email cannot become a There There ticket and is skipped with a warning.
  • HelpSpot request-change log entries and generated EMAIL ERROR: entries are not imported as messages.
  • HelpSpot custom fields, categories, reporting tags, time tracking, and prepared responses are not imported.
  • The importer reads data only. It does not change HelpSpot and does not send messages.