# Intercom

Connect Intercom so Suger AI can work with your conversations, contacts, and help centre articles.

---

## Overview

[Intercom](https://www.intercom.com) is a customer messaging and support platform covering live chat, a shared inbox, and a help centre. Connecting it lets the Suger AI agent read and act on your support workload — conversations, contacts, companies, and articles — from a Suger workflow or chat.

### Org-Level vs User-Level

> **Org-Level**: Supported. One Intercom administrator authorizes Suger once, and the connection serves the whole organization.
>
> **User-Level**: Not applicable, and not merely absent. An Intercom access token carries the permissions declared by the *app*, applied across the whole workspace — not the role of the admin who authorized it. A per-user connection would return exactly the same data as the org connection, so Suger does not offer one.

### How the connection works

One Intercom administrator authorizes Suger through Intercom's own consent screen. Suger holds and refreshes the resulting token, and every tool then runs across the whole workspace under the scopes declared on the app — not under that admin's role.

```d2
shape: sequence_diagram
admin: "Your Intercom admin"
suger: "Suger"
intercom: "Intercom"
agent: "Suger AI agent"
admin -> suger: "Click Connect on Intercom"
suger -> intercom: "Hand off to Intercom's authorize page"
admin -> intercom: "Sign in and click Authorize"
intercom -> suger: "Access token, carrying THIS admin's grant" { style.stroke-dash: 4 }
agent -> suger: "Run an Intercom tool"
suger -> intercom: "Workspace-wide call under the app's declared scopes"
intercom -> agent: "Conversations, contacts, companies, articles" { style.stroke-dash: 4 }
offboarded: "if that admin is deactivated in Intercom" {
  intercom -> suger: "The org-wide connection can stop working — someone must reconnect" { style.stroke-dash: 4 }
}
```

:::info
Do not paste an Intercom **Access Token** from your own workspace's developer settings. Those tokens are for private apps on the workspace that owns them; using one to reach a different workspace is against Intercom's terms of service. Always connect through the OAuth flow below.
:::

## Create Integration (Org-Level)

### Prerequisites

- An Intercom workspace, and an account with permission to install apps on it.
- Currently supported for **US-region** workspaces. If your workspace is hosted in the EU or Australia, contact Suger support before connecting.
- The Suger **Admin** role — connecting, disconnecting, and running an integration's actions are all admin-only in Suger.

### Authenticate by OAuth

1. In the Suger console, open [Settings → Integrations](https://console.suger.io/settings?tab=integrations) and click **Connect** on **Intercom**.
2. Suger redirects you to Intercom. Sign in if prompted.
3. Review the access Suger requests and click **Authorize**.
4. Intercom returns you to the Suger console and the integration shows as connected.

Suger stores and refreshes the resulting token; you never handle it directly.

<!-- screenshot needed: the Suger integrations list with Intercom mid-connect, and Intercom's authorize screen — BLOCKED: completing it starts a live OAuth grant against a real Intercom workspace, so capture it during a genuine connection -->

:::warning
The token is tied to the Intercom administrator who authorized it. If that person's Intercom account is deactivated, the connection stops working and someone else has to reconnect. For a long-lived integration, authorize with a dedicated Intercom admin account rather than an individual's.
:::

## Suger AI Tools

When Intercom is connected, the Suger AI agent can work your support queue through Suger's built-in tools (42 actions).

> **Org-level**: All tools run under the app's declared scopes across the whole workspace, so the agent can read any conversation regardless of who it is assigned to.

| Capability | What the agent can do |
|------------|-----------------------|
| **Conversations** | Create, read, search, and list conversations; reply, send a message, close, snooze, or reopen one (e.g. `reply-to-conversation`, `snooze-conversation`, `search-conversations`) |
| **Contacts** | Full create/read/update/delete on contacts, plus search and merge (e.g. `create-contact`, `merge-contacts`, `search-contacts`) |
| **Companies** | Create, read, update, delete, and list companies, and attach or detach contacts (e.g. `attach-contact-to-company`, `list-company-contacts`) |
| **Help centre** | Create, read, update, delete, and list articles, and list collections (e.g. `create-article`, `list-help-center-collections`) |
| **Tags** | Create and list tags, and apply or remove them on contacts, companies, and conversations (e.g. `tag-conversation`, `untag-contacts`) |
| **Notes** | Add and list notes on a contact (e.g. `create-note`, `list-notes`) |
| **Admins** | Read and list workspace administrators (e.g. `get-admin`, `list-admins`) |

:::tip
Open the integration from **Settings → Integrations** to see the exact tool list for your connection on its **Actions** tab, and to try a call on the **Playground** tab. The Playground pre-fills only the inputs an action *requires* — add optional ones yourself when you need them.
:::

## Edit Integration

Editing is not supported. To reconnect under a different account or workspace, delete the integration and authorize again.

## Delete Integration

Click the 🗑️ button next to **Intercom** in the **Integrations** list. Suger's authorization is revoked and the token destroyed. To fully remove Suger from the Intercom side, also uninstall it from the workspace's app list in Intercom.