Intercom connector setup

This page is the setup half — creating the OAuth app Intercom needs in its own Developer Hub and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Intercom.

1. Create the OAuth app in the Intercom Developer Hub

1. In Intercom, open the Developer Hub and create a new app against your own workspace — this is your own app, not Botseon's. Intercom's own walk-through is Setting up OAuth.

2. Under Configure → Authentication, turn on Use OAuth and add the redirect URL from docs/connectors/README.md. Intercom accepts only HTTPS redirect URLs, so the quickstart's plain-HTTP address has to sit behind TLS first; its path is:

   http://127.0.0.1:3000/api/oauth/intercom/callback
   

3. Open Basic information. The Client ID and Client secret are there — copy both.

An app that only ever reaches the workspace it was created in needs no review. An app that other companies' workspaces install is a public app in Intercom's terms, and Intercom reviews it before any other workspace can install it, listed or unlisted, in up to seven business days.

2. Scopes

Intercom does not take scopes on the authorize URL: the permissions are checkboxes on the app's Authorization page, chosen once for every workspace that installs it. Tick the reads and the writes this connector uses — reading and writing conversations, reading contacts, and reading and attaching tags — and nothing more (F-PLUG-1: minimum scopes per capability).

Because the grant cannot be split into a read half and a write half, the plugin sheet shows one sentence for it rather than a scope list: Intercom grants all or nothing, so this account can read and change everything the app was given. The separation lives in the tools instead — every tool that writes raises an approval card first.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug intercom \
  --client-id <the client ID from step 1> \
  --auth-url https://app.intercom.com/oauth \
  --token-url https://api.intercom.io/auth/eagle/token \
  --configured-by <your user id>

For a deployment whose members' workspaces are hosted in the EU or Australia, the authorize URL is https://app.eu.intercom.com/oauth or https://app.au.intercom.com/oauth.

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug intercom says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. What this connector does and does not do

• intercom.search_conversations — search conversations by state, contact or subject, one page of up to 150 at a time.
• intercom.get_conversation — one conversation and its parts, as plain text.
• intercom.get_contact — one contact.
• intercom.list_tags — the workspace's tags.
• intercom.reply_to_conversation — replies to the customer. Tagged external_send, because the reply reaches a customer; the approval card names the conversation and the reply's text is disclosed on the card.
• intercom.add_internal_note — adds a note only teammates see. Tagged write.
• intercom.tag_conversation — attaches an existing tag. Tagged write.

Replies, notes and tags are authored as the Intercom teammate who authorised the connection.

Every request pins Intercom's API version 2.17 with the Intercom-Version header, so a default somebody changes in the Developer Hub never changes what this connector reads. The grant does not expire and there is no refresh: it lasts until it is revoked in Intercom, and reconnecting means authorising again.

Intercom hosts a workspace in the US, the EU or Australia, fixed when the workspace was created. Set the plugin's Intercom workspace region to eu or au for those workspaces; leave it empty for the US. An EU-hosted workspace has to have been created that way — an existing US workspace cannot be moved.

The rate limit is 10,000 calls a minute per app and 25,000 per workspace, counted in 10-second windows; a member may notice a short pause when a busy workspace reaches it.

This connector's catalogue row ships available: false: it stays disabled until the live smoke runs at turn-on.