ContextQMD
Back to Airbyte

Intercom

docs/integrations/sources/intercom.md

2.0.030.8 KB
Original Source

Intercom

<HideInUI>

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

</HideInUI>

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

<!-- env:oss -->

Obtain an Intercom access token (Airbyte Open Source)

To authenticate the connector in Airbyte Open Source, you will need to obtain an access token. You can follow the setup 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. We recommend only granting 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.
<!-- /env:oss -->

Set up the Intercom connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud 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:
<!-- env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source 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.
<!-- /env:oss -->
  • For Airbyte Cloud, click Authenticate your Intercom account. When the pop-up appears, select the appropriate workspace from the dropdown and click Authorize access. <!-- /env:cloud --> <!-- env:oss -->
  • For Airbyte Open Source, enter your access token to authenticate your account.
<!-- /env:oss -->
  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. 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 requests per minute for public apps and 10,000 requests per minute for private apps. 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 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.

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
0.13.16-rc.62026-03-1975216Bump CDK base image to 7.13.0 (includes block_simultaneous_read support and cursor field fix)
0.13.16-rc.52026-03-1171141Block simultaneous reading from companies endpoint
0.13.16-rc.42026-03-0374143fix(source-intercom): fix UnboundLocalError in rate limiter when response is not available
0.13.16-rc.32026-03-0372955fix(source-intercom): add step size and end_datetime to contacts, conversations, and activity_logs streams
0.13.16-rc.22026-02-1873635fix(source-intercom): bump heartbeat timeout from 6h to 9h
0.13.16-rc.12025-12-1170335Fix pagination on companies stream
0.13.152025-11-2569563Update dependencies
0.13.142025-11-1969306Update custom IntercomScrollRetriever to not use deprecated stream_state parameter
0.13.132025-10-2968767Update dependencies
0.13.122025-10-2168477Update dependencies
0.13.112025-10-1467933Update dependencies
0.13.102025-10-0767364Update dependencies
0.13.92025-10-0667104Increase Heartbeat Timeout to Account for cursor based streams with client side incremental and large record counts for a given day.
0.13.82025-09-3066789Update dependencies
0.13.72025-09-2666665Fix Typo on Error Message
0.13.62025-09-0966056Update dependencies
0.13.52025-08-2365374Update dependencies
0.13.42025-08-0963523Update dependencies
0.13.32025-07-1263155Update dependencies
0.13.22025-07-0562592Update dependencies
0.13.12025-06-2854308Update dependencies
0.13.02025-06-2562069Promoting release candidate 0.13.0-rc.5 to a main version.
0.13.0-rc.52025-06-1161506Add better error handling for companies stream, update SDM, & add advanced_auth
0.13.0-rc.42025-05-1560235Add required custom paginator for 'companies' stream & Fix 500s on Tickets stream.
0.13.0-rc.32025-05-0955829Fix pagination for conversations, tickets, companies & contacts and cleanup manifest
0.13.0-rc.22025-04-0857524Use global state and pass state to parent streams for conversation_parts and company_segments
0.13.0-rc.12025-02-2253187Update with latest CDK features, remove custom incremental sync components, update schema for conversation_parts
0.12.22025-02-1553835Update dependencies
0.12.12025-02-0853257Update dependencies
0.12.02025-02-0352687New stream Tickets
0.11.02025-02-0351619Upgrade API version to 2.11, add ai_agent_participated and ai_agent fields conversations stream schema
0.10.12025-02-0149212Update dependencies
0.10.02025-01-2452132Fix incremental sync
0.9.02025-01-1551570Promoting release candidate 0.9.0-rc.2 to a main version.
0.9.0-rc.22025-01-1349936Incremental substream fixes
0.9.0-rc.12024-12-1747240Migrate to manifest-only format
0.8.32024-12-1248979Update dependencies
0.8.22024-10-2947919Update dependencies
0.8.12024-10-2847537Update dependencies
0.8.02024-10-2346658Add lookback_window to the source specification
0.7.52024-10-2147120Update dependencies
0.7.42024-10-1246831Update dependencies
0.7.32024-10-0546447Update dependencies
0.7.22024-09-2845279Update dependencies
0.7.12024-08-3144966Update dependencies
0.7.02024-08-2944911Migrate to CDK v4
0.6.212024-08-2444672Update dependencies
0.6.202024-08-1744296Update dependencies
0.6.192024-08-1243878Update dependencies
0.6.182024-08-1043500Update dependencies
0.6.172024-08-0343276Update dependencies
0.6.162024-07-2942094Use latest CDK, raise config error on Active subscription needed error and transient errors for Companies stream.
0.6.152024-07-2742654Update dependencies
0.6.142024-07-2042262Update dependencies
0.6.132024-07-1341712Update dependencies
0.6.122024-07-1041356Update dependencies
0.6.112024-07-0941112Update dependencies
0.6.102024-07-0640878Update dependencies
0.6.92024-06-2540428Update dependencies
0.6.82024-06-2239951Update dependencies
0.6.72024-06-0639286[autopull] Upgrade base image to v1.2.2
0.6.62024-05-2438626Add step granularity for activity logs stream
0.6.52024-04-1936644Updating to 0.80.0 CDK
0.6.42024-04-1236644Schema descriptions
0.6.32024-03-2336414Fixed pagination regression bug for conversations stream
0.6.22024-03-2236277Fixed the bug for conversations stream failed due to 404 - User Not Found, when the 2.10 API version is used
0.6.12024-03-1836232Fixed the bug caused the regression when setting the Intercom-Version header, updated the source to use the latest CDK version
0.6.02024-02-1235176Update the connector to use 2.10 API version
0.5.12024-02-1235148Manage dependencies with Poetry
0.5.02024-02-0935063Add missing fields for mutiple streams
0.4.02024-01-1133882Add new stream Activity Logs
0.3.22023-12-0733223Ignore 404 error for Conversation Parts
0.3.12023-10-1931599Base image migration: remove Dockerfile and use the python-connector-base image
0.3.02023-05-2529598Update custom components to make them compatible with latest cdk version, simplify logic, update schemas
0.2.12023-05-2526571Remove authSpecification from spec.json in favour of advancedAuth
0.2.02023-04-0523013Migrated to Low-code (YAML Frramework)
0.1.332023-03-2022980Specified date formatting in specification
0.1.322023-02-2722095Extended Contacts schema adding opted_out_subscription_types property
0.1.312023-02-1723152Add TypeTransformer to stream companies
0.1.302023-01-2722010Set AvailabilityStrategy for streams explicitly to None
0.1.292022-10-3118681Define correct version for airbyte-cdk~=0.2
0.1.282022-10-2018216Use airbyte-cdk~=0.2.0 with SQLite caching
0.1.272022-08-2817326Migrate to per-stream states
0.1.262022-08-1816540Fix JSON schema
0.1.252022-08-1815681Update Intercom API to v 2.5
0.1.242022-07-2114924Remove additionalProperties field from schemas
0.1.232022-07-1914830Added checkpoint_interval for Incremental streams
0.1.222022-07-0914554Fixed conversation_parts stream schema definition
0.1.212022-07-0514403Refactored Conversations, Conversation Parts, Company Segments to increase performance
0.1.202022-06-2414099Extended Contacts stream schema with sms_consent,unsubscribe_from_sms properties
0.1.192022-05-2513204Fixed conversation_parts stream schema definition
0.1.182022-05-0412482Update input configuration copy
0.1.172022-04-2912374Fixed filtering of conversation_parts
0.1.162022-03-2311206Added conversation_id field to conversation_part records
0.1.152022-03-2211176Correct check_connection URL
0.1.142022-03-1611208Improve 'conversations' incremental sync speed
0.1.132022-01-149513Added handling of scroll param when it expired
0.1.122021-12-148429Updated fields and descriptions
0.1.112021-12-138685Remove time.sleep for rate limit
0.1.102021-12-108637Fix 'conversations' order and sorting. Correction of the companies stream
0.1.92021-12-038395Fix backoff of 'companies' stream
0.1.82021-11-097060Added oauth support
0.1.72021-11-087499Remove base-python dependencies
0.1.62021-10-076879Corrected pagination for contacts
0.1.52021-09-286082Corrected android_last_seen_at field data type in schemas
0.1.42021-09-206087Corrected updated_at field data type in schemas
0.1.32021-09-085908Corrected timestamp and arrays in schemas
0.1.22021-08-195531Corrected pagination
0.1.12021-07-315123Corrected rate limit
0.1.02021-07-194676Release Intercom CDK Connector
</details>