:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from typing import cast
from products.warehouse_sources.sources.intercom._config import IntercomSourceConfig
from products.warehouse_sources.sources.intercom.intercom import (
IntercomConversationCursor,
IntercomResumeConfig,
intercom_source,
validate_credentials as validate_intercom_credentials,
)
from products.warehouse_sources.sources.intercom.settings import INCREMENTAL_FIELDS, INTERCOM_ENDPOINTS
from products.warehouse_sources.sources.sdk import (
CanonicalDescriptions,
CursorSource,
DataWarehouseSourceCategory,
ExternalDataSourceType,
FieldType,
OAuthMixin,
ProductKey,
ReleaseStatus,
ResumableSource,
ResumableSourceManager,
SourceConfig,
SourceFieldOauthConfig,
SourceInputs,
SourceRegistry,
SourceResponse,
SourceSchema,
detect,
)
@SourceRegistry.register
class IntercomSource(
ResumableSource[IntercomSourceConfig, IntercomResumeConfig],
CursorSource[IntercomConversationCursor],
OAuthMixin,
):
codebase_detection = detect(
env=(
"^INTERCOM_",
"^IOS_INTERCOM_APP_ID$",
"^IOS_INTERCOM_KEY$",
"^ANDROID_INTERCOM_APP_ID$",
"^ANDROID_INTERCOM_KEY$",
),
script_hosts=("widget.intercom.io", "js.intercomcdn.com", "app.intercom.io", "static.intercomcdn.com"),
npm=(
"intercom-client",
"@intercom/messenger-js-sdk",
"@intercom/intercom-react-native",
"react-use-intercom",
"cordova-plugin-intercom",
"@intercom/cli",
"passport-intercom",
"@types/intercom-web",
"@types/intercom-client",
"@capacitor-community/intercom",
"@capgo/capacitor-intercom",
"@awesome-cordova-plugins/intercom",
"@ionic-native/intercom",
"react-intercom",
"@supy-io/ngx-intercom",
"ng-intercom",
"@mathieustan/vue-intercom",
),
pypi=("python-intercom", "django-intercom"),
cocoapods=("Intercom",),
composer=("intercom/intercom-php", "intercom/oauth2-intercom"),
go=("github.com/intercom/intercom-go", "gopkg.in/intercom/intercom-go.v2"),
hex=("intercom",),
maven=(
"io.intercom.android:intercom-sdk",
"io.intercom:intercom-java",
"io.intercom.android:intercom-sdk-base",
"io.intercom.android:intercom-sdk-fcm",
"io.intercom.android:intercom-sdk-ui",
"io.intercom.android:intercom-sdk-base-transitive",
),
pub=("intercom_flutter", "intercom_flutter_web", "intercom_flutter_platform_interface"),
rubygems=("intercom", "intercom-rails", "omniauth-intercom", "intercom-app"),
swiftpm=("github.com/intercom/intercom-ios-sp", "github.com/intercom/intercom-ios"),
alternative_to=(ProductKey.CONVERSATIONS,),
)
lists_tables_without_credentials = True # static endpoint catalog — safe for public docs
supported_versions = ("2.13", "2.15", "2.16", "2.17")
default_version = "2.17"
api_docs_url = "https://developers.intercom.com/docs/references/rest-api"
@property
def source_type(self) -> ExternalDataSourceType:
return ExternalDataSourceType.INTERCOM
def get_canonical_descriptions(self) -> CanonicalDescriptions:
from products.warehouse_sources.sources.intercom.canonical_descriptions import CANONICAL_DESCRIPTIONS
return CANONICAL_DESCRIPTIONS
def get_non_retryable_errors(self) -> dict[str, str | None]:
return {
"401 Client Error": "Your Intercom connection is invalid or expired. Please reconnect it.",
"403 Client Error": "Your Intercom connection is missing required scopes. Please update permissions and reconnect.",
# Deterministic credential/config errors from OAuthMixin and source_for_pipeline. The
# integration row is gone or unconfigured, so retrying can never succeed — the customer
# must reconnect. Match on the stable prefix so the volatile integration ID is ignored.
"Missing integration ID": "Intercom integration ID is not configured. Please reconnect your Intercom account.",
"Integration not found": "The linked Intercom integration no longer exists. Please reconnect your Intercom account.",
"Intercom access token not found": "Intercom OAuth access token is missing. Please reconnect your Intercom account.",
# Raised by intercom_source for a table Intercom only serves on a newer API version.
"requires Intercom API version": "This table needs a newer Intercom API version. Upgrade the source's API version, then sync again.",
}
def resume_covers_run(
self,
*,
incremental_or_append: bool,
schema_name: str | None = None,
) -> bool:
# The companies Scroll API cannot preserve a cursor across worker hand-offs.
return schema_name != "companies"
def get_retryable_errors(self) -> set[str]:
# The `companies` table walks Intercom's companies Scroll API (`_iter_companies` in
# intercom.py). The scroll cursor expires mid-walk on idle timeout or when a
# concurrent sync steals the workspace's single scroll slot, and the continuation
# then 404s (see `_is_scroll_expired`). `companies` is full-refresh, so a fresh
# Temporal attempt opens a new scroll and restarts cleanly — transient and
# self-recovering, not a real bug.
#
# Opening a fresh scroll can also 400 with `scroll_exists` when another scroll is
# still open for the workspace (see `_is_scroll_exists`). `_open_companies_scroll`
# already backs off and retries that inline, but a lock held longer than the retry
# budget exhausts it and the raw error propagates — a fresh Temporal attempt opens
# cleanly once the stale scroll has expired, so this is the same self-recovering
# case as the 404 above, just surfaced later.
return {
"Not Found for url: https://api.intercom.io/companies/scroll",
"Bad Request for url: https://api.intercom.io/companies/scroll",
# Every Intercom request goes through `_make_intercom_session`, whose transport-level
# retry (`_INTERCOM_RETRY`, derived from `DEFAULT_RETRY`) already retries a 429/5xx
# response before `raise_for_status` can raise. A `HTTPError` reaching here has already
# exhausted that budget, so it's a transient upstream blip — Temporal retries the whole
# activity next. `raise_for_status` derives the "Server Error" prefix from the status
# code alone, not Intercom's reason text, so it's stable to match on (see
# convex/app_store_connect for the same pattern).
"Server Error",
}
@property
def get_source_config(self) -> SourceConfig:
return SourceConfig(
name=ExternalDataSourceType.INTERCOM,
category=DataWarehouseSourceCategory.CUSTOMER_SUPPORT,
caption="Select an existing Intercom workspace to link to PostHog or create a new connection",
iconPath="/static/services/intercom.png",
docsUrl="https://posthog.com/docs/cdp/sources/intercom",
fields=cast(
list[FieldType],
[
SourceFieldOauthConfig(
name="intercom_integration_id",
label="Intercom workspace",
required=True,
kind="intercom",
),
],
),
releaseStatus=ReleaseStatus.GA,
)
def get_schemas(
self,
config: IntercomSourceConfig,
team_id: int,
with_counts: bool = False,
names: list[str] | None = None,
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
resolved_version = self.resolve_api_version(api_version)
schemas = []
for endpoint_config in INTERCOM_ENDPOINTS.values():
if endpoint_config.api_versions is not None and resolved_version not in endpoint_config.api_versions:
continue
incremental_fields = INCREMENTAL_FIELDS.get(endpoint_config.name, [])
supports_incremental = bool(incremental_fields)
schemas.append(
SourceSchema(
name=endpoint_config.name,
supports_incremental=supports_incremental,
supports_append=supports_incremental,
incremental_fields=incremental_fields,
)
)
if names is not None:
names_set = set(names)
schemas = [s for s in schemas if s.name in names_set]
return schemas
def validate_credentials(
self, config: IntercomSourceConfig, team_id: int, schema_name: str | None = None, api_version: str | None = None
) -> tuple[bool, str | None]:
try:
integration = self.get_oauth_integration(config.intercom_integration_id, team_id)
except ValueError:
# get_oauth_integration raises ValueError("Integration not found: <id>") for an
# integration that was deleted or disconnected while the source still references it.
return False, "Intercom integration not found. Please reconnect your Intercom integration."
if not integration.access_token:
return False, "Intercom integration has no access token. Please reconnect."
# Probe under the source's resolved pin so a 2.13-pinned source validates against the
# version it syncs on; `None` (pre-creation) resolves to `default_version`.
return validate_intercom_credentials(
integration.access_token, schema_name=schema_name, api_version=self.resolve_api_version(api_version)
)
def cursor_class(self) -> type[IntercomConversationCursor]:
return IntercomConversationCursor
def merge_cursors(
self, current: IntercomConversationCursor, candidate: IntercomConversationCursor
) -> IntercomConversationCursor:
return max(current, candidate, key=lambda cursor: cursor.updated_at)
def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[IntercomResumeConfig]:
return ResumableSourceManager[IntercomResumeConfig](inputs, IntercomResumeConfig)
def source_for_pipeline(
self,
config: IntercomSourceConfig,
resumable_source_manager: ResumableSourceManager[IntercomResumeConfig],
inputs: SourceInputs,
) -> SourceResponse:
integration = self.get_oauth_integration(config.intercom_integration_id, inputs.team_id)
if not integration.access_token:
raise ValueError(f"Intercom access token not found for job {inputs.job_id}")
return intercom_source(
access_token=integration.access_token,
endpoint=inputs.schema_name,
team_id=inputs.team_id,
job_id=inputs.job_id,
api_version=self.resolve_api_version(inputs.api_version),
resumable_source_manager=resumable_source_manager,
should_use_incremental_field=inputs.should_use_incremental_field,
incremental_field=inputs.incremental_field if inputs.should_use_incremental_field else None,
db_incremental_field_last_value=inputs.db_incremental_field_last_value
if inputs.should_use_incremental_field
else None,
# Only the HITL events table keeps a source cursor; see `_conversation_hitl_events_generator`.
cursor_manager=self.get_cursor_manager(inputs)
if inputs.schema_name == "conversation_hitl_events"
else None,
)