.png)
Intercom Integration Guide
Connect Intercom with enterprise systems through REST APIs, selected webhook events, secure authentication, and Martini workflows.
Intercom integration options at a glance
Intercom’s primary integration interface is its REST API at api.intercom.io, covering Contacts, Companies, Conversations, Tickets, Articles, teams, admins, tags, and related resources. Intercom also supports webhook subscriptions for selected conversation, contact, company, ticket, and article events, although coverage depends on the resource and workspace configuration. Bulk and export-oriented capabilities are available for selected use cases, while attachments are supported in specific conversation and message contexts. OAuth 2.0, bearer tokens, personal access tokens, scopes, and webhook signing support secure access. Martini can orchestrate these mechanisms through authenticated workflows, APIs, mappings, checkpoints, retries, and validation.
| Integration point | Supported by Intercom? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Intercom’s principal integration interface for Contacts, Companies, Conversations, Tickets, Articles, admins, teams, tags, and related resources. It supports reads, creates, updates, messages, notes, assignment, routing, and content management. | Martini can consume Intercom REST endpoints from workflows, map and validate payloads, expose internal REST APIs that abstract Intercom operations, and orchestrate calls to other systems. |
| Webhooks | Yes | Intercom supports webhook subscriptions for selected conversation, contact, company, ticket, and article events. Coverage is resource- and workspace-specific rather than universal. | Martini can expose an API endpoint or receive webhook-triggered workflow input, validate the signing mechanism, normalize events, retrieve current resources, and route them downstream. |
| Authentication | Yes | Intercom supports OAuth 2.0, bearer access tokens, personal access tokens where enabled, OAuth scopes, permissions, and webhook signing secrets. | Martini can store credentials and secrets in environment-specific secure configuration and use authenticated workflows or APIs with controlled access. |
| Bulk and export APIs | Limited | Batch-style operations and data export capabilities are available for selected resources and use cases; coverage is not uniform across all objects or writes. | Martini can combine paginated reads, supported bulk or export operations, queueing, scheduled workflows, checkpoints, and rate-limit-aware retries. |
| File and attachment APIs | Limited | Attachments are supported in selected conversation and message contexts through attachment metadata or URLs, not as a universal file-management repository. | Martini can retrieve permitted attachment references, transform or copy files to another system, and preserve content type and correlation metadata. |
| Pagination and incremental synchronization | Yes | Intercom list operations use pagination, with cursors or equivalent state. Resource timestamps, filters, and webhooks can support incremental synchronization where available. | Martini can persist cursors and checkpoints, combine event-driven processing with scheduled reconciliation, and implement idempotent upserts. |
| GraphQL APIs | Not confirmed | No current public Intercom GraphQL API was confirmed as the recommended general-purpose integration interface. | Martini can consume GraphQL APIs generally, but Intercom integrations should use the confirmed REST API unless a required GraphQL endpoint is separately documented. |
| SOAP APIs | No | No current public Intercom SOAP API was confirmed; Intercom’s documented model uses REST APIs and webhooks. | Martini supports SOAP consumption generally, but SOAP is not an applicable mechanism for the confirmed Intercom integration model. |
| Database access | No | Intercom does not provide direct customer database or SQL access for application integrations. | Martini should access Intercom data through its APIs, webhooks, and documented export mechanisms rather than direct database connectivity. |
How Intercom exposes data and business events
Intercom REST APIs
Intercom’s REST API at api.intercom.io is the principal interface for Contacts, Companies, Conversations, Tickets, Articles, admins, teams, tags, and related resources. It supports retrieval, creation, updates, messaging, assignment, routing, and content operations.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to Intercom, calls the required endpoint, validates the response, maps the resource to a canonical model, applies business rules, and writes to one or more target systems. For list operations, the workflow persists pagination state and checkpoints.
Implementation sequence
Intercom Webhooks
Intercom supports webhook subscriptions for selected Conversation, Contact, Company, Ticket, and Article events. Exact topics depend on the resource, API version, workspace capabilities, and configuration.
Martini implementation pattern
Martini implementation pattern: expose a controlled API endpoint or webhook-triggered workflow, validate the Intercom signing mechanism, acknowledge valid input promptly, and process longer-running work asynchronously where appropriate. The workflow should re-fetch the current resource because events can be incomplete, duplicated, or out of order.
Implementation sequence
Intercom Bulk and Data Export
Intercom provides batch-style and data export capabilities for selected resources and use cases. These capabilities are not uniform across all object types or operations and should be assessed per endpoint.
Martini implementation pattern
Martini implementation pattern: use scheduled or manually initiated workflows for large transfers, combine export or bulk operations with paginated reads, and maintain checkpoints so failed pages or batches can restart without repeating completed work.
Implementation sequence
Intercom Attachments
Intercom supports attachments in selected conversation and message contexts. Attachments may be represented through URLs or metadata and do not constitute confirmation of a universal file repository API.
Martini implementation pattern
Martini implementation pattern: inspect attachment metadata in the relevant Conversation or message response, retrieve the file only when permitted, apply content-type and privacy rules, and copy it to a durable target location or retain the approved reference.
Implementation sequence
Intercom Authentication
Intercom supports OAuth 2.0 for public or multi-workspace integrations, bearer access tokens, personal access tokens where enabled, scopes, permissions, and webhook signing secrets.
Martini implementation pattern
Martini implementation pattern: keep client credentials, access tokens, personal tokens, and webhook secrets in environment-specific secure configuration. Workflows use the least-privilege permissions required and separate development, staging, and production credentials.
Implementation sequence
Common Intercom integration patterns
Pattern 1: Synchronize Contacts and Companies with Salesforce
When to use this pattern
Use this pattern when Intercom and Salesforce must share customer identity, company association, lifecycle attributes, ownership, or support context. Webhooks provide near-real-time processing for supported changes, while scheduled reconciliation corrects missed events and handles backfills.
Integration direction
Example Mapping
| Intercom Field | Canonical Field | Target Field |
|---|---|---|
| Contact.id | customer.externalId | Contact.IntercomContactId |
| Contact.email | customer.email | Contact.Email |
| Company.name | organization.name | Account.Name |
| Contact.custom_attributes | customer.attributes | Contact.CustomAttributes |
Martini implementation pattern
A Martini workflow receives a supported Contact or Company event, validates and deduplicates it, retrieves the current Intercom resource, and maps it to Salesforce. Business rules determine ownership, field precedence, merge behavior, and privacy filtering. The workflow performs an idempotent Salesforce upsert, records the correlation key, and retries rate-limit or transient failures without creating duplicates.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- idempotent upserts
- error handling
- scheduled reconciliation
Pattern 2: Route Conversations to Jira or ServiceNow
When to use this pattern
Use this pattern when a customer Conversation needs engineering, operational, or IT escalation. It is appropriate for selected Intercom events such as creation, assignment, state changes, or updates that meet routing criteria.
Integration direction
Example Mapping
| Intercom Field | Canonical Field | Target Field |
|---|---|---|
| Conversation.id | supportConversation.externalId | Issue.ExternalConversationId |
| Conversation.title | workItem.summary | Issue.Summary |
| Conversation.contacts | customer.references | Issue.CustomerContext |
| Conversation.state | support.status | Incident.State |
Martini implementation pattern
Martini validates the webhook, retrieves the current Conversation, and applies rules based on tags, team, state, priority, or customer attributes. It creates or updates the Jira issue or ServiceNow incident, stores the downstream identifier, and optionally writes a note or metadata back to Intercom where supported. Duplicate checks and retry-safe writes preserve one downstream work item per escalation.
Martini capabilities used
- webhook consumption
- API orchestration
- conditional routing
- data transformation
- correlation state
- retry handling
Pattern 3: Enrich Intercom with Shopify Customer and Order Context
When to use this pattern
Use this pattern when support agents need approved customer, order, fulfillment, or purchase context in Intercom. The design should minimize sensitive data and use stable external identifiers for correlation.
Integration direction
Example Mapping
| Intercom Field | Canonical Field | Target Field |
|---|---|---|
| Shopify customer.id | customer.externalId | Contact.external_id |
| Shopify customer.email | customer.email | Contact.email |
| Shopify order.id | order.externalId | Contact.custom_attributes.orderId |
| Shopify order.fulfillment_status | order.status | Conversation.context.fulfillmentStatus |
Martini implementation pattern
A Martini workflow consumes Shopify events or retrieves changed resources, validates the customer relationship, and selects only the order fields approved for Intercom. It creates or updates the Contact or conversation context through the Intercom REST API. Idempotency keys, privacy rules, and rate-limit-aware retries prevent repeated updates and unnecessary data exposure.
Martini capabilities used
- workflow orchestration
- API consumption
- mapping and transformation
- data minimization
- business rules
- retry handling
Pattern 4: Publish Approved Content as Intercom Articles
When to use this pattern
Use this pattern when an enterprise content workflow controls help center content and approved publications must be created or updated in Intercom Articles. It supports scheduled reconciliation or source publication events.
Integration direction
Example Mapping
| Intercom Field | Canonical Field | Target Field |
|---|---|---|
| sourceArticle.id | content.externalId | Article.externalId |
| sourceArticle.title | content.title | Article.title |
| sourceArticle.body | content.body | Article.body |
| sourceArticle.locale | content.locale | Article.locale |
Martini implementation pattern
Martini receives a publication event or starts a scheduled reconciliation, retrieves the approved source article, converts rich text and metadata, and creates or updates the corresponding Intercom Article. Rules control publication status, locale, folder or collection mapping, and content ownership. The workflow records the target identifier and routes failed transformations or API calls for retry.
Martini capabilities used
- scheduled workflows
- API consumption
- content transformation
- mapping
- validation
- business rules
- error handling
Applications commonly integrated with Intercom
Intercom can be integrated with customer-data, support, commerce, collaboration, and content platforms. Martini provides the orchestration layer for retrieving complete Intercom resources, applying business rules, mapping data, and coordinating downstream updates without requiring a dedicated Intercom connector.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Align Contacts, Companies, customer ownership, and support context between Salesforce and Intercom. | Salesforce → Martini → Intercom | Use Salesforce events or scheduled reads and Intercom webhooks as triggers. Retrieve complete resources from both APIs, map stable identifiers and customer attributes, apply ownership rules, and perform idempotent upserts in each system. |
| HubSpot | Synchronize contacts, companies, lifecycle attributes, and engagement context across customer-data platforms. | HubSpot → Martini → Intercom | Orchestrate bidirectional REST workflows with field-level mappings, source-of-truth rules, duplicate detection, and checkpointed reconciliation for paginated data. |
| Zendesk | Coordinate support conversations and escalation workflows when teams use both Intercom and Zendesk. | Intercom → Martini → Zendesk | Receive selected Intercom Conversation events, classify them with business rules, create or update Zendesk work items, and persist the downstream identifier to prevent duplicate escalations. |
| ServiceNow | Create incidents or cases when an Intercom conversation requires operational or IT support. | Intercom → Martini → ServiceNow | Validate the Intercom webhook, retrieve the current Conversation, transform customer and issue context, call ServiceNow, and optionally synchronize status changes back to Intercom. |
| Jira | Convert technical customer issues into Jira work items and coordinate resolution status. | Intercom → Martini → Jira | Route selected Conversation events to Jira through a Martini workflow, use the Conversation ID as a correlation key, and handle retries and duplicate issue checks before creating work. |
| Shopify | Add customer, order, fulfillment, and purchase context to Intercom Contacts and Conversations. | Shopify → Martini → Intercom | Consume Shopify events or API data, minimize sensitive order information, map stable customer and order identifiers, and update Intercom through REST workflows. |
| Slack | Notify support or engineering teams about selected Intercom conversations, escalations, or service events. | Intercom → Martini → Slack | Filter Intercom webhook events by team, tag, state, or priority, format a concise notification, and deliver it to the appropriate Slack destination with retry handling. |
| Stripe | Associate billing or subscription context with Intercom Contacts and support interactions without exposing unnecessary payment data. | Stripe → Martini → Intercom | Retrieve approved billing attributes from Stripe, apply privacy and field-selection rules, correlate them to Intercom Contacts, and update only the required customer context. |
How to build a Intercom integration in Martini
Objective
Establish Intercom access using the authentication method appropriate for the workspace and integration model.
Instructions in Martini
- Configure OAuth 2.0, bearer access tokens, or permitted personal access tokens.
- Request only the scopes required for Contacts, Companies, Conversations, Tickets, Articles, or other resources.
- Store tokens, client secrets, and webhook secrets in environment-specific secure configuration.
Objective
Select an event-driven, scheduled, API-led, or migration trigger based on the synchronization requirement.
Instructions in Martini
- Use selected Intercom webhook topics for near-real-time changes.
- Use scheduler-triggered workflows for reconciliation, backfill, and export processing.
- Use a Martini API when internal applications need a controlled Intercom façade.
Objective
Obtain a complete and authoritative Intercom resource rather than relying on a partial event payload.
Instructions in Martini
- Receive and validate the webhook request when an applicable topic exists.
- Call the Intercom REST API to retrieve the current Contact, Company, Conversation, Ticket, or Article.
- Persist cursors, timestamps, and checkpoints for paginated synchronization.
Objective
Coordinate validation, enrichment, routing, target calls, and state management in a maintainable Martini workflow.
Instructions in Martini
- Separate event intake from longer-running processing when appropriate.
- Apply correlation and deduplication before creating downstream objects.
- Use queues or scheduled processing for high-volume reconciliation and export work.
Objective
Convert Intercom structures into canonical and target-specific models while preserving useful identifiers and context.
Instructions in Martini
- Map actual Intercom object fields to target application fields.
- Transform rich text, attachment metadata, custom attributes, statuses, and ownership values as required.
- Apply data-minimization and privacy rules before copying Conversations or attachments.
Objective
Enforce business decisions for ownership, routing, source-of-truth, publication, and duplicate handling.
Instructions in Martini
- Define precedence for email, company identifiers, lifecycle values, and ownership.
- Route Conversations by tags, team, state, priority, or customer attributes.
- Use stable Intercom IDs and deterministic business keys for idempotency.
Common Intercom data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Contacts | Represent people communicating with or being supported by a business, including identity, email, role, custom attributes, and conversation relationships. | Salesforce, HubSpot, Shopify, Stripe, data warehouses | Martini retrieves complete Contacts after supported events, maps stable identifiers and attributes, applies privacy rules, and performs idempotent upserts. |
| Companies | Represent organizations associated with Contacts and customer activity. | Salesforce, HubSpot, ServiceNow, data warehouses | Martini correlates Companies with Contacts, maps ownership and organization attributes, and uses paginated reconciliation with checkpointing. |
| Conversations | Contain customer interactions, messages, participants, assignments, tags, states, and related metadata. | Jira, ServiceNow, Zendesk, Slack, Salesforce | Martini receives selected events, re-fetches current Conversations when payloads are incomplete, applies routing rules, and stores downstream correlation identifiers. |
| Tickets | Represent structured support requests managed through Intercom ticketing functionality. | ServiceNow, Jira, Salesforce, reporting platforms | Martini synchronizes supported ticket events and REST resources, transforms status and ownership fields, and handles duplicate delivery and retry scenarios. |
| Articles | Represent help center content that can be created, updated, searched, and published through the API. | Contentful, Confluence, enterprise content workflows | Martini schedules or receives publication events, converts content and metadata, maps locale and publication state, and retries failed updates. |
| Admins and teams | Represent internal users and groups used for assignment, routing, and ownership of Conversations or Tickets. | Salesforce, ServiceNow, identity and workforce systems | Martini maps Intercom ownership identifiers to target users or groups and applies routing rules before writing assignments. |
Authentication and security considerations
Authentication and access control
Intercom supports OAuth 2.0, bearer access tokens, personal access tokens where enabled, scopes, and resource permissions. Webhooks use Intercom’s signing mechanism and the secret configured for the webhook.
- Use least-privilege scopes for Contacts, Companies, Conversations, Tickets, Articles, and other required resources.
- Store client credentials, access tokens, personal access tokens, and webhook secrets in Martini environment-specific secure configuration.
- Separate development, staging, and production credentials and rotate them according to organizational policy.
- Minimize copied conversation content and attachments and apply downstream retention, redaction, and access controls.
Operational considerations for Intercom integrations
Reliability and operations
Intercom API limits can vary by endpoint, plan, authorization model, or workspace. Workflows should read response headers, throttle requests, and use exponential backoff for transient failures.
- Persist pagination cursors, timestamps, and checkpoints so synchronization can restart safely.
- Treat webhook delivery as at least once; validate signatures and deduplicate using event identifiers or deterministic keys.
- Re-fetch current resources when event payloads are incomplete or arrive out of order.
- Use idempotent upserts for Contacts, Companies, Conversations, Tickets, and Articles.
- Track API versions, permissions, enum values, and deprecations in configuration and test representative payloads.
- Test rich text, localization, publication status, attachment handling, and privacy filtering before production rollout.
Why use Martini instead of scripts or point-to-point integrations?
Integration orchestration rather than isolated scripts
Martini provides a maintainable workflow and API layer between Intercom and enterprise applications. It separates event intake, API calls, transformation, business rules, target writes, and operational state so integration behavior can evolve without duplicating point-to-point code.
- Combine Intercom webhooks with scheduled reconciliation, pagination, exports, and checkpoints.
- Reuse mappings, validation, authentication configuration, and error-handling patterns across workflows.
- Expose controlled Martini APIs when internal applications should not depend directly on Intercom resource details.
- Apply consistent correlation, retry, deduplication, monitoring, and environment-specific deployment practices.
Frequently asked questions
Intercom can be integrated through its REST API, selected webhook event subscriptions, OAuth 2.0 or token-based authentication, and selected bulk, export, and attachment capabilities. Enterprise workflows commonly synchronize Contacts and Companies, route Conversations or Tickets, enrich support context, and publish Articles to or from other systems.
Yes. Martini can consume Intercom’s REST API, receive selected Intercom webhook events, expose internal REST APIs that abstract Intercom operations, and orchestrate mappings, validation, retries, pagination, and synchronization with other applications.
No. A dedicated Intercom connector is not required. Martini can use Intercom’s confirmed native integration mechanisms, including REST APIs, selected webhooks, authentication methods, export capabilities, and attachment references.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Intercom. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Intercom, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
The REST API is Intercom’s principal integration interface and should be used for resource operations. Selected webhooks are suitable for near-real-time changes, while paginated reads, timestamps, exports, and supported bulk capabilities support reconciliation and migration. SOAP is not supported and no general-purpose public GraphQL API was confirmed.
Yes, Intercom supports webhooks for selected Conversation, Contact, Company, Ticket, and Article events. Coverage is resource- and workspace-specific, so integrations should verify the required topic. Martini can validate, deduplicate, normalize, and route these events, with REST retrieval used when payloads are incomplete.
Martini workflows can combine webhook-driven processing with scheduled reconciliation and paginated REST reads. They map Intercom’s Contacts, Companies, Conversations, Tickets, Articles, admins, and teams to canonical and target models, apply business rules, preserve correlation identifiers, and checkpoint progress.
Intercom integrations should account for rate limits, pagination, transient failures, duplicate deliveries, and out-of-order events. Martini can validate requests, store event keys and checkpoints, use idempotent upserts, apply backoff and retry handling, and route persistent failures for monitoring or operational review. Martini can also expose a controlled API façade for internal applications that need standardized Intercom operations.
Related Martini documentation
API Integration
Workflows
Connect Intercom with your enterprise systems
Use Martini to build secure, maintainable Intercom integrations around REST APIs, selected webhooks, synchronization workflows, and reusable data transformation logic.