Docs: System guides

Read Intercom into Maplith

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

Helpdesk · Also known as Intercom Inbox, Intercom Helpdesk · Checked 2026-10-19

On this page

Best path

Recommended: your agent fetches it. Intercom's connector in Claude, its synced app in ChatGPT and its official MCP server let your 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:

Your agent fetches it, with the access you already gave it. Connectors a vendor or client page confirms: Intercom connector in Claude (US-hosted workspaces); Intercom synced app in ChatGPT. Your 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.
Maplith reads an MCP server you already run. Intercom runs Intercom MCP server. Its address is https://mcp.intercom.com/mcp. Documentation: developers.intercom.com. 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 you connect 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 below; you cannot add it under Data sources › Systems as a server you run.
Export files, the fallback that always works. See the export steps below.
Maplith’s own integration. Built, and not open to every workspace yet. Until it opens, 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: you decide what goes in.

The access to give

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".

Choose the narrowest access that covers the data:

Read conversations
Read and list users and companies
Read one user and one company
Read tickets
Read tags
Read admins

Where to click:

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

A key or token made here stays in the tool that reads the system, never in a chat. Maplith asks for one only under Data sources › Systems in the app.

Export steps

Format: CSV Date range: The last three months

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

How much data

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.

An agent that reads rows through a chat reads every one of them, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, an MCP server or an export is the better path.

Maplith’s integration

Status: Built, and not open to every workspace yet. Until it opens, share the export.

How to connect

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.
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.
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.
Scan it from the connection, or wait for the workspace's scan schedule.

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

The permissions it asks for

Permission	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 read during the scan and deleted when it ends
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.

Scans. The connection is scanned on your workspace’s scan schedule, daily or weekly. The first scan is one you ask for from the connection; after that it follows the schedule.

Events. Intercom signs each event it sends to Maplith, and Maplith checks the signature before it reads anything. 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.

Removing 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. 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.

What Maplith sets up once it is connected

Maplith sets these up itself. You correct them; you never have to approve them first. If the system is disconnected, the playbooks Maplith set up and nobody changed are taken out of use, and put back when it is connected again.

Signals it raises:

Something Maplith relies on stopped working (checked on a schedule): a regular check finds the access revoked, Intercom's server unreachable, or none of the read tools offered
A support case was opened in your helpdesk (as it happens): a new conversation arrives in Intercom, or its customer replies after it was closed
A connected system grew or shrank (checked on a schedule): the connection offers at least a quarter more or fewer resources than at the last check
New finding (checked on a schedule): a scan finds a flaw in how conversations are handled, such as a case no one takes

Checks:

Connection check (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 “Something Maplith relies on stopped working” signal is raised.
Work a new Intercom support case. Starts when a new support case opens in Intercom.

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 your own agent may do. Maplith never writes in Intercom. Your agent can, with its own access, once your admin has declared the operation under Agents & access › Policies:

Send a reply on a conversation. Your agent’s own access needs Intercom's Write conversations permission.
Close a conversation that is settled. Your agent’s own access needs Intercom's Write conversations permission.

Events that wake your agent

Intercom sends Maplith an event as soon as something happens, so your agent can start on it without waiting for the next scan. Intercom signs each event, and Maplith checks the signature before it reads anything.

Events arrive through Maplith’s Intercom integration, once it opens to your workspace. Until then, your agent can read Intercom on a schedule; the Markdown version of this page describes how it sends Maplith what changed.

Each of these events raises “A support case was opened in your helpdesk”:

conversation.user.created: opens a case.
conversation.user.replied: opens the case again if it was closed.
conversation.admin.replied: marks the case handled by your team.
conversation.admin.closed: marks the case handled by your team.

Always

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

Sources

Written from public documentation, last checked 2026-10-19:

← All system guides · Markdown version · What your agents do with Intercom