Advanced Analytica Advanced Analytica: IBOM
← All connectors
Intercom logo

Source connector

Intercom

Set up Intercom as a source and move its data into your chosen destination.

Version 1.0.0 certified generally available

Intercom

This page explains how to set up the Intercom source connector and provides reference information.

Prerequisites

  • An Intercom account containing 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. Grant at least 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. Without it, the connector silently skips the Tickets stream during syncs.
  • A Start date in UTC format (YYYY-MM-DDTHH:mm:ssZ). The connector only replicates data created on or after this date.

Setup

Set up Intercom

Get an Intercom access token (Airbyte Open Source)

You need an access token to authenticate the connector in Airbyte Open Source. Create an Intercom app and generate the token using these steps. For more information about Intercom’s authentication flow, see the official documentation.

  1. Log in to your Intercom account and go 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, then click Create app.
  4. Open the Authentication tab, then click Edit in the top-right corner. Select the permissions you want to grant the app. Grant only read permissions, not write. When you’ve finished, click Save.
  5. Under the Access token header, you’ll be asked to regenerate your access token. Follow the instructions, then copy the new token.

Set up the Intercom connector in Airbyte

Airbyte Cloud

  1. Log into your Airbyte Cloud account.
  2. Click Sources, 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. Authenticate your account:

For Airbyte Open Source:

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, 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 Airbyte Cloud, click Authenticate your Intercom account. In the pop-up, select the correct workspace from the dropdown, then click Authorize access.
  • For Airbyte Open Source, enter your access token to authenticate your account.
  1. For Start date, use the datepicker or enter a UTC date and time in the format YYYY-MM-DDTHH:mm:ssZ. The connector only replicates data created on or after this date.
  2. Optionally, configure Lookback window to re-sync records updated within the specified days before the current cursor position. This captures late-arriving updates. The default is 0, which applies no lookback.
  3. Optionally, configure Activity logs stream slice step size to control the days of activity log data fetched per request. The default is 30 days. Reduce this value if the Activity Logs stream times out.
  4. Optionally, configure Num Workers to set the worker threads used for concurrent stream processing. The default is 10, with a maximum of 40. Increase this value to accelerate syncs for workspaces with many conversations.
  5. Optionally, configure API Rate Limit to set the effective API request budget per minute. The default is 9500, or 95% of Intercom’s standard 10,000/min limit. If your workspace has a higher limit, such as 150,000/min, set this to about 95% of that value. This allows you to use the available API throughput.
  6. Click Set up source and wait for the tests to finish.

Supported sync modes

The Intercom source connector supports these sync modes:

  • Full Refresh
  • Incremental

Supported streams

The Intercom source connector supports these streams:

Performance

The connector is subject to standard Intercom rate limits. Public apps allow 1,000 API calls per minute by default. Private apps allow 10,000 API calls per minute by default. A workspace-level limit of 25,000 API calls per minute also applies. The connector monitors the X-RateLimit-Remaining header and slows requests before reaching the API rate limit. This prioritises stability over sync speed. If the API returns a 429 Too Many Requests response, the connector retries automatically.

The API Rate Limit setting controls the connector’s request budget. It defaults to 9500 requests per minute. The connector automatically derives a per-10-second window (api_rate_limit / 6). If your Intercom workspace has a higher limit, such as 150,000/min, increase this value. This allows the connector to use the available API throughput.

The connector also supports configurable concurrency through the Num Workers setting. The default is 10, and the maximum is 40. This controls how many partition slices the connector processes in parallel. It particularly benefits substream-based streams such as conversation_parts and company_segments.

The connector shouldn’t encounter rate limit issues during normal use. Create an issue if you see rate limit errors that aren’t retried automatically.

Troubleshooting and limitations

Client-side incremental sync for Companies and Company Segments

The Companies and Company Segments streams use the Scroll over all companies endpoint, which doesn’t support server-side datetime filtering. For incremental syncs, the connector fetches every record from the API and filters them locally. It emits only records newer than the last sync checkpoint.

The connector must read every company record before identifying and emitting new ones, even if you need one day’s data. Workspaces with many companies can therefore experience long sync times.

Company Segments membership records

Each company_segments record represents one segment membership for one company. company_id is the company’s Intercom ID. It matches id in the companies stream. It isn’t the company_id field in the companies stream, which contains the company ID you set.

The stream filters by the segment’s updated_at, not the date the company joined the segment. A membership syncs only when both the company and segment were last updated on or after the Start Date. An incremental sync can miss a company joining a segment that hasn’t changed since the previous sync. It also can’t remove an ended membership. For a complete membership table, sync company_segments using Full Refresh | Overwrite. Use a connection with a Start Date earlier than your Intercom workspace.

One open scroll per app

The Intercom API allows only one company scroll per app at a time. A second request during an active scroll returns a 400 error. The message is “scroll already exists for this workspace.” The connector retries this error automatically after a one-minute delay. Scrolls expire after one minute of inactivity.

The connector prevents conflicts by blocking simultaneous reads from the Companies endpoint. It applies this control across connections using the same Intercom workspace. If they sync Companies or Company Segments, the connector queues their reads. This keeps only one scroll active at a time.

Reduce sync times

These streams must read every record during each sync. Including Companies and Company Segments with other streams can therefore increase the connection’s total sync time. To prevent this, sync Companies and Company Segments separately from your other Intercom streams.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
1.0.02026-11-1091060Add company_id to company_segments and make [company_id, id] its primary key
0.13.302026-11-1091585Update dependencies
0.13.292026-11-0390886Simplify error handling configuration for the conversation_parts stream; no behavior change
0.13.282026-11-0390605Update dependencies
0.13.272026-10-2789955Update dependencies
0.13.262026-10-2089568Update base image to SDM 7.37.1
0.13.252026-09-1678017Improve the Companies stream error message for Intercom scroll concurrency failures.
0.13.242026-05-21Fix sub-daily incremental syncs for contacts, conversations, and tickets
0.13.232026-05-1978171Promoted release candidate to GA
0.13.23-rc.12026-05-1278023Bump CDK to 7.18.1.post8.dev25490693965 for block_simultaneous_read regression validation
0.13.222026-04-2870464Update dependencies
0.13.212026-04-2276847Update CDK to 7.17.3
0.13.202026-04-1476316Promote 0.13.20-rc.1 to stable and disable progressive rollout
0.13.20-rc.12026-04-1073717Add configurable concurrency (num_workers), configurable API rate limit (api_rate_limit), HTTPAPIBudget, and ErrorHandlerWithRateLimiter for conversation_parts
0.13.192026-04-0976182Promote 0.13.19-rc.1 to stable and disable progressive rollout
0.13.19-rc.12026-04-0876122Increase HTTP connection pool size
0.13.182026-04-0675899Update CDK to 7.15.0
0.13.172026-03-3075575Add oauth_connector_input_specification for declarative OAuth
0.13.162026-03-2475419Promote 0.13.16-rc.6 to GA — includes CDK 7.13.0 upgrade, block_simultaneous_read for companies, rate limiter fix, step size/end_datetime for incremental streams, and heartbeat timeout bump
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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.