Start here

Connect Intercom

Connecting Intercom lets Winston look up your conversations, contacts and companies and report on them. You create a small internal app in Intercom's Developer Hub, then paste its access token into Winston. This page shows each screen.

Before you start

You need to be an Owner or Admin in Winston.
You need to be able to create apps in your Intercom workspace, which normally means being an Intercom admin.
Decide what Winston should be able to do. Reading conversations and contacts needs far less access than replying to customers.

The connection belongs to the Winston workspace, not only to you. Anyone in the workspace who asks Winston can have it read your Intercom conversations and customer details. Winston still asks before it changes or sends anything; see Review and approve.

1. Create an app in Intercom's Developer Hub

In Intercom, open the Developer Hub (Settings → Integrations → Developer Hub, or go to app.intercom.com/a/apps/_/developer-hub). Choose New app, name it Winston, check the workspace is yours and choose Create app.

Intercom Developer Hub's New app dialog with the App name Winston, the workspace Riverbend, and a Create app button — Developer Hub → New app. Name it Winston and create it in your workspace.

2. Limit its permissions and copy the token

In the new app, open Authentication. The Access token for your workspace is at the top, with an eye to show it and a button to copy it. Below it is the list of Permissions.

The Winston app's Authentication page in Intercom's Developer Hub, with the masked access token and its copy button outlined, and the Edit button outlined — Authentication. The access token and its copy button; Edit changes the app's permissions.

Intercom gives a new app almost every permission, including writing, deleting and replying to customers. Choose Edit, keep only what Winston needs and choose Save. For reporting these six are enough, and Winston has been checked with exactly these: Read conversations, Read and list users and companies, Read one user and one company, Read admins, Read tags and Read tickets. Add write permissions only if Winston should update contacts or reply to customers.

Changing permissions does not change a token that already exists. Intercom then warns that the token "has outdated permissions" and still grants the old access. Regenerate it before you copy it, as below.

To regenerate, open Test and publish → Your workspaces in the app's menu, choose Regenerate token next to your workspace and confirm with Regenerate. The old token stops working at once. Then go back to Authentication and copy the new token.

The app's Your workspaces page with Regenerate token outlined next to the workspace, and Intercom's Regenerate your token? confirmation with a red Regenerate button — Test and publish → Your workspaces → Regenerate token. Confirm, then copy the new token from Authentication.

3. Paste it into Winston

In Winston, open Settings → Connections, find the Intercom card (under Support, or type "Intercom" into the search box) and choose Connect.

The Connections screen in Winston searched for Intercom, with the Intercom card's Connect button outlined — Settings → Connections. Find Intercom and choose Connect.

Paste the token into Access Token and choose Connect. Winston shows it only as dots.

Winston's Intercom dialog, badged API Key, with the Access Token field filled and shown as dots, and Cancel and Connect buttons — Paste the token into Access Token and choose Connect.

4. Check it is connected

Winston checks the token with Intercom and confirms with Intercom is connected. Choose Done.

Winston's dialog headed Intercom is connected, saying Winston can now use your Intercom account, with a Done button — Winston confirms the connection. Choose Done.

The Intercom card on the Connections screen with a green Connected badge, a pencil icon and a plug icon — The Intercom card after connecting. The pencil replaces the token; the plug disconnects.

Then ask Winston a small read-only question in Chat, for example "Which Intercom workspace are you connected to, and how many open conversations can you see?" Winston names the workspace and counts the conversations.

Replace the token

If the token is regenerated or the app is deleted, Winston's connection stops working, even though the card still shows Connected; Winston then reports that Intercom refused the token. This includes regenerating after a permission change. Choose the pencil on the Intercom card, paste the new token into Access Token and choose Save Changes.

Winston's Update Intercom dialog with Access Token showing (unchanged), and Cancel and Save Changes buttons — The pencil opens Update Intercom. Paste a new token, or leave it blank to keep the current one.

Disconnect

To stop Winston using Intercom, choose the plug icon on the Intercom card and confirm Disconnect. This applies to the whole workspace.

Disconnecting removes the token from Winston but the app still exists in Intercom. To make sure the token can no longer be used, delete the Winston app in the Developer Hub as well.

If something does not work

What you see	What to do
Winston says the token was refused (401, "Access Token Invalid")	The token was regenerated, the app was deleted, or part of the token was missed when copying. Copy the current token from Authentication and paste it in with the pencil.
Winston says it isn't allowed to read something (403 or token_unauthorized)	That permission is switched off for the app. Choose Edit on its Authentication page, add the read permission, save, regenerate the token and paste the new one in with the pencil.
Intercom says the token "has outdated permissions"	The permissions were changed after the token was made. Regenerate it under Test and publish → Your workspaces, then paste the new token into Winston.
There is no New app button in the Developer Hub	Your Intercom role can't create apps. Ask an Intercom admin to create the app, or to give you the permission.
Winston connects to the wrong workspace	The app was created in another workspace. Check the workspace under Access token, and create the app in the right one.

For other connections, see Connect your tools. Anything else, see Troubleshooting or contact Support from the dashboard.