@kody/intercom

Read Intercom contacts, conversations, and articles, with dry-run writes.

OtherTopics: intercom, contacts, conversations, articles, help-center, oauth, access-token, multi-account

Version: 1.0.0
License: MIT
Published: September 10, 2026
Pinned commit: 8851e58
Rating: No ratings yet
Forks: 1
Adaptation effort: —

README

@kody/intercom

Intent

Provide reusable, account-agnostic Intercom helpers so Kody agents can read contacts, conversations, and Help Center articles through a saved intercom / intercom-* OAuth integration or a workspace access token — without hand-rolling REST. Mutations are previewable with dryRun: true and only run live after confirm: true.

This listing is meant to be forked. After you fork, connect your Intercom workspace. Do not treat the live @kody/intercom package storage as yours. No workspace ids, admin ids, or contact ids are baked in.

Share this package as https://kody.codes/@kody/intercom (never a /community/{listing_id} URL).

What it does

List, get, or search contacts, conversations, and Help Center articles
Preview or apply contact / conversation / article writes after confirmation
Call an unwrapped Intercom REST path through ./request
Connect more than one Intercom workspace via integrationName / account
Optional disabled-by-default workspace-health job (read-only counts)

Prerequisites / setup

Intercom has no built-in Kody OAuth app. Choose one lane:

Lane	When to use	Credential
Access token (fastest)	Private app for your workspace	User secret `intercomAccessToken` (or `intercomAccessToken-<purpose>`)
OAuth	Public app that accesses another workspace	Saved integration `intercom` or `intercom-<purpose>`

Both lanes send Authorization: Bearer … plus Intercom-Version: 2.14. Required API hosts: api.intercom.io, api.eu.intercom.io, api.au.intercom.io. Approve them in the account secrets UI. Never paste tokens into chat.

Lane A — Access token

Create a private app in the Intercom Developer Hub and copy the access token from Configure → Authentication. Docs: https://developers.intercom.com/docs/build-an-integration/learn-more/authentication
Save the token (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=intercomAccessToken&description=Intercom%20workspace%20access%20token&allowedHosts=api.intercom.io%2Capi.eu.intercom.io%2Capi.au.intercom.io&scope=user

Approve hosts api.intercom.io, api.eu.intercom.io, and api.au.intercom.io
Run the smoke test (see AGENTS.md)

For a second workspace/token, use a distinct secret name such as intercomAccessToken-work and pass secretName: 'intercomAccessToken-work' (or account: 'work', which resolves to intercom-work / intercomAccessToken-work).

EU or AU workspaces: pass region: 'eu' or region: 'au' (or apiBaseUrl) on each call. Hosts stay generic — never hard-code a workspace id.

Lane B — BYO OAuth

Create a public Intercom app from https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth
Set the redirect URI exactly to https://kody.codes/connect/oauth
Enable the permissions listed below on the app (Intercom configures these in the Developer Hub; they are not OAuth query scopes)
Connect while signed in to Kody:

https://kody.codes/connect/oauth?provider=intercom&authorizeUrl=https%3A%2F%2Fapp.intercom.com%2Foauth&tokenUrl=https%3A%2F%2Fapi.intercom.io%2Fauth%2Feagle%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.intercom.io&flow=confidential&pkce=false&allowedHosts=api.intercom.io%2Capi.eu.intercom.io%2Capi.au.intercom.io&dashboardUrl=https%3A%2F%2Fdevelopers.intercom.com%2Fdocs%2Fbuild-an-integration%2Flearn-more%2Fauthentication%2Fsetting-up-oauth

Paste the Intercom client id and client secret into the Kody wizard (never into chat). Approve the API hosts.
Reconnect later with https://kody.codes/connect/oauth?provider=intercom

Authorize URL: https://app.intercom.com/oauth (use app.eu.intercom.com or app.au.intercom.com for those regions). Token URL: https://api.intercom.io/auth/eagle/token. Flow: confidential (client secret). Intercom access tokens do not use refresh tokens; reconnect if a token is revoked.

To connect a second workspace, change provider (for example provider=intercom-work) and pass integrationName: 'intercom-work' on every call.

Permissions

Developer Hub permission	Needed for
Read admins	`./me`, `./smoke-test`
Read and list users and companies	`./list-contacts`, `./get-contact`, `./search-contacts`
Read and write users	`./create-contact`, `./update-contact`
Read conversations	`./list-conversations`, `./get-conversation`, `./search-conversations`
Write conversations	`./reply-conversation`, `./close-conversation`
Read and List articles	`./list-articles`, `./get-article`
Read and Write Articles	`./create-article`, `./update-article`

If Intercom returns 401/403, helpers throw a message that names the missing permission and the next setup URL (reconnect OAuth, or save an access token).

Agents: see AGENTS.md for import paths, smoke checks, and mutation guards.

Done when

Access token intercomAccessToken is saved or OAuth intercom is connected; hosts api.intercom.io / api.eu.intercom.io / api.au.intercom.io are approved
Smoke test returns ok: true (live admin id when credentials exist; no email)
Mutating helpers refuse unless confirm: true; dryRun: true never calls Intercom

Branding

community-icon.svg is Intercom's official logomark from Simple Icons (product mark, unmodified path, Intercom brand black #1A1A19 on Intercom cream #F4F4EC so the smile stays legible at 56px). Intercom® is a trademark of Intercom, Inc. This package is not affiliated with or endorsed by Intercom.

Docs

Report this listing