> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/intercom.md).

# Intercom

## OAuth app properties

| Property                | Value                                                                                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Multi-tenant**        | **Conditional.** Other Intercom workspaces can install the app only after Intercom approves it as a public app (listed or unlisted). Before that it works only for you and your team.                                                                                                            |
| **Vendor review**       | **Required** for other workspaces: App Partner Program details, a description of the app with test credentials, a video of the OAuth install, the app's features and the uninstall, and scopes that match the features. An App Store listing is optional.                                        |
| **Review time**         | Up to 7 business days.                                                                                                                                                                                                                                                                           |
| **Users before review** | Only your own team.                                                                                                                                                                                                                                                                              |
| **App owner**           | An Intercom development workspace, created in the [Developer Hub](https://developers.intercom.com/). Development workspaces exist only in the US region.                                                                                                                                         |
| **Regions**             | Intercom hosts workspaces in the US, EU and AU and does not publish a per-region app rule. The connector sends users to the US sign-in page (`app.intercom.com`), where EU and AU users pick their region, and calls `api.intercom.io`, which Intercom tries to route to the workspace's region. |
| **Client secret**       | No expiry documented.                                                                                                                                                                                                                                                                            |
| **Rate limits**         | 10,000 calls per minute per app and workspace; 25,000 per minute per workspace across all its apps. Spread over 10-second windows.                                                                                                                                                               |
| **Checked**             | 2026-11-13                                                                                                                                                                                                                                                                                       |

**Limitations**

* Scopes are set on the app's **Authentication** page, not by the connector, and Intercom reviews them. A component whose data needs a scope the app does not have fails.
* Intercom spreads the per-minute limit over 10-second windows, so a short burst can hit `429` while the minute total is still under the limit.
* After approval the app is public but unlisted. Users install it through the Appmixer connect flow, not from the Intercom App Store.

Sources: [Setting up OAuth](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth), [App review and publishing](https://developers.intercom.com/docs/publish-to-the-app-store/review-publish-your-app), [Rate limiting](https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting), [About the REST API](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis). What the rows mean: [OAuth app properties](https://docs.appmixer.com/connector-configuration/oauth-app-properties.md).

## Intercom – Connector Configuration

### Step 1: Create a Developer Account & Access Developer Hub

* Sign in to your Intercom account at [Intercom](https://www.intercom.com/)
* Navigate to the [Intercom Developer Hub](https://developers.intercom.com/)
* Go to **Your Apps** section in the Developer Hub

> ⚠️ **Note**: You need an existing Intercom workspace to create developer apps.

***

### Step 2: Create Your App

1. **Create a new app**:
   * Click **"New app"** or **"Create app"**
   * Provide an **App name** (e.g., "My Integration")
   * Add an **App description** explaining what your integration does
   * Select your **Workspace** from the dropdown
2. **App Configuration**:
   * Choose **"Internal integration"** for private use within your workspace
   * Or choose **"Public app"** if you plan to distribute it publicly

***

### Step 3: Configure OAuth Settings

1. **Navigate to Authentication**:
   * In your app dashboard, go to the **"Authentication"** section
   * Select **"OAuth"** as the authentication method
2. **Set up OAuth Configuration**:
   * **Redirect URLs**: Add your callback URL
   * **Scopes**: Select the permissions your app needs:
     * `read_conversations` - Read conversations and messages
     * `write_conversations` - Create and update conversations
     * `read_contacts` - Read contact information
     * `write_contacts` - Create and update contacts
     * `read_teams` - Read team information
     * And other scopes as needed for your integration

👉 For Appmixer, set the redirect URI to:

```http
https://[YOUR_API_BASE]/auth/intercom/callback
```

Example:

```http
https://api.appmixer.com/auth/intercom/callback
```

***

### Step 4: Copy Your Credentials

After configuring OAuth, you'll find your credentials in the **Authentication** section:

* **Client ID** - Found in the OAuth section
* **Client Secret** - Found in the OAuth section

⚠️ **Important**: Keep your Client Secret secure and never expose it in client-side code!

***

### Step 5: Configure Webhooks (Optional)

If your integration needs real-time updates:

1. **Go to Webhooks section**:
   * Navigate to **"Webhooks"** in your app dashboard
   * Click **"Create webhook"**
2. **Webhook Configuration**:
   * **Webhook URL**: Your endpoint to receive webhook notifications
   * **Topics**: Select events you want to subscribe to:
     * `conversation.created`
     * `conversation.updated`
     * `contact.created`
     * `contact.updated`
     * And others as needed
3. **Webhook Security**:
   * Note the **Webhook Secret** for verifying webhook signatures
   * Use this to validate that webhooks are coming from Intercom

***

### Step 6: Install and Test the App

Put the Client ID and Client Secret into the Appmixer Backoffice, see [Backoffice configuration](#backoffice-configuration).

1. **Install your app**:
   * In the app dashboard, click **"Install app"**
   * This will install the app to your selected workspace
2. **Generate Access Token** (for testing):
   * Go to **"Configure"** -> **"Authentication"**
   * Generate a test access token if needed for development
3. **API Testing**:
   * Use the generated credentials to test API calls
   * Intercom API base URL: `https://api.intercom.io/`
   * Include `Authorization: Bearer <access_token>` header in requests

***

### Step 7: Going Live

When ready for production:

1. **App Review** (for public apps):
   * Submit your app for Intercom's review process
   * Provide detailed information about your app's functionality
   * Include privacy policy and terms of service links
2. **App Store Listing** (optional):
   * If approved, your app can be listed in the Intercom App Store
   * Configure app store listing with screenshots and descriptions

***

### Important Notes

⚠️ **Rate Limits**:

* Intercom has rate limits based on your plan
* Standard: 1,000 requests per minute
* See [Intercom Rate Limits](https://developers.intercom.com/intercom-api-reference/reference/rate-limiting) for details

⚠️ **API Versions**:

* Intercom uses API versioning via headers
* Always specify the API version: `Intercom-Version: 2.10`

⚠️ **Scopes**:

* Request only the minimum scopes needed for your integration
* Users will see all requested permissions during OAuth flow

***

### Useful Links

* [Intercom Developer Documentation](https://developers.intercom.com/)
* [API Reference](https://developers.intercom.com/intercom-api-reference)
* [OAuth Guide](https://developers.intercom.com/building-apps/docs/oauth)
* [Webhook Documentation](https://developers.intercom.com/building-apps/docs/webhooks)
* [Rate Limits](https://developers.intercom.com/intercom-api-reference/reference/rate-limiting)

***

## Backoffice configuration

Configuration ID: `appmixer:intercom` (Backoffice → Configuration; see [Connector Configuration](https://docs.appmixer.com/getting-started/services) for how a configuration is created and how its keys reach the connector).

* `clientId` — Client ID of the Intercom app from Step 4. Not needed when Intercom is authenticated through the Appmixer Auth Hub.
* `clientSecret` — Client secret of the same app. Not needed with the Auth Hub.
* `outputFilePrefix` — Optional. File name prefix of the CSV file that **FindCompanies**, **FindContacts**, **FindConversations**, **ListAdmins**, **ListSegments** and **ListTags** create when their output is set to a file. Default `intercom-objects-export`.

![blankImage](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-1861428ad939fdf3b1a5ec312de3e30f220bc634%2FintercomImage-1.png?alt=media)

![blankImage](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-8d6bad906178639d95d533a7517bdb542406f0db%2FintercomImage-2.png?alt=media)

The same keys can be set with the CLI (`-u` updates the existing configuration instead of creating it):

```bash
appmixer service-config set appmixer:intercom -u -d '{
  "clientId": "<client id>",
  "clientSecret": "<client secret>"
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/intercom.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
