Intercom Connector

SKILL.md

---
name: intercom-connector
description: "Access Intercom customer messaging with managed OAuth. Search and manage contacts, conversations, and companies. Use when the user wants to search Intercom contacts, read conversations, create messages, manage customer data, or query Intercom."
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: INTERCOM_ACCESS_TOKEN
        type: oauth2
        integration_id: intercom
        description: Intercom OAuth access
    primaryEnv: INTERCOM_ACCESS_TOKEN
---

# Intercom Connector

Access Intercom customer messaging through the Intercom REST API v2 using managed OAuth.

## First-Time Setup

If Intercom is not connected yet, run:

`manage_auth(action="connect", integration_id="intercom", auth_env="INTERCOM_ACCESS_TOKEN")`

## Auth & Security

- Authentication is managed by Polly + Nango from `metadata.polly.auth`
- Never ask users to paste tokens in chat
- Never print or log token values
- If auth fails, reconnect with:
  `manage_auth(action="connect", integration_id="intercom", auth_env="INTERCOM_ACCESS_TOKEN")`

## Base URL

`https://api.intercom.io`

All requests include:

`Authorization: Bearer $INTERCOM_ACCESS_TOKEN`

## Quick Usage

List contacts:

```bash
curl -sS \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://api.intercom.io/contacts"
```

Search contacts:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":{"field":"email","operator":"=","value":"user@example.com"}}' \
  "https://api.intercom.io/contacts/search"
```

List conversations:

```bash
curl -sS \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://api.intercom.io/conversations"
```

Get a conversation:

```bash
curl -sS \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://api.intercom.io/conversations/<conversationId>"
```

Reply to a conversation:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message_type":"comment","type":"admin","admin_id":"<adminId>","body":"Thanks for reaching out!"}' \
  "https://api.intercom.io/conversations/<conversationId>/reply"
```

List companies:

```bash
curl -sS \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://api.intercom.io/companies"
```

## Rules

- Intercom API uses cursor-based pagination — pass `starting_after` from prior responses
- Contact search uses a structured query object with `field`, `operator`, and `value`
- Include `Accept: application/json` on GET requests for consistent response format
- On API errors, surface status + response body clearly
- On 401/403, reconnect with `manage_auth(action="connect", integration_id="intercom", auth_env="INTERCOM_ACCESS_TOKEN")`
- Never log, echo, or expose credential values in any output