# Intercom: how to read it into Maplith

*Helpdesk · also known as Intercom Inbox, Intercom Helpdesk · last checked 2026-10-19 · recipe `maplith://systems/intercom`*

Customer conversations, tickets, contacts and companies, which show who asks for help, about what, and how fast the team answers.

## Best path

**Recommended: your agent fetches it.** Intercom's connector in Claude, its synced app in ChatGPT and its official MCP server let the customer's own agent read conversations, contacts and companies with access it already has. A small team can have thousands of conversations a month, too many to pass through a chat, so take the history for a first map from the conversation and contact exports.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: Intercom connector in Claude (US-hosted workspaces); Intercom synced app in ChatGPT. The customer's agent uses the Intercom connector it already has to look at a few recent conversations, contacts and companies, read-only, and reports which fields and ids are in use.
2. **Maplith reads an MCP server your human already has.** Official: **Intercom MCP server**. Endpoint to connect to: `https://mcp.intercom.com/mcp`. Documentation (a page to read, not an address to connect to): https://developers.intercom.com/docs/guides/mcp. Access: Sign in with OAuth as an Intercom teammate, or create a private app in the Developer Hub with only read permissions (Read conversations, Read and list users and companies); its access token goes into the client your human connects to the server, never into a chat. The endpoint above is for US-hosted workspaces; EU-hosted workspaces use mcp.eu.intercom.com with the same path, and AU-hosted workspaces are not supported yet. The server offers tools, including write tools (internal notes, Help Center articles), so give it read permissions only. The Claude directory connector covers US workspaces; EU workspaces need a custom connector with the EU endpoint. Maplith reads this server through its own integration, described in *Maplith's integration* below; it is not a server your human adds under Data sources › Systems.
3. **Export files**, the fallback that always works: see *Export steps* below.
4. **Maplith's own integration** (built, and not open to every workspace yet: it opens once it is released; until then, share the export): see *Maplith's integration* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Conversations | One customer conversation in the inbox, with its state, timestamps, assignee and tags. | conversation id, contact id, company id, assigned teammate id, team id, tags, created at, closed at | Contacts by contact id; Companies by company id; CRM contacts and shop customers by the contact's email through Contacts. |
| Contacts (users and leads) | One person the company talks to: a signed-up user or an anonymous lead. | contact id, external user id, email (Maplith tries to mask it), company id, signed up at, last seen at | CRM contacts, shop customers and billing customers by email or by the external user id the company sends from its own product. |
| Companies | One customer company, with the id the company gives it and its custom attributes. | company id, company name, user count, created at, custom attributes | CRM companies and billing customers when the same company id is used there; Contacts and Conversations by company id. |
| Tickets | One ticket of a given ticket type, raised by a customer or the team. | ticket id, ticket type, contact id, linked conversation id, state, created at | Contacts by contact id; Conversations by linked conversation id; order or invoice systems when an order number is kept in a ticket attribute. |
| Teammates and tags | One support teammate or team, and the tags used to sort conversations. | admin id, team id, tag id, tag name | Conversations and Tickets by assigned teammate id, team id and tag. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Read-only access

**Who usually has the rights:** A workspace admin, or a teammate with the permissions "Can access Developer Hub" and "Can install, configure and delete apps".

**For the key your own agent's client uses, choose only these read permissions:** `Read conversations`, `Read and list users and companies`, `Read one user and one company`, `Read tickets`, `Read tags`, `Read admins`

**Where to click:**

1. Open the Developer Hub (under Settings in some workspaces)
2. Your apps
3. New app: give it a name and pick your workspace
4. Configure
5. Authentication
6. Edit the permissions and keep only read permissions
7. Copy the Access Token

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app: for an MCP server it can read, or for its own integration below.

## Export steps

**Format:** CSV · **Date range:** The last three months

1. Conversations: go to Reports, then Dataset export.
2. Pick the Conversations dataset and a time period, choose the columns (keep the ids and the conversation tags), preview, and click Export CSV.
3. Large files are sent by email instead of downloading in the browser.
4. Contacts: go to Contacts, select the users, open the More menu and choose Export users, then pick all columns.
5. The contacts file arrives by email; the download link expires after one hour.

## Volume hint

**About 300–3,000 conversations a month** (an estimate). Estimate for a small company, not a measured figure: one support inbox handling a few to a hundred chats a day.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Maplith's integration

**Status:** built, and not open to every workspace yet: it opens once it is released; until then, share the export.

**How to connect:**

1. In Maplith, open Data sources › Systems and choose Connect Intercom, or click Install on Maplith in Intercom's App Store. You need to be an admin or builder of the workspace.
2. Intercom asks you to approve read access to the workspace: sign in to Intercom as a teammate who may install apps, and approve it there.
3. Intercom returns you to Data sources › Systems. Maplith checks that it is you, in the workspace you started from, before it stores anything; the access token is sealed and never shown again.
4. Scan it from the connection, or wait for the workspace's scan schedule.

**The permissions it needs, and why:**

- `Read conversations`: reads the conversations the support process and the support playbooks are built from: their state, times, assignee and tags
- `Read and list users and companies`: lists the contacts and companies a conversation belongs to, so a case can be joined to the same person or company in the shop or the billing system
- `Read one user and one company`: reads one contact or company when a conversation names it

**What it reads:**

- Conversations, contacts and companies, through the six read-only tools of Intercom's MCP server, as Intercom API pages the build reads and deletes with the run
- Who is on a conversation as an id, its tags, and the message text the support process is described from; Maplith tries to mask personal data in it as it does in an uploaded export
- What reaches the map: the helpdesk's objects, the conversation process (opened, assigned, first reply, closed) and a playbook for each kind of case

**What it never reads or does:**

- Anything that changes Intercom: the server's tools that write an article or an internal note are never called
- Tickets, articles, news items, data exports or settings: the permissions for them are not asked for
- Your access token anywhere but sealed in Maplith: it is never shown again and never sent to a model
- A US- or AU-hosted workspace: only Intercom's EU server is read, so those workspaces share an export or let their own agent read Intercom

**Choosing what is read:** Maplith reads everything the read tools list, whatever its age, up to a bounded amount; there is no filter to set. To read less, share an export instead of connecting.

## What Maplith sets up once it is connected

Maplith builds these itself; a person corrects them, and never has to approve them first (ADR-0038). If the system is disconnected, Maplith takes the playbooks it set up and nobody changed out of use, and puts them back when the system is connected again; a playbook a person changed stays as they left it.

**Signals:**

| Kind | Delivery | When |
|---|---|---|
| `link_dead` | poll | the probe finds the access revoked, Intercom's server unreachable, or none of the read tools offered |
| `support_case_opened` | push | a new conversation arrives in Intercom, or its customer replies after it was closed |
| `structure_changed` | poll | the connection offers at least a quarter more or fewer resources than at the last check |
| `finding_added` | poll | a scan finds a flaw in how conversations are handled, such as a case no one takes |

**Checks:**

- **Connection probe** (every 12 hours): checks that Intercom still grants the access and offers its read tools, and calls none of them
- **Read allow-list** (on every call): refuses any Intercom tool that is not one of the six read tools before a request is sent

**Suggested playbooks:**

- **Reconnect Intercom.** Starts when the Intercom connection's link_dead signal is raised. Steps: Open Data sources › Systems and run Test connection to read the reason; If Intercom no longer grants the access, because the Maplith app was removed there, choose Connect Intercom again; If Intercom could not be reached, wait a few minutes and test again; Run Test connection again and record what was done.
- **Work a new Intercom support case.** Starts when a new support case opens in Intercom. Steps: Read the signal: it carries the conversation id and the tag id, never a message. Open the conversation in Intercom with the access your agent already has; Find the support playbook for the tag and follow it; when there is none, hand the case to a person; Reply or close only after asking Maplith's action gate (request_action), and do it in Intercom with your own access: Maplith never writes there; Record what was done on the signal.

**Schedules:**

- **Read Intercom** (with the workspace's scan schedule (daily or weekly)): the support process and the playbooks stay current with how conversations are actually handled

**What setup integrity expects:**

- The Intercom connection exists and its last probe succeeded
- The intercom source has an owner and a refresh cadence (Maplith states them from the workspace owner and the scan schedule; a person corrects them)
- Each suggested playbook exists, or a person removed it, and is anchored on a signal kind the connection raises

## How the connection works

Every Maplith integration provides the same things. For Intercom:

**Install.** Install it from Intercom's App Store: the listing opens `https://app.maplith.com/install/intercom`, which takes you to Intercom's consent screen. Or open Data sources › Systems and choose "Connect Intercom". You give access once, in Intercom's own consent screen, and never type or paste a token. Before anything is stored Maplith checks:

- The request started in your workspace in the last 15 minutes and was not changed on the way
- You are the same person who started it, still signed in, and still an admin or builder of that workspace
- Connecting Intercom is open in that workspace and it has no Intercom connection yet
- Intercom's server answers and offers the read tools, before the access token is stored

**Read.** Maplith reads Intercom through the read-only tools of its MCP server at `https://mcp.eu.intercom.com/mcp`, from a fixed list: `search_conversations`, `get_conversation`, `search_contacts`, `get_contact`, `list_companies`, `get_company`. A call to anything else is refused before it is sent. It never calls `create_article`, `update_article`, `add_internal_note`, which change something. What it reads is written as Intercom's own API pages, which the build flattens exactly as an Intercom export you upload; Maplith tries to mask personal data in them the same way.

**Scan.** The connection is scanned on the workspace's scan schedule, daily or weekly. The first scan is one you ask for from the connection; after that it follows the schedule. Every 12 hours the connection is checked without reading any content: Intercom must answer and offer its read tools. If it does not, Maplith raises link_dead with the steps that repair it, and clears it when the connection recovers.

**Events.** Intercom signs each event it sends to Maplith's app (header `X-Hub-Signature`, HMAC-SHA1 over the raw body, written as sha1= and hex, with the Maplith app's client secret, held only in Maplith's environment: never per workspace, never in the database, never shown). Maplith checks the signature on the raw request before it reads anything. The workspace comes from Maplith's own record of which Intercom workspace granted access to which Maplith workspace: the Intercom account Maplith reads with the connection's own token when it connects and on every Test and Scan. Nothing in the event chooses it, an event for a workspace Maplith does not know is dropped, and a connection whose access Intercom has refused receives nothing. Topics: `conversation.user.created` raises `support_case_opened`; `conversation.user.replied` raises `support_case_opened`; `conversation.admin.replied` raises `support_case_opened`; `conversation.admin.closed` raises `support_case_opened`. Ids and times only: the conversation id, the tag id and when it happened. Never a message, a name or an email address; receipts are kept for 30 days. The workspace's scan and the connection probe carry the connection when an event is missed.

**Remove it.** Remove under Data sources › Systems first revokes Maplith's access at Intercom with the access token itself, because Intercom's tokens do not expire, and says so. The connection is removed either way. When someone removes the Maplith app in Intercom, Intercom sends an uninstall notification naming the workspace. Intercom does not say it signs it, so Maplith treats it as a hint: it removes the connection and stops its events only once Intercom refuses the stored token. A connection whose token Intercom refuses at any check, the daily probe included, stops receiving events at once. Where Maplith could not revoke its access, the page says so: remove the Maplith app in Intercom, under Settings, Integrations, Apps. The map built from Intercom stays, marked as no longer maintained. Signals and event receipts stay for their retention. The playbooks Maplith set up for it are taken out of use, not deleted.

**Playbooks from the data.**

- One playbook per kind of conversation, by its tag, that enough conversations share, written from Conversations, starting on `support_case_opened`.

**Your own agent.** Maplith never writes in Intercom. Your agent does, with its own access, once Maplith's action gate allows it. Operations your admin can declare under Agents & access › Policies (each is a suggestion, and Maplith performs none of them):

- `helpdesk.reply_to_case`: Send a reply on a conversation. Targets a `conversation`. Your agent's own credential needs Intercom's Write conversations permission.
- `helpdesk.close_case`: Close a conversation that is settled. Targets a `conversation`. Your agent's own credential needs Intercom's Write conversations permission.

Maplith wakes a subscribed agent (ADR-0036) when this connection raises `support_case_opened` or `link_dead`.

## Events that wake your agent

**Event URLs for your own private Intercom app are not available in customer workspaces yet: Maplith rehearses them in its own workspaces first, and Data sources › Systems shows Events from Intercom once yours can use one. Events through Maplith's Intercom app need no URL: they arrive once your workspace has connected Intercom with it.**

Native webhooks: a paid Intercom workspace or a development workspace, with Developer Hub access and Read conversations.

Through Maplith's Intercom app: Intercom signs every notification with X-Hub-Signature, an HMAC-SHA1 of the raw body keyed with the app's client secret, which only Maplith holds; Maplith checks it before it reads anything and refuses a notification that is unsigned or wrongly signed. Through an event URL for your own private app: the URL token authenticates the request, and Intercom's signature is not checked, because it is keyed with your private app's secret, which you never give Maplith.

1. With Maplith's Intercom app, there is nothing to set up: connect Intercom on Data sources › Systems (or install Maplith from Intercom's App Store), and scan it once so the map has its conversations. From then on Intercom sends the topics listed here for your workspace, and a new conversation becomes a support case within seconds. Intercom also sends `ping` (its Developer Hub test sends one); Maplith answers it and stores nothing.
2. With your own private Intercom app instead: build the map from an Intercom export first; choose its system and conversation object under Data sources › Systems › Events from Intercom, create a URL, paste it into your private app's webhook settings and subscribe to the topics listed here. HEAD checks authenticate the URL and store no event. Keep the URL secret, and rotate or revoke it in Data sources › Systems if it is exposed.
3. A conversation's first tag, when it has one, travels as its tag id, so your agent can tell which of your support playbooks applies; Maplith tries to mask a tag id that looks like personal data, as it does the conversation id. Never forward a conversation body, a contact or an email.

- `conversation.user.created` → `support_case_opened` (open)
- `conversation.user.replied` → `support_case_opened` (reply)
- `conversation.admin.replied` → `support_case_opened` (close)
- `conversation.admin.closed` → `support_case_opened` (close)

A new conversation opens one support case: a `support_case_opened` signal keyed `support_case_opened:<system>:<conversation id>`, carrying the system, the tag id and the conversation id, never a message. A customer reply after the case was closed opens it again. A conversation an admin answers or closes in Intercom counts as handled there by your team; if an agent or a person has taken the case, it is marked for them and they close it with their own record; if they let it go without one, it still counts as handled in Intercom.

URL checks send HEAD and store no event. Event receipts keep digests, times, topic and outcome for 30 days; message bodies and personal values are dropped. Maplith tries to mask displayed identifiers. The secret URL is shown once; later choose Rotate URL to replace it.

Where outbound events are unavailable, your own agent can poll Intercom and post the closed event contract to POST /api/watches/ingest, one JSON object per change, with the event URL token as Authorization: Bearer. The object has these properties and no others: type, always "event"; vendor, always "intercom"; topic, one of the topics above; event_id, an id of the change itself, so a retry of the same change is recognised; object_id, the conversation id; observed_at, when the change happened in Intercom, in ISO 8601 UTC ending in Z (2026-10-16T12:00:00Z, at most three decimals), within the last 48 hours; and tag_id, the conversation's first tag id, which is optional and the only property that may be left out. event_id, object_id and tag_id are opaque ids of at most 128 letters, digits, underscores or hyphens. Any other property is refused with 422, which names it. Example: `{"type":"event","vendor":"intercom","topic":"conversation.user.created","event_id":"poll-12345-1792141200","object_id":"12345","observed_at":"2026-10-16T12:00:00Z","tag_id":"4242"}`. Maplith does not poll customer systems for these events.

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-19:

- https://developers.intercom.com/docs/guides/mcp
- https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/oauth-scopes
- https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/installing-uninstalling-apps
- https://developers.intercom.com/docs/publish-to-the-app-store/review-publish-your-app
- https://developers.intercom.com/docs/build-an-integration/learn-more/authentication
- https://www.intercom.com/help/en/articles/8922207-apps-and-integrations-faqs
- https://www.intercom.com/help/en/articles/2046229-export-your-conversations-data
- https://www.intercom.com/help/en/articles/8851609-how-to-export-users-leads-or-company-data
- https://claude.com/connectors/intercom
- https://help.openai.com/en/articles/12562556-intercom-synced-connector
- https://developers.intercom.com/docs/references/webhooks/webhook-models
- https://developers.intercom.com/docs/webhooks
- https://developers.intercom.com/docs/webhooks/setting-up-webhooks