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.
- Log in to your Intercom account and go to the Developer Hub.
- Click Your apps in the top-right corner, then click New app.
- Choose an App name, select your Workspace from the dropdown, then click Create app.
- 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.
- 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
- Log into your Airbyte Cloud account.
- Click Sources, then click + New source.
- On the Set up the source page, select Intercom from the Source type dropdown.
- Enter a name for the Intercom connector.
- Authenticate your account:
For Airbyte Open Source:
- Go to the Airbyte Open Source dashboard.
- Click Sources, then click + New source.
- On the Set up the source page, select Intercom from the Source type dropdown.
- 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.
- 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. - 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. - Optionally, configure Activity logs stream slice step size to control the days of activity log data fetched per request. The default is
30days. Reduce this value if the Activity Logs stream times out. - Optionally, configure Num Workers to set the worker threads used for concurrent stream processing. The default is
10, with a maximum of40. Increase this value to accelerate syncs for workspaces with many conversations. - 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. - 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:
- Activity Logs (Incremental)
- Admins (Full table)
- Companies (Incremental)
- Company Segments (Incremental)
- Company Attributes (Full table)
- Contact Attributes (Full table)
- Contacts (Incremental)
- Conversations (Incremental)
- Conversation Parts (Incremental)
- Segments (Incremental)
- Tags (Full table)
- Teams (Full table)
- Tickets (Incremental)
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
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.0.0 | 2026-11-10 | 91060 | Add company_id to company_segments and make [company_id, id] its primary key |
| 0.13.30 | 2026-11-10 | 91585 | Update dependencies |
| 0.13.29 | 2026-11-03 | 90886 | Simplify error handling configuration for the conversation_parts stream; no behavior change |
| 0.13.28 | 2026-11-03 | 90605 | Update dependencies |
| 0.13.27 | 2026-10-27 | 89955 | Update dependencies |
| 0.13.26 | 2026-10-20 | 89568 | Update base image to SDM 7.37.1 |
| 0.13.25 | 2026-09-16 | 78017 | Improve the Companies stream error message for Intercom scroll concurrency failures. |
| 0.13.24 | 2026-05-21 | Fix sub-daily incremental syncs for contacts, conversations, and tickets | |
| 0.13.23 | 2026-05-19 | 78171 | Promoted release candidate to GA |
| 0.13.23-rc.1 | 2026-05-12 | 78023 | Bump CDK to 7.18.1.post8.dev25490693965 for block_simultaneous_read regression validation |
| 0.13.22 | 2026-04-28 | 70464 | Update dependencies |
| 0.13.21 | 2026-04-22 | 76847 | Update CDK to 7.17.3 |
| 0.13.20 | 2026-04-14 | 76316 | Promote 0.13.20-rc.1 to stable and disable progressive rollout |
| 0.13.20-rc.1 | 2026-04-10 | 73717 | Add configurable concurrency (num_workers), configurable API rate limit (api_rate_limit), HTTPAPIBudget, and ErrorHandlerWithRateLimiter for conversation_parts |
| 0.13.19 | 2026-04-09 | 76182 | Promote 0.13.19-rc.1 to stable and disable progressive rollout |
| 0.13.19-rc.1 | 2026-04-08 | 76122 | Increase HTTP connection pool size |
| 0.13.18 | 2026-04-06 | 75899 | Update CDK to 7.15.0 |
| 0.13.17 | 2026-03-30 | 75575 | Add oauth_connector_input_specification for declarative OAuth |
| 0.13.16 | 2026-03-24 | 75419 | Promote 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.6 | 2026-03-19 | 75216 | Bump CDK base image to 7.13.0 (includes block_simultaneous_read support and cursor field fix) |
| 0.13.16-rc.5 | 2026-03-11 | 71141 | Block simultaneous reading from companies endpoint |
| 0.13.16-rc.4 | 2026-03-03 | 74143 | fix(source-intercom): fix UnboundLocalError in rate limiter when response is not available |
| 0.13.16-rc.3 | 2026-03-03 | 72955 | fix(source-intercom): add step size and end_datetime to contacts, conversations, and activity_logs streams |
| 0.13.16-rc.2 | 2026-02-18 | 73635 | fix(source-intercom): bump heartbeat timeout from 6h to 9h |
| 0.13.16-rc.1 | 2025-12-11 | 70335 | Fix pagination on companies stream |
| 0.13.15 | 2025-11-25 | 69563 | Update dependencies |
| 0.13.14 | 2025-11-19 | 69306 | Update custom IntercomScrollRetriever to not use deprecated stream_state parameter |
| 0.13.13 | 2025-10-29 | 68767 | Update dependencies |
| 0.13.12 | 2025-10-21 | 68477 | Update dependencies |
| 0.13.11 | 2025-10-14 | 67933 | Update dependencies |
| 0.13.10 | 2025-10-07 | 67364 | Update dependencies |
| 0.13.9 | 2025-10-06 | 67104 | Increase Heartbeat Timeout to Account for cursor based streams with client side incremental and large record counts for a given day. |
| 0.13.8 | 2025-09-30 | 66789 | Update dependencies |
| 0.13.7 | 2025-09-26 | 66665 | Fix Typo on Error Message |
| 0.13.6 | 2025-09-09 | 66056 | Update dependencies |
| 0.13.5 | 2025-08-23 | 65374 | Update dependencies |
| 0.13.4 | 2025-08-09 | 63523 | Update dependencies |
| 0.13.3 | 2025-07-12 | 63155 | Update dependencies |
| 0.13.2 | 2025-07-05 | 62592 | Update dependencies |
| 0.13.1 | 2025-06-28 | 54308 | Update dependencies |
| 0.13.0 | 2025-06-25 | 62069 | Promoting release candidate 0.13.0-rc.5 to a main version. |
| 0.13.0-rc.5 | 2025-06-11 | 61506 | Add better error handling for companies stream, update SDM, & add advanced_auth |
| 0.13.0-rc.4 | 2025-05-15 | 60235 | Add required custom paginator for ‘companies’ stream & Fix 500s on Tickets stream. |
| 0.13.0-rc.3 | 2025-05-09 | 55829 | Fix pagination for conversations, tickets, companies & contacts and cleanup manifest |
| 0.13.0-rc.2 | 2025-04-08 | 57524 | Use global state and pass state to parent streams for conversation_parts and company_segments |
| 0.13.0-rc.1 | 2025-02-22 | 53187 | Update with latest CDK features, remove custom incremental sync components, update schema for conversation_parts |
| 0.12.2 | 2025-02-15 | 53835 | Update dependencies |
| 0.12.1 | 2025-02-08 | 53257 | Update dependencies |
| 0.12.0 | 2025-02-03 | 52687 | New stream Tickets |
| 0.11.0 | 2025-02-03 | 51619 | Upgrade API version to 2.11, add ai_agent_participated and ai_agent fields conversations stream schema |
| 0.10.1 | 2025-02-01 | 49212 | Update dependencies |
| 0.10.0 | 2025-01-24 | 52132 | Fix incremental sync |
| 0.9.0 | 2025-01-15 | 51570 | Promoting release candidate 0.9.0-rc.2 to a main version. |
| 0.9.0-rc.2 | 2025-01-13 | 49936 | Incremental substream fixes |
| 0.9.0-rc.1 | 2024-12-17 | 47240 | Migrate to manifest-only format |
| 0.8.3 | 2024-12-12 | 48979 | Update dependencies |
| 0.8.2 | 2024-10-29 | 47919 | Update dependencies |
| 0.8.1 | 2024-10-28 | 47537 | Update dependencies |
| 0.8.0 | 2024-10-23 | 46658 | Add lookback_window to the source specification |
| 0.7.5 | 2024-10-21 | 47120 | Update dependencies |
| 0.7.4 | 2024-10-12 | 46831 | Update dependencies |
| 0.7.3 | 2024-10-05 | 46447 | Update dependencies |
| 0.7.2 | 2024-09-28 | 45279 | Update dependencies |
| 0.7.1 | 2024-08-31 | 44966 | Update dependencies |
| 0.7.0 | 2024-08-29 | 44911 | Migrate to CDK v4 |
| 0.6.21 | 2024-08-24 | 44672 | Update dependencies |
| 0.6.20 | 2024-08-17 | 44296 | Update dependencies |
| 0.6.19 | 2024-08-12 | 43878 | Update dependencies |
| 0.6.18 | 2024-08-10 | 43500 | Update dependencies |
| 0.6.17 | 2024-08-03 | 43276 | Update dependencies |
| 0.6.16 | 2024-07-29 | 42094 | Use latest CDK, raise config error on Active subscription needed error and transient errors for Companies stream. |
| 0.6.15 | 2024-07-27 | 42654 | Update dependencies |
| 0.6.14 | 2024-07-20 | 42262 | Update dependencies |
| 0.6.13 | 2024-07-13 | 41712 | Update dependencies |
| 0.6.12 | 2024-07-10 | 41356 | Update dependencies |
| 0.6.11 | 2024-07-09 | 41112 | Update dependencies |
| 0.6.10 | 2024-07-06 | 40878 | Update dependencies |
| 0.6.9 | 2024-06-25 | 40428 | Update dependencies |
| 0.6.8 | 2024-06-22 | 39951 | Update dependencies |
| 0.6.7 | 2024-06-06 | 39286 | [autopull] Upgrade base image to v1.2.2 |
| 0.6.6 | 2024-05-24 | 38626 | Add step granularity for activity logs stream |
| 0.6.5 | 2024-04-19 | 36644 | Updating to 0.80.0 CDK |
| 0.6.4 | 2024-04-12 | 36644 | Schema descriptions |
| 0.6.3 | 2024-03-23 | 36414 | Fixed pagination regression bug for conversations stream |
| 0.6.2 | 2024-03-22 | 36277 | Fixed the bug for conversations stream failed due to 404 - User Not Found, when the 2.10 API version is used |
| 0.6.1 | 2024-03-18 | 36232 | Fixed the bug caused the regression when setting the Intercom-Version header, updated the source to use the latest CDK version |
| 0.6.0 | 2024-02-12 | 35176 | Update the connector to use 2.10 API version |
| 0.5.1 | 2024-02-12 | 35148 | Manage dependencies with Poetry |
| 0.5.0 | 2024-02-09 | 35063 | Add missing fields for mutiple streams |
| 0.4.0 | 2024-01-11 | 33882 | Add new stream Activity Logs |
| 0.3.2 | 2023-12-07 | 33223 | Ignore 404 error for Conversation Parts |
| 0.3.1 | 2023-10-19 | 31599 | Base image migration: remove Dockerfile and use the python-connector-base image |
| 0.3.0 | 2023-05-25 | 29598 | Update custom components to make them compatible with latest cdk version, simplify logic, update schemas |
| 0.2.1 | 2023-05-25 | 26571 | Remove authSpecification from spec.json in favour of advancedAuth |
| 0.2.0 | 2023-04-05 | 23013 | Migrated to Low-code (YAML Frramework) |
| 0.1.33 | 2023-03-20 | 22980 | Specified date formatting in specification |
| 0.1.32 | 2023-02-27 | 22095 | Extended Contacts schema adding opted_out_subscription_types property |
| 0.1.31 | 2023-02-17 | 23152 | Add TypeTransformer to stream companies |
| 0.1.30 | 2023-01-27 | 22010 | Set AvailabilityStrategy for streams explicitly to None |
| 0.1.29 | 2022-10-31 | 18681 | Define correct version for airbyte-cdk~=0.2 |
| 0.1.28 | 2022-10-20 | 18216 | Use airbyte-cdk~=0.2.0 with SQLite caching |
| 0.1.27 | 2022-08-28 | 17326 | Migrate to per-stream states |
| 0.1.26 | 2022-08-18 | 16540 | Fix JSON schema |
| 0.1.25 | 2022-08-18 | 15681 | Update Intercom API to v 2.5 |
| 0.1.24 | 2022-07-21 | 14924 | Remove additionalProperties field from schemas |
| 0.1.23 | 2022-07-19 | 14830 | Added checkpoint_interval for Incremental streams |
| 0.1.22 | 2022-07-09 | 14554 | Fixed conversation_parts stream schema definition |
| 0.1.21 | 2022-07-05 | 14403 | Refactored Conversations, Conversation Parts, Company Segments to increase performance |
| 0.1.20 | 2022-06-24 | 14099 | Extended Contacts stream schema with sms_consent,unsubscribe_from_sms properties |
| 0.1.19 | 2022-05-25 | 13204 | Fixed conversation_parts stream schema definition |
| 0.1.18 | 2022-05-04 | 12482 | Update input configuration copy |
| 0.1.17 | 2022-04-29 | 12374 | Fixed filtering of conversation_parts |
| 0.1.16 | 2022-03-23 | 11206 | Added conversation_id field to conversation_part records |
| 0.1.15 | 2022-03-22 | 11176 | Correct check_connection URL |
| 0.1.14 | 2022-03-16 | 11208 | Improve ‘conversations’ incremental sync speed |
| 0.1.13 | 2022-01-14 | 9513 | Added handling of scroll param when it expired |
| 0.1.12 | 2021-12-14 | 8429 | Updated fields and descriptions |
| 0.1.11 | 2021-12-13 | 8685 | Remove time.sleep for rate limit |
| 0.1.10 | 2021-12-10 | 8637 | Fix ‘conversations’ order and sorting. Correction of the companies stream |
| 0.1.9 | 2021-12-03 | 8395 | Fix backoff of ‘companies’ stream |
| 0.1.8 | 2021-11-09 | 7060 | Added oauth support |
| 0.1.7 | 2021-11-08 | 7499 | Remove base-python dependencies |
| 0.1.6 | 2021-10-07 | 6879 | Corrected pagination for contacts |
| 0.1.5 | 2021-09-28 | 6082 | Corrected android_last_seen_at field data type in schemas |
| 0.1.4 | 2021-09-20 | 6087 | Corrected updated_at field data type in schemas |
| 0.1.3 | 2021-09-08 | 5908 | Corrected timestamp and arrays in schemas |
| 0.1.2 | 2021-08-19 | 5531 | Corrected pagination |
| 0.1.1 | 2021-07-31 | 5123 | Corrected rate limit |
| 0.1.0 | 2021-07-19 | 4676 | Release Intercom CDK Connector |