> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intercom

> Integration details and setup guide for the Intercom connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                                                                          |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens) or Bearer Token                                                               |
| **Two-Way Sync**                    | No                                                                                                                               |
| **Events Supported**                | No                                                                                                                               |
| **Realtime**                        | Polling                                                                                                                          |
| **Supports Rate Limiting**          | Yes (429 handling & rate limit headers)                                                                                          |
| **Authentication Scopes Supported** | `read_contacts`, `write_contacts`, `read_conversations`, `write_conversations`, `read_articles`, `write_articles`, `read_admins` |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Intercom**:

* **Contacts**
* **Admins**
* **Articles**
* **Conversations**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Offers free trial?**                             | Yes. Intercom offers a 14-day free trial. Sign up at [https://www.intercom.com/](https://www.intercom.com/). |
| **Requires paid sandbox**                          | No. You can use the trial account for testing.                                                               |
| **Requires partnership to obtain authentication?** | No. Anyone can create an Intercom app and generate API credentials.                                          |

***

### Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

#### Create your OAuth app

1. Go to **Intercom Developer Hub** ([https://app.intercom.com/a/apps/\_/developer-hub](https://app.intercom.com/a/apps/_/developer-hub))
2. Click **New app** to create a new application
3. Fill in your app details:
   * **App name**: Your application name
   * **Description**: Brief description of your app
4. Configure OAuth settings:
   * Add the redirect URI: `https://api.runalloy.com/api/strategy/connector/intercom/callback`
   * Select required scopes based on your needs:
     * `read_contacts` - Read access to contacts
     * `write_contacts` - Write access to contacts
     * `read_conversations` - Read access to conversations
     * `write_conversations` - Write access to conversations
     * `read_articles` - Read access to help center articles
     * `write_articles` - Write access to help center articles
     * `read_admins` - Read access to admin information
5. Copy your **Client ID** and **Client Secret**
6. Configure these credentials in Alloy Automation

#### API Documentation

* Intercom API Reference: [https://developers.intercom.com/docs/references/rest-api](https://developers.intercom.com/docs/references/rest-api)
* OAuth Guide: [https://developers.intercom.com/docs/build-an-integration/learn-more/authentication](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication)

***

## Use Cases

### 1) Unified customer support data

Sync Intercom conversations, contacts, and support tickets into your data warehouse or CRM, creating a single source of truth for customer interactions and support history.

### 2) Automated contact enrichment

Automatically create and update Intercom contacts when new users sign up or customer data changes in your application, ensuring your support team always has the latest information.

### 3) Help center content synchronization

Sync Intercom help center articles to external documentation systems, knowledge bases, or search platforms to make support content accessible across multiple touchpoints.

### 4) Conversation routing and analytics

Pull conversation data to analyze support patterns, measure response times, and route high-priority conversations to appropriate teams based on custom business logic.

### 5) Cross-platform messaging

Integrate Intercom conversations with other messaging platforms or ticketing systems, enabling support teams to manage customer communications from a unified interface.

***

## API Gotchas

* **API versioning**: Intercom requires the `Intercom-Version` header (e.g., `2.14`) on all requests. Always specify the API version to ensure consistent behavior. Missing this header may result in unexpected responses or errors.
* **Cursor-based pagination**: Most list endpoints use cursor-based pagination with `starting_after` parameter. You must store the `pages.next.starting_after` value from the response to fetch the next page - page numbers are not supported for these endpoints.
* **Search vs List**: The `/contacts/search` endpoint offers powerful filtering capabilities but has different rate limits than `/contacts`. Use search for complex queries and list for simple pagination.
* **Rate limiting**: Intercom enforces rate limits per workspace. When you receive a `429` response, check the `X-RateLimit-Reset` header to determine when you can retry. Implement exponential backoff to avoid repeatedly hitting rate limits.
* **Contact roles**: When creating contacts, you must specify a `role` field (typically `user`). Missing this required field will result in a validation error.
* **Date formats**: Intercom uses both ISO 8601 date-time strings (for most fields) and Unix timestamps (for certain fields like `signed_up_at`). Ensure your integration handles both formats correctly based on the field being used.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.