Skip to content

README.md

125 lines · 6.1 KB · Markdown
Raw

@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:

LaneWhen to useCredential
Access token (fastest)Private app for your workspaceUser secret intercomAccessToken (or intercomAccessToken-<purpose>)
OAuthPublic app that accesses another workspaceSaved 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
  1. 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
  2. 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

  1. Approve hosts api.intercom.io, api.eu.intercom.io, and api.au.intercom.io
  2. 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
  1. Create a public Intercom app from https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth
  2. Set the redirect URI exactly to https://kody.codes/connect/oauth
  3. Enable the permissions listed below on the app (Intercom configures these in the Developer Hub; they are not OAuth query scopes)
  4. 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

  1. Paste the Intercom client id and client secret into the Kody wizard (never into chat). Approve the API hosts.
  2. 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 permissionNeeded 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