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

# Intercom

> Import contacts, companies, conversations, and tickets from Intercom into Halo. Best for migrating from Intercom or running both in parallel.

## What Intercom adds to Halo

Intercom is an ingest-only integration:

| Mode | What it does |
| - | - |
| **Ingest** | Sync contacts, companies, conversations, and tickets into Halo. Conversation transcripts can be distilled into customer-scoped knowledge. |

Use this when you're:

* **Migrating** from Intercom to Halo and want all your historical data
* **Running both in parallel** during a transition period
* **Backfilling** Halo with the customer history you already have

Connect at **Integrations > Intercom**.

## Setup

### Connecting

Intercom uses **access token + region** auth (not OAuth in this implementation):

1. In your Intercom workspace, generate a **Personal access token** with `read` scopes for contacts, companies, conversations, and tickets.
2. In Halo, click **Connect Intercom**.
3. Paste the token, select your region (`us`, `eu`, or `au`), and submit.

Halo validates the token, encrypts and stores it, and triggers a full historical sync.

### Webhook (optional, near-real-time)

For ongoing sync after the initial backfill:

1. In Intercom, configure a webhook with **`webhook_secret`** (required for verification).
2. Paste the secret into Halo on the Intercom integration page.
3. Set the webhook URL to:

   ```
   https://app.haloagents.ai/api/integrations/intercom/webhook/{orgId}
   ```

Halo verifies signatures using HMAC-SHA1 on the raw body. Topics handled:

| Topic | Action |
| - | - |
| `conversation.user.created` | Create a Halo transcript / ticket |
| `conversation.user.replied`, `conversation.admin.replied`, `conversation.admin.noted` | Append message |
| `conversation.admin.closed`, `conversation.admin.opened`, `conversation.admin.snoozed`, `conversation.admin.unsnoozed` | Sync conversation state |
| `contact.user.created`, `contact.user.updated`, `contact.lead.created`, `contact.lead.updated`, `contact.lead.signed_up`, `contact.email.updated`, `contact.subscribed`, `contact.unsubscribed` | Upsert end user |
| `ticket.created`, `ticket.state.updated`, `ticket.admin.replied`, `ticket.contact.replied`, `ticket.note.created`, `ticket.closed` | Sync ticket |

Without webhooks, Halo still runs hourly cron sync (`cronSync: true`).

## Ingest mode

When ingest is on:

| Data | Where it lands |
| - | - |
| **Contacts** | `end_users` table with `source: intercom` |
| **Companies** | `companies` table with `source: intercom` |
| **Conversations** | `transcripts` table with `metadata.source: intercom` |
| **Tickets** | `tickets` table with `metadata.source: intercom` |
| **Conversation history** | Distilled into knowledge under `intercom:` and `distilled:intercom:` prefixes |

Conversation transcripts are distillable — Halo can run an additional summarization pass to extract customer insights ("Customer always asks about pricing transparency, prefers email follow-ups, has had 3 tickets about SSO").

### Configuration

| Field | Purpose |
| - | - |
| **`user_id_field`** | Which Intercom field to use as the external user ID |
| **`company_id_field`** | Which Intercom field to use as the external company ID |
| **`activity_refresh`** | How often to refresh conversation activity |
| **`webhook_secret`** | Required for webhook verification (encrypted at rest) |

## Migration tips

If you're migrating from Intercom:

1. **Connect Intercom first** to backfill historical data
2. **Configure webhooks** to keep Intercom data flowing during the transition
3. **Set up email forwarding** so new emails come to Halo (see [Receiving Emails](https://docs.haloagents.ai/channels/receiving-emails.md))
4. **Migrate help center articles** using the help center [Migration tool](https://docs.haloagents.ai/help-center/migrating.md)
5. **Switch the chat widget** on your site from Intercom to Halo
6. **Keep Intercom connected** for a few months as a fallback / source of truth
7. **Disconnect Intercom** once you're confident Halo has everything

## Status and stats

The integration page shows:

* Total contacts, companies, conversations, tickets synced
* Last sync time
* Webhook secret status (configured / not configured)

## Where to go next

> **[Help Center Migration](https://docs.haloagents.ai/help-center/migrating.md)**
>
> Import your existing help center articles into Halo.

> **[Receiving Emails](https://docs.haloagents.ai/channels/receiving-emails.md)**
>
> Forward emails into Halo to replace Intercom's inbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.