Skip to main content

Intercom

This page contains the setup guide and reference information for the Intercom source connector.

Prerequisites​

  • An Intercom account with the data you want to replicate.
  • An Intercom app with the required permissions. The connector needs read access to the data you want to sync. At minimum, grant these permissions in the Developer Hub:
    • Read and list users and companies—required for Companies, Company Segments, Company Attributes, Contact Attributes, Contacts, Segments, and Teams.
    • Read conversations—required for Conversations and Conversation Parts.
    • Read admins—required for Admins.
    • Read admin activity logs—required for Activity Logs.
    • Read tags—required for Tags.
    • Read Tickets—required for Tickets. This permission is optional: if it is not granted, the Tickets stream is silently skipped during syncs.
  • A Start date in UTC format (YYYY-MM-DDTHH:mm:ssZ). Only data created on or after this date is replicated.

Setup guide​

Set up Intercom​

Obtain an Intercom access token (Calabi Connect)​

To authenticate the connector in Calabi Connect, you need an access token. Follow the steps below to create an Intercom app and generate the token. For more information on Intercom's authentication flow, refer to the official documentation.

  1. Log in to your Intercom account and navigate to the Developer Hub.
  2. Click Your apps in the top-right corner, then click New app.
  3. Choose an App name, select your Workspace from the dropdown, and click Create app.
  4. To set the appropriate permissions, from the Authentication tab, click Edit in the top right corner and check the permissions you want to grant to the app. Grant only read permissions (not write). Click Save when you are finished.
  5. Under the Access token header, you will be prompted to regenerate your access token. Follow the instructions to do so, and copy the new token.

Set up the Intercom connector in Calabi Connect​

For Calabi Connect:​

  1. Log into your Calabi Connect account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Intercom from the Source type dropdown.
  4. Enter a name for the Intercom connector.
  5. To authenticate:

For Calabi Connect:​

  1. Navigate to the Calabi Connect dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Intercom from the Source type dropdown.
  4. Enter a name for the Intercom connector.
  • For Calabi Connect, click Authenticate your Intercom account. When the pop-up appears, select the appropriate workspace from the dropdown and click Authorize access.
  • For Calabi Connect, enter your access token to authenticate your account.
  1. For Start date, use the provided datepicker or enter a UTC date and time in the format YYYY-MM-DDTHH:mm:ssZ. Only data created on or after this date is replicated.
  2. Optionally, configure Lookback window to re-sync records updated within the specified number of days before the current cursor position. This helps capture late-arriving updates. The default is 0 (no lookback).
  3. Optionally, configure Activity logs stream slice step size to control how many days of activity log data the connector fetches per request. The default is 30 days. Lower this value if you experience timeouts on the Activity Logs stream.
  4. Optionally, configure Num Workers to set the number of worker threads for concurrent stream processing. The default is 10 (max 40). Increase this to speed up syncs for workspaces with large volumes of conversations.
  5. Optionally, configure API Rate Limit to set the effective API request budget per minute. The default is 9500 (95% of the standard 10,000/min Intercom limit). If your workspace has a higher rate limit (e.g. 150,000/min), set this to ~95% of that value to leverage your full API throughput.
  6. Click Set up source and wait for the tests to complete.

Supported sync modes​

The Intercom source connector supports the following sync modes:

  • Full Refresh
  • Incremental

Supported streams​

The Intercom source connector supports the following streams:

Performance considerations​

The connector is restricted by normal Intercom rate limits. The default rate limit is 1,000 API calls per minute for public apps and 10,000 API calls per minute for private apps, with a workspace-level cap of 25,000 API calls per minute. The connector monitors the X-RateLimit-Remaining header and proactively throttles itself before hitting the API rate limit, trading sync speed for stability. If the API returns a 429 Too Many Requests response, the connector retries automatically.

The connector uses an API Rate Limit setting (default: 9500 requests per minute) to control its request budget. A per-10-second window is derived automatically (api_rate_limit / 6). If your Intercom workspace has an elevated rate limit (e.g. 150,000/min), increase this value to allow the connector to use your full API throughput.

The connector also supports configurable concurrency via the Num Workers setting (default: 10, max: 40). This controls how many partition slices are processed in parallel, which is especially beneficial for substream-based streams like conversation_parts and company_segments.

The connector should not run into rate limit issues under normal usage. Create an issue if you see rate limit errors that are not automatically retried.

Troubleshooting and limitations​

Companies and Company Segments use client-side incremental sync​

The Companies and Company Segments streams rely on the Scroll over all companies endpoint, which does not support server-side datetime filtering. Incremental sync for these streams works by fetching all records from the API and filtering locally, emitting only the records that are newer than the last sync checkpoint.

This means that even if you only need one day of new data, the connector must read all company records from the beginning before it can identify and emit the new ones. For workspaces with a large number of companies, this can result in long sync times.

Only one scroll can be open per app at a time​

The Intercom API allows only one company scroll to be open per app at a time. If a second scroll request is made while one is already active, the API returns a 400 error with the message "scroll already exists for this workspace." The connector retries this error automatically with a one-minute backoff, since scrolls expire after one minute of inactivity.

To prevent conflicts, the connector blocks simultaneous reads from the Companies endpoint. If you run multiple connections that sync the Companies or Company Segments streams from the same Intercom workspace, the connector queues the reads so only one scroll is active at a time.

Recommendation for reducing sync times​

Because these streams must read all records on every sync, syncing Companies and Company Segments alongside other streams in the same connection can increase the total sync duration for that connection. To avoid this, sync the Companies and Company Segments streams in a separate connection from your other Intercom streams.