---
title: "Intercom Connector"
description: "Complete Intercom integration guide for syncing contacts, conversations, companies, and engagement events with Brevo via Tajo."
url: https://tajo.io/docs/connectors/support/intercom/
markdown: https://tajo.io/docs/connectors/support/intercom.md
lang: en-US
robots: noindex
---

# Intercom Connector

Connector status: Planned Not built yet. Tajo does not run this connector today.

| Source field | Destination field | Sample value |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Connect your Intercom workspace to Brevo via Tajo for unified customer messaging, conversation tracking, and engagement-driven marketing automation powered by your support and product data.

## Overview

| Property | Value |
| --- | --- |
| **Platform** | Intercom |
| **Category** | Support |
| **Setup Complexity** | Medium |
| **Official Integration** | No |
| **Data Synced** | Contacts, Conversations, Companies, Events |
| **API Base URL** | `https://api.intercom.io` |

## Features

- **Contact sync** - Bidirectional sync of Intercom users and leads with Brevo contacts
- **Conversation tracking** - Sync conversation data for support-driven segmentation
- **Company mapping** - Associate contacts with companies for account-based workflows
- **Custom attributes** - Map Intercom custom attributes to Brevo contact fields
- **Event tracking** - Sync custom events and user activities for behavioral targeting
- **Tag sync** - Map Intercom tags to Brevo list membership or attributes
- **Messenger data** - Track in-app messaging engagement and chat interactions
- **AI agent integration** - Sync AI agent conversation outcomes with Brevo

## Prerequisites

Before you begin, ensure you have:

1. An Intercom workspace (Starter, Pro, or Premium plan)
2. An Intercom app with access token (private app) or OAuth configured (public app)
3. A Brevo account with API access
4. A Tajo account

## Authentication

### Access Token (Private App)

For private integrations that access your own workspace data.

1. Go to Developer Hub > Your Apps > Create new app
2. Associate with your Intercom workspace
3. Copy the access token

```bash
curl https://api.intercom.io/contacts \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Intercom-Version: 2.11"
```

### OAuth 2.0 (Public App)

For integrations that access other customers’ Intercom data.

```bash
# Authorization URL
https://app.intercom.com/oauth?client_id={client_id}&state={state}

# Token exchange
curl -X POST https://api.intercom.io/auth/eagle/token \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={auth_code}"
```

API Versioning

Always include the `Intercom-Version` header in your requests. Tajo uses API version 2.11 by default. Check the Intercom changelog for breaking changes.

## Configuration

### Basic Setup

```yaml
connectors:
  intercom:
    enabled: true
    access_token: "${INTERCOM_ACCESS_TOKEN}"
    api_version: "2.11"

    # Data sync options
    sync:
      contacts: true
      conversations: true
      companies: true
      events: true
      tags: true

    # Sync direction
    direction: intercom_to_brevo

    # Brevo list assignment
    lists:
      all_users: 35
      active_conversations: 36
      leads: 37
```

### Field Mapping

Map Intercom contact data to Brevo contact attributes:

#### Default Mappings

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | Contact email address (unique identifier) |
| `name` optional | string | Full name, split into FIRSTNAME/LASTNAME |
| `phone` optional | string | Maps to SMS attribute for WhatsApp/SMS |
| `role` optional | string | Contact type: user or lead |
| `company.name` optional | string | Associated company name |
| `signed_up_at` optional | timestamp | User signup date |
| `last_seen_at` optional | timestamp | Last active timestamp |
| `custom_attributes` optional | object | Custom attribute key-value pairs |

#### Custom Attribute Mapping

```yaml
field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Engagement fields
  signed_up_at: SIGNUP_DATE
  last_seen_at: LAST_ACTIVE
  session_count: SESSION_COUNT
  unsubscribed_from_emails: UNSUBSCRIBED

  # Company fields
  company.name: COMPANY_NAME
  company.plan: COMPANY_PLAN
  company.size: COMPANY_SIZE

  # Custom attributes
  custom_attributes.plan_tier: PLAN_TIER
  custom_attributes.feature_usage: FEATURE_USAGE
```

## API Endpoints

### Contacts API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/contacts` | List all contacts |
| `POST` | `/contacts` | Create a contact |
| `PUT` | `/contacts/{id}` | Update a contact |
| `GET` | `/contacts/{id}` | Retrieve a contact |
| `POST` | `/contacts/search` | Search contacts |
| `DELETE` | `/contacts/{id}` | Archive a contact |

### Conversations API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/conversations` | List conversations |
| `GET` | `/conversations/{id}` | Retrieve a conversation |
| `POST` | `/conversations` | Create a conversation |
| `POST` | `/conversations/{id}/reply` | Reply to a conversation |
| `POST` | `/conversations/{id}/parts` | Add conversation part |

### Companies API

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/companies` | List companies |
| `POST` | `/companies` | Create or update a company |
| `GET` | `/companies/{id}` | Retrieve a company |
| `GET` | `/companies/{id}/contacts` | List company contacts |

### Events API

| Method | Endpoint | Description |
| --- | --- | --- |
| `POST` | `/events` | Submit an event |
| `GET` | `/events?type=user&intercom_user_id={id}` | List user events |

## Events

### Conversation Events

| Event | Trigger | Use Case |
| --- | --- | --- |
| `conversation.created` | New conversation started | Support ticket alert |
| `conversation.closed` | Conversation resolved | CSAT survey trigger |
| `conversation.rating.added` | Rating submitted | Satisfaction tracking |
| `conversation.snoozed` | Conversation snoozed | Follow-up scheduling |

### Contact Events

| Event | Trigger | Use Case |
| --- | --- | --- |
| `contact.created` | New contact added | Welcome sequence |
| `contact.updated` | Contact data changed | Attribute sync |
| `contact.deleted` | Contact archived | Cleanup |
| `contact.tag.created` | Tag added to contact | Segment update |

### User Events

| Event | Trigger | Use Case |
| --- | --- | --- |
| `user.created` | New user signed up | Onboarding flow |
| `user.email.updated` | Email changed | Contact merge |
| `user.unsubscribed` | Unsubscribed from emails | Preference update |

## Code Examples

### Initialize Connector

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Intercom
await tajo.connectors.connect('intercom', {
  accessToken: process.env.INTERCOM_ACCESS_TOKEN,
  apiVersion: '2.11'
});
```

### Sync Contacts and Conversations

```javascript
// Full sync of contacts and conversation data
await tajo.connectors.sync('intercom', {
  type: 'full',
  resources: ['contacts', 'conversations', 'companies'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('intercom');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 14200,
//   conversationsSynced: 28400,
//   companiesSynced: 2100
// }
```

### Handle Intercom Webhooks

```javascript
import crypto from 'crypto';

app.post('/webhooks/intercom', async (req, res) => {
  const signature = req.get('X-Hub-Signature');
  const expectedSig = 'sha1=' + crypto
    .createHmac('sha1', process.env.INTERCOM_CLIENT_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).send('Unauthorized');
  }

  await tajo.connectors.handleWebhook('intercom', {
    topic: req.body.topic,
    data: req.body.data
  });

  res.status(200).send('OK');
});
```

## Rate Limits

Intercom applies rate limits based on your plan:

| Plan | Rate Limit | Details |
| --- | --- | --- |
| Starter | 20 requests/10 seconds | Per app |
| Pro | 50 requests/10 seconds | Per app |
| Premium | 100 requests/10 seconds | Per app |
| Search endpoint | 1 request/second | Per app |
| Scroll endpoint | 1 request/minute | Per app |

Additional limits:

- **Bulk operations**: 15 contacts per bulk request
- **Event submissions**: 500 events/second per workspace
- **Webhook delivery**: Automatic retry for 24 hours
- **Data export**: 1 concurrent export

Rate Limit Response

Intercom returns `429 Too Many Requests` with a `Retry-After` header. Implement exponential backoff and respect the retry window.

## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
| --- | --- | --- |
| 401 Unauthorized | Invalid or expired token | Regenerate access token in Developer Hub |
| Contact not synced | Missing email field | Intercom leads may lack email; filter by role |
| Conversation data empty | App lacks conversation scope | Re-authorize with conversation read permissions |
| Webhook not received | Webhook not registered | Configure webhooks in Developer Hub settings |
| API version mismatch | Breaking changes in new version | Pin API version with `Intercom-Version` header |

### Debug Mode

Enable verbose logging:

```yaml
connectors:
  intercom:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### Test Connection

```bash
tajo connectors test intercom
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Conversations readable
# ✓ Companies readable
# ✓ Webhooks registered
```

## Best Practices

1. **Pin API version** - Always specify `Intercom-Version` to avoid breaking changes
2. **Use search API efficiently** - Use filters and pagination to reduce data transfer
3. **Sync both users and leads** - Capture the full funnel in Brevo
4. **Map conversation tags** - Use conversation tags for post-support marketing segments
5. **Track custom events** - Submit key product events to Intercom for behavioral targeting
6. **Handle contact merges** - Implement merge logic for duplicate contacts

## Security

- **Access Token** - Bearer token authentication for private apps
- **OAuth 2.0** - Delegated authorization for public apps with client secret
- **Webhook verification** - HMAC SHA-1 signature validation via `X-Hub-Signature`
- **TLS encryption** - All API communication encrypted via HTTPS
- **Data access controls** - Granular data access per app configuration

## Related Resources

- [Intercom Developer Documentation](https://developers.intercom.com/docs)
- [Intercom API Reference](https://developers.intercom.com/docs/references/introduction)
- [Zendesk Connector](https://tajo.io/docs/connectors/support/zendesk)
- [Customer Sync Skill](https://tajo.io/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/docs/contact-management)

## Open-Source Implementation Map

This section is derived from official or public repository material discovered for the Intercom connector. Use it as the engineering companion to the setup guide above: it shows where the API surface lives, what implementation assets exist, and how Tajo should translate them into reliable Brevo sync behavior.

### Repository Snapshot

| Repository | Commit | Languages / formats | Files |
| --- | --- | --- | --- |
| [intercom/Intercom-OpenAPI](https://github.com/intercom/Intercom-OpenAPI) | 58585fd | JSON (24), Markdown (22), JavaScript (17), YAML (12), YAML (10), sh (1) | 90 |
| [intercom/intercom-mcp-server](https://github.com/intercom/intercom-mcp-server) | 96140be | svg (4), Markdown (1) | 5 |

### Integration Shape

```mermaid
graph LR
  Source["Intercom API / repository"] --> Auth["Auth and scopes"]
  Source --> Objects["Objects, events, and schemas"]
  Auth --> Tajo["Tajo connector runtime"]
  Objects --> Tajo
  Tajo --> Brevo["Brevo contacts, attributes, lists, campaigns"]
  Tajo --> Ops["Backfill, cursor, retries, logs"]
```

### What To Reuse

- Intercom REST API OpenAPI Description
- This repository contains OpenAPI descriptions for Intercom’s REST API.
- It defines the HTTP interface used to integrate with Intercom’s customer engagement and support platform.
- **Supported API versions:** 2.7 and higher.

---

### Tajo Revamp Checklist

- Keep authentication setup aligned with the vendor docs and the public repository’s current API shape.
- Map primary resources into explicit Tajo sync objects with stable external IDs.
- Prefer cursor-based or updated-at incremental sync where the API exposes it; otherwise document the fallback.
- Treat webhook handlers as idempotent and replay-safe, especially for order, contact, ticket, and campaign events.
- Capture pagination, rate limits, retry headers, and partial-failure behavior in connector smoke tests.
- Keep examples small and runnable against sandbox or test-mode accounts.

### Sources

- [intercom/Intercom-OpenAPI](https://github.com/intercom/Intercom-OpenAPI)
- [intercom/intercom-mcp-server](https://github.com/intercom/intercom-mcp-server)
- [Vendor documentation](https://developers.intercom.com/)