Intercom

Intercom

This connector works with one Intercom workspace through the Intercom REST API, version 2.16 (https://api.intercom.io, or the EU or Australian host): contacts (users and leads) with their tags, notes and companies, companies, conversations (read, search, reply, notes, assign, snooze, close, reopen, tags), tickets (search, read, reply, update), the Help Center (articles and collections), and the workspace's admins, teams, tags, segments and data attributes. Every call sends Intercom-Version: 2.16 and the workspace access token as a Bearer token.

Setup (about 5 minutes)

1. Sign in to the workspace as an admin and open the Developer Hub: https://app.intercom.com/a/apps/_/developer-hub (or Settings → Integrations → Developer Hub; EU and Australian workspaces use the same path on app.eu.intercom.com or app.au.intercom.com).
2. Click New app, name it (for example "AnythingMCP"), choose the workspace and click Create app. The app is installed on that workspace at once; your own workspace needs no OAuth and no app review.
3. Open the app's Configure → Authentication page. It shows the workspace Access token and the permissions it carries. For every tool here, grant: Read and list users and companies, Write users and companies, Read conversations, Write conversations, Read tickets, Write tickets, Read and List articles, Read and Write Articles, Read admins, Read tags, Write tags. After changing permissions, regenerate the token (the page links to it) and use the new one.
4. Paste the token into INTERCOM_ACCESS_TOKEN, without the word Bearer. Treat it like a password: it opens the workspace's customer data.
5. Set INTERCOM_API_URL to the region of your workspace: https://api.intercom.io (US, you open app.intercom.com), https://api.eu.intercom.io (EU, app.eu.intercom.com) or https://api.au.intercom.io (Australia, app.au.intercom.com).
6. Install and run intercom_get_me: it returns your admin id and the workspace with its region.

Read-only setup: grant only the read permissions (Read and list users and companies, Read conversations, Read tickets, Read and List articles, Read admins, Read tags) and switch off the write tools here. The three search tools only read, although they are POST requests.

Trying it out: a free development workspace from https://app.intercom.com/admins/sign_up/developer is enough. It lives in the US region, sends no emails or push notifications, holds up to 20 users and leads, and can never become a production workspace.

Acting as an admin: replies, notes, assignment, snooze, close, reopen and conversation tags need admin_id, the teammate the action is credited to. Use the id from intercom_get_me, or another admin from intercom_list_admins. intercom_create_article needs an author_id the same way.

Customers see some of this: confirm first.

• intercom_reply_to_conversation posts a message the customer sees in the Messenger, or receives by email for email conversations. intercom_close_conversation with a body posts that text too. intercom_reply_to_ticket with message_type comment is shown to the customer.
• Notes (intercom_add_conversation_note, intercom_add_contact_note, intercom_reply_to_ticket with message_type note, the default) are only visible to teammates.
• intercom_create_article makes a draft unless state is published. intercom_update_article on a published article changes the public Help Center at once; state draft takes it offline.
• Before any customer-visible message or publishing, show the text and wait for the user's yes. intercom_delete_contact, intercom_delete_article and intercom_delete_collection are installed switched off; intercom_archive_contact is the reversible way to hide a contact.

Searching: intercom_search_contacts, intercom_search_conversations and intercom_search_tickets take a query, either one condition {"field": "email", "operator": "=", "value": "[email protected]"} or a group {"operator": "AND", "value": [ ... ]} (or OR; at most 2 levels of nesting and 15 conditions per group). Operators: =, !=, IN and NIN (value is an array), <, <=, >, >= (numbers), ~ (contains), !~, ^ (starts with), $ (ends with). Which ones a field accepts depends on its type (for contacts: text takes all but the comparisons, true/false only =, !=, IN and NIN, tag_id only = and !=). Dates are Unix timestamps in seconds and are matched by whole day in the workspace's timezone; on contact dates only =, < and > work. Useful fields:

• contacts: email, name, phone, external_id, role (user or lead), created_at, last_seen_at, tag_id, segment_id, location.country, custom_attributes.<name> (intercom_list_data_attributes lists the names);
• conversations: open, state (open, closed, snoozed), admin_assignee_id, team_assignee_id, contact_ids, tag_ids, priority, source.author.email, source.body (matches single words only), created_at, updated_at;
• tickets: ticket_type_id, open, state, title, category (request for customer tickets, task for back-office, tracker), contact_ids, admin_assignee_id, created_at. A contact created a few minutes ago may not be searchable yet.

Paging

• Cursor: intercom_list_contacts, intercom_list_conversations and the three search tools take per_page (default 20 here, max 150) and starting_after, the value of pages.next.starting_after in the previous answer. No pages.next means the last page.
• Page numbers: intercom_list_companies, intercom_list_articles and intercom_list_collections take page and per_page.
• intercom_list_companies only returns companies that have at least one contact, and at most 10,000 of them.

Ids: contacts have 24-character hex ids; conversations have numeric ids sent as text. Tickets have an id (use this one) and a ticket_id, the #number in the Inbox, which the API does not accept. Companies have Intercom's id and your own company_id; tools that take a company_id argument mean Intercom's id except intercom_create_or_update_company and the company_id filter of intercom_list_companies. Tag ids come from intercom_list_tags or intercom_create_tag (which returns the existing tag when the name is taken).

What changed in 2.16: an unassigned conversation reports admin_assignee_id and team_assignee_id as 0, not null; priority is none, low, medium, high or urgent; articles report their collections as parent_ids, while creating or moving one still takes parent_id and parent_type.

Empty workspaces: lists come back with an empty data (or conversations, admins, teams, segments) array; be ready for the key to be missing altogether.

Limits: by default 10,000 calls a minute per app and 25,000 per workspace, spread over 10-second windows. The X-RateLimit-Remaining and X-RateLimit-Reset headers show what is left; a 429 means wait a few seconds.

Common errors ({"type": "error.list", "errors": [{"code": "...", "message": "..."}]})

• 401 unauthorized / token_unauthorized: the token is wrong, was regenerated or the app was uninstalled, or INTERCOM_API_URL is not your workspace's region.
• 403 forbidden / api_plan_restricted: the token lacks a permission (step 3), or the plan does not include the feature, e.g. tickets.
• 404 not_found: wrong id; for tickets, the Inbox number instead of the id.
• 410 contact_merged: the contact was merged into another; search by email for the surviving one.
• 400 parameter_invalid / parameter_not_found: a bad search condition, an unknown field, a missing admin_id, or a date operator that dates do not support.
• 429 rate_limit_exceeded: wait and retry.

Out of scope here: starting outbound messages and creating conversations or tickets, deleting conversations, merging contacts, data events, news items, macros, Fin, custom objects, calls, data exports, webhooks and workspace settings.