Intercom

The Intercom tool covers 48 endpoints for inbox conversations, contacts, companies, tags, notes, admins, teams and help center articles. Its key is intercom.

Connect

Variable	Value
`INTERCOM_API_URL`	Base URL. Pass it as the client’s `baseUrl`.
`INTERCOM_ACCESS_TOKEN`	Fake access token. Send `Authorization: Bearer <token>`.

TypeScript

import { IntercomClient } from 'intercom-client';
const intercom = new IntercomClient({ token: process.env.INTERCOM_ACCESS_TOKEN!, baseUrl: process.env.INTERCOM_API_URL });
const open = await intercom.conversations.search({ query: { field: 'state', operator: '=', value: 'open' } });
// open.data is the first page; `for await (const c of open)` walks every page.

This is what ancha connect intercom --lang ts prints.

Endpoints

Method	Path	Support
`GET`	`/me`	supported
`GET`	`/admins`	supported
`GET`	`/admins/:id`	supported
`PUT`	`/admins/:id/away`	supported
`GET`	`/teams`	supported
`GET`	`/teams/:id`	supported
`GET`	`/contacts`	supported
`POST`	`/contacts/search`	partial: common contact fields, tags, companies and custom attributes; segments and device fields are gaps
`POST`	`/contacts`	supported
`GET`	`/contacts/find_by_external_id/:id`	supported
`GET`	`/contacts/:id`	supported
`PUT`	`/contacts/:id`	supported: custom attributes must already exist in the workspace
`DELETE`	`/contacts/:id`	supported
`POST`	`/contacts/:id/archive`	supported
`POST`	`/contacts/:id/unarchive`	supported
`GET`	`/contacts/:id/tags`	supported
`POST`	`/contacts/:id/tags`	supported
`DELETE`	`/contacts/:id/tags/:tag`	supported
`GET`	`/contacts/:id/notes`	supported
`POST`	`/contacts/:id/notes`	supported
`GET`	`/notes/:id`	supported
`GET`	`/contacts/:id/companies`	supported
`POST`	`/contacts/:id/companies`	supported
`DELETE`	`/contacts/:id/companies/:company`	supported
`GET`	`/companies`	supported: by company_id or name, or a page of all
`POST`	`/companies/list`	supported
`POST`	`/companies`	supported: creates, or updates the company with the same company_id
`GET`	`/companies/:id`	supported
`PUT`	`/companies/:id`	supported
`GET`	`/companies/:id/contacts`	supported
`GET`	`/conversations`	supported: newest activity first
`POST`	`/conversations/search`	partial: state, assignment, tags, contacts, source and timestamps; ratings, AI agent and statistics fields are gaps
`POST`	`/conversations`	supported: started by a contact
`GET`	`/conversations/:id`	supported: display_as=plaintext
`PUT`	`/conversations/:id`	partial: read, title and custom attributes; company is a gap
`POST`	`/conversations/:id/reply`	partial: admin comments and notes, contact replies; quick replies and attachments are gaps
`POST`	`/conversations/:id/parts`	supported: close, snooze, open and assign
`POST`	`/conversations/:id/tags`	supported
`DELETE`	`/conversations/:id/tags/:tag`	supported
`GET`	`/tags`	supported
`POST`	`/tags`	partial: create or rename; bulk tagging companies and users is a gap
`GET`	`/tags/:id`	supported
`DELETE`	`/tags/:id`	supported
`GET`	`/articles`	supported
`GET`	`/articles/search`	supported: every word of the phrase in the title, description or body
`GET`	`/articles/:id`	supported
`POST`	`/articles`	partial: collections and translations are gaps
`PUT`	`/articles/:id`	partial: title, description, body and state

Unsupported features on listed routes return HTTP 400 in Intercom’s error shape. Unknown routes return HTTP 404. Both carry x-ancha-gap: 1. The client retries 5xx responses, so these errors use 4xx responses.

Starter data

The starter data is the Acme workspace. Your agent acts as Ancha assistant, ancha@acme.example.

Record	Detail
Admins	Ancha assistant, Mike Turner, Laura Kim, Anna Fischer, Greg Wilson, Ben Carter and Tom Hughes. Tom is away.
Teams	Support, Billing and Engineering escalations.
Tags	VIP, Pilot, Bug, Billing, Feature request and Exports.
Companies	Ridgeway Robotics, Pinecrest Health, Bluefield Logistics, Kestrel Credit Union, Helix Manufacturing and Lakeview Retail.
Contacts	Erin Walsh, Paul Young, Nora Bell, Grace Lin, Carla Diaz, Derek Moss and Isabel Cruz. Isabel is a lead.
Open conversations	Erin cannot find a CSV export, Paul wants to invite a teammate, Nora wants to add seats and Isabel asks about pricing.
Other conversations	Derek’s billing question is snoozed. Grace’s SCIM question and Carla’s duplicate dashboard report are closed.
Articles	Published guides to CSV exports, inviting teammates and SSO with Okta. A seat-proration guide is a draft.

Run ancha twins seed intercom --full to print the complete starter data and the scene seed fields.

Checks

Intercom has no state checks. Use trace checks, for example { called: "POST /conversations/*/reply" } or { not_called: "DELETE /contacts/*" }.

Limits

Tickets, outbound messages, data events, segments, subscriptions and AI agent fields are gaps.
Replies support admin comments, internal notes and contact replies. Quick replies and attachments are gaps.
Contact custom attributes must already exist in the workspace.
Article collections and translations, bulk tagging of companies and users, and conversation ratings and statistics are gaps.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

Connect

Endpoints

Starter data

Checks

Limits

​Connect

​Endpoints

​Starter data

​Checks

​Limits

Connect

Endpoints

Starter data

Checks

Limits