From 401f8b404eac4888d22262a2c988702770fbdc00 Mon Sep 17 00:00:00 2001 From: "everyskill-bot[bot]" <261099307+everyskill-bot[bot]@users.noreply.github.com> Date: Wed, 4 Mar 2026 16:55:21 +0000 Subject: [PATCH] Add skill: intercom-api --- skills/intercom-api/SKILL.md | 329 +++++++++++++++++++++++++++++++++++ 1 file changed, 329 insertions(+) create mode 100644 skills/intercom-api/SKILL.md diff --git a/skills/intercom-api/SKILL.md b/skills/intercom-api/SKILL.md new file mode 100644 index 0000000..fc2e570 --- /dev/null +++ b/skills/intercom-api/SKILL.md @@ -0,0 +1,329 @@ +--- +name: intercom-api +description: "Perform write operations on Intercom conversations and Help Center articles via REST API. Use when you need to reply, add notes, assign, close, snooze, or reopen conversations, or create/update Help Center articles. Trigger when: user says 'reply to intercom', 'close conversation', 'add note', 'update help article', 'assign conversation', or any Intercom write operation." +tags: + - intercom + - support + - customer-service + - help-center +version: "1.0.0" +allowed-tools: + - Bash + - Read + - Edit + - Write +--- + +# Intercom API (Write Operations) + +Perform write operations on Intercom conversations and Help Center via REST API using curl. + +## Authentication + +Store your Intercom Personal Access Token as an environment variable. The `Intercom-Version: 2.11` header is **required** on all requests. + +```bash +# Set your token (add to ~/.zshenv, ~/.bashrc, or ~/.zshrc) +export INTERCOM_ACCESS_TOKEN="your-token-here" + +# Test authentication +curl -s https://api.intercom.io/me \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['name'], d['email'])" +``` + +## Conversation Write Operations + +All conversation actions use `$CONVERSATION_ID`. Find this from the Intercom URL or search API. + +### Reply to Conversation (Customer-Visible) + +Sends a reply that the customer can see. + +```bash +CONVERSATION_ID="12345678" +ADMIN_ID="YOUR_ADMIN_ID" + +curl -s -X POST "https://api.intercom.io/conversations/$CONVERSATION_ID/reply" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"message_type\": \"comment\", + \"type\": \"admin\", + \"admin_id\": \"$ADMIN_ID\", + \"body\": \"Your reply text here.\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Reply sent:', d.get('id', d))" +``` + +### Add Internal Note + +Adds a note visible only to admins (not the customer). Notes support HTML. + +```bash +CONVERSATION_ID="12345678" +ADMIN_ID="YOUR_ADMIN_ID" + +curl -s -X POST "https://api.intercom.io/conversations/$CONVERSATION_ID/reply" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"message_type\": \"note\", + \"type\": \"admin\", + \"admin_id\": \"$ADMIN_ID\", + \"body\": \"

Investigation notes here.

Root cause: ...

\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Note added:', d.get('id', d))" +``` + +### Assign Conversation + +```bash +CONVERSATION_ID="12345678" +ADMIN_ID="YOUR_ADMIN_ID" # Admin performing the assignment +ASSIGNEE_ID="TARGET_ADMIN_ID" # Who to assign to + +curl -s -X POST "https://api.intercom.io/conversations/$CONVERSATION_ID/parts" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"message_type\": \"assignment\", + \"type\": \"admin\", + \"admin_id\": \"$ADMIN_ID\", + \"assignee_id\": \"$ASSIGNEE_ID\", + \"body\": \"Assigning to support team for follow-up.\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Assigned:', d.get('conversation_parts', {}).get('conversation_parts', [{}])[0].get('id', d))" +``` + +### Close Conversation + +```bash +CONVERSATION_ID="12345678" +ADMIN_ID="YOUR_ADMIN_ID" + +curl -s -X POST "https://api.intercom.io/conversations/$CONVERSATION_ID/parts" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"message_type\": \"close\", + \"type\": \"admin\", + \"admin_id\": \"$ADMIN_ID\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Closed. State:', d.get('state', d))" +``` + +### Snooze Conversation + +Snooze until a Unix timestamp. + +```bash +CONVERSATION_ID="12345678" +ADMIN_ID="YOUR_ADMIN_ID" +# macOS: $(date -v+1d +%s) Linux: $(date -d '+1 day' +%s) +SNOOZE_UNTIL=$(date -v+1d +%s) + +curl -s -X POST "https://api.intercom.io/conversations/$CONVERSATION_ID/parts" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"message_type\": \"snoozed\", + \"type\": \"admin\", + \"admin_id\": \"$ADMIN_ID\", + \"snoozed_until\": $SNOOZE_UNTIL + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Snoozed until:', d.get('snoozed_until', d))" +``` + +### Open (Reopen) Conversation + +```bash +CONVERSATION_ID="12345678" +ADMIN_ID="YOUR_ADMIN_ID" + +curl -s -X POST "https://api.intercom.io/conversations/$CONVERSATION_ID/parts" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"message_type\": \"open\", + \"type\": \"admin\", + \"admin_id\": \"$ADMIN_ID\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Opened. State:', d.get('state', d))" +``` + +## Tracker Tickets + +Create tracker tickets to group related customer issues. + +```bash +python3 - <<'PYEOF' +import subprocess, json, os + +token = os.environ["INTERCOM_ACCESS_TOKEN"] + +payload = json.dumps({ + "ticket_type_id": "YOUR_TICKET_TYPE_ID", + "ticket_attributes": { + "_default_title_": "Short bug title", + "_default_description_": "Description of the issue and any linked references" + }, + "contacts": [] +}) + +result = subprocess.run([ + "curl", "-s", "-X", "POST", "https://api.intercom.io/tickets", + "-H", f"Authorization: Bearer {token}", + "-H", "Content-Type: application/json", + "-H", "Accept: application/json", + "-H", "Intercom-Version: 2.11", + "-d", payload +], capture_output=True, text=True) + +d = json.loads(result.stdout) +print("Ticket ID:", d.get("ticket_id")) +print("Internal ID:", d.get("id")) +PYEOF +``` + +Use `python3` heredoc pattern (not inline curl) to avoid shell escaping issues with apostrophes in the description. + +**Note:** Linking tracker tickets to conversations is UI-only. The REST API linking endpoints silently fail. Use the Intercom UI to link tickets to conversations. + +## Help Center Management + +### List All Articles + +```bash +curl -s "https://api.intercom.io/articles" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + | python3 -c " +import sys, json +d = json.load(sys.stdin) +for a in d.get('data', []): + print(f\"{a['id']:10} {a.get('state',''):10} {a.get('title','')[:60]}\") +print(f'\nTotal: {len(d.get(\"data\", []))}') +" +``` + +### Get Article Details + +```bash +ARTICLE_ID="12345" + +curl -s "https://api.intercom.io/articles/$ARTICLE_ID" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + | python3 -c " +import sys, json +d = json.load(sys.stdin) +print('Title:', d.get('title')) +print('State:', d.get('state')) +print('URL:', d.get('url')) +print() +print('Body (truncated):') +print(d.get('body', '')[:500]) +" +``` + +### Create Article + +```bash +AUTHOR_ID="YOUR_ADMIN_ID" +PARENT_ID="YOUR_COLLECTION_ID" + +curl -s -X POST "https://api.intercom.io/articles" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"title\": \"Article Title\", + \"description\": \"Short description shown in search results\", + \"body\": \"

Overview

Content here...

\", + \"author_id\": $AUTHOR_ID, + \"state\": \"draft\", + \"parent_id\": $PARENT_ID, + \"parent_type\": \"collection\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Created:', d.get('id'), d.get('title'), d.get('url'))" +``` + +States: `"draft"` (default) or `"published"`. Parent types: `"collection"` or `"section"`. + +### Update Article + +```bash +ARTICLE_ID="12345" + +curl -s -X PUT "https://api.intercom.io/articles/$ARTICLE_ID" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + -d "{ + \"title\": \"Updated Title\", + \"body\": \"

Overview

Updated content...

\", + \"state\": \"published\" + }" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Updated:', d.get('id'), d.get('title'), d.get('state'))" +``` + +### List Collections + +```bash +curl -s "https://api.intercom.io/help_center/collections" \ + -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \ + -H "Accept: application/json" \ + -H "Intercom-Version: 2.11" \ + | python3 -c " +import sys, json +d = json.load(sys.stdin) +for c in d.get('data', []): + print(f\"{c['id']:10} {c.get('name','')}\") +" +``` + +## Help Center Editing Workflow + +1. **List articles** to find the one to edit +2. **Get article details** to read current content +3. **Draft updated content** - body must be valid HTML (`

`, `

`, `