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

1. Create a private app in the [Intercom Developer Hub](https://app.intercom.com/developers)
   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

3. Approve hosts `api.intercom.io`, `api.eu.intercom.io`, and `api.au.intercom.io`
4. Run the smoke test (see [`AGENTS.md`](./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

5. Paste the Intercom client id and client secret into the Kody wizard (never
   into chat). Approve the API hosts.
6. 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`](./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](https://simpleicons.org/icons/intercom) (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

- [Authentication](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication)
- [OAuth](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth)
- [Contacts](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/contacts)
- [Conversations](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations)
- [Articles](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/articles)