--- name: intercom-conversation-themes description: "Every Friday: the topics customers raised in Intercom this week, how many conversations each, and real quotes behind them. Use when the user asks for this, or when it runs on a schedule." --- # Intercom conversation themes Every Friday: the topics customers raised in Intercom this week, how many conversations each, and real quotes behind them. Product managers ask support the same thing every week, "what are customers saying?", and the honest answer takes an afternoon of reading. Intercom tags help only if every teammate tags the same way, which in practice they don't. The agent reads this week's customer-started conversations through the Conversations API, sorts them into a handful of themes by what the customer actually wrote, and keeps two or three short quotes per theme. Support and product read the same list on Friday, and the counts settle the argument about what is loudest. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - An Intercom access token from a private app in the Developer Hub, with permission to read conversations, in `INTERCOM_ACCESS_TOKEN`; or an Intercom connector. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Find this week's conversations** (Intercom): Call `POST /conversations/search` with `{"query": {"operator": "AND", "value": [{"field": "created_at", "operator": ">", "value": }]}, "pagination": {"per_page": 150}}`, following `pages.next.starting_after`. Send the `Intercom-Version: 2.17` header, or set that version as the app's default in the Developer Hub. 2. **Read what customers wrote** (Intercom): Keep conversations whose `source.delivered_as` is `customer_initiated`. Take `source.body` and, from `GET /conversations/{id}`, the customer's first two replies in `conversation_parts`, with the HTML stripped. 3. **Group into themes**: Cluster by what the customer asked for or reported, not by tag: 5 to 8 themes, each with a count, its share of the week and 2 or 3 quotes under 25 words. Whatever fits nowhere goes into Other, with its size. 4. **Compare with last week**: Save theme names and counts to a small JSON file each run. Mark themes that are new or grew by half or more, and note which existing tags (`tags.tags[].name`) each theme maps to. 5. **Write the summary**: Total conversations, themes by count with their quotes, then the new or growing ones. Keep customer names, emails and company names out of every quote. ## Route B: the browser ### What you need - Signed in to Intercom as a teammate with access to the inbox and to Reports (reports need a seat with reporting permission). If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://app.intercom.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Open the inbox for this week**: Intercom URLs carry your workspace ID, so start at the sign-in landing page and pick the workspace. Open **Inbox**, choose the **All** view, and add a filter **Created** set to the range from Monday 00:00 to now, with **Started by** set to **Customer** (under the conversation attribute filters) so outbound messages and bot-only threads stay out. 2. **Read what customers wrote**: Go through the list oldest first. For each conversation read the opening message and the customer's first two replies in the conversation pane, ignoring teammate and Fin replies. Keep a running list of what the customer asked for or reported, in a few words each. 3. **Check the topics Intercom already found**: Open **Reports**, then **Conversation topics**, and set the date filter to this week. Read the **Topics** table, sorted by volume. It covers only topics someone defined, so treat it as a cross-check on your own grouping, not as the answer. 4. **Group and count**: Sort your notes into 5 to 8 themes by what the customer wanted, not by Intercom tag, with a count, the share of the week and 2 or 3 quotes under 25 words each. Put the rest in Other with its size, and note which tags (shown on each conversation) each theme maps to. 5. **Write the summary**: Total conversations customers started this week, themes by count with their quotes, then themes you did not see last week or that grew by half or more. Names, emails and company names stay out of every quote. Note: The inbox list loads conversations as you scroll, and a browser agent reading a few hundred full threads is slow. Above roughly 300 conversations a week, read the opening messages only and open full threads for a sample of each theme. ## The report - **Conversations this week** that customers started. - **Themes** by count, each with its share and two or three quotes. - **New or growing** themes compared with last week. - **Tag drift**: themes that map to no tag, or to several. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "intercom-conversation-themes/", "item_key": "intercom-conversation-themes", "project": "Acme", "source": "Intercom conversation themes skill", "kind": "update", "title": "Billing questions led this week's 412 conversations", "summary": "**412** customer conversations this week. Billing and invoices was the biggest theme (**96**), and **CSV export timeouts** is new, already at 41.", "widget": [ { "type": "Bars", "props": { "items": [ { "label": "Billing and invoices", "value": 96 }, { "label": "Login and SSO", "value": 71 }, { "label": "Integration setup", "value": 58 }, { "label": "Feature requests", "value": 52 }, { "label": "Account changes", "value": 47 }, { "label": "CSV export timeouts", "value": 41 }, { "label": "Other", "value": 47 } ], "unit": "conversations" } }, { "type": "Table", "props": { "columns": [ "Theme", "What customers wrote" ], "rows": [ [ "Billing and invoices", "\"Why was I charged for 12 seats when we only have 9?\"" ], [ "Login and SSO", "\"SSO sends me back to the sign-in page every time.\"" ], [ "Integration setup", "\"The Slack integration connects but never posts anything.\"" ], [ "CSV export timeouts", "\"Exporting last quarter just spins and then fails.\"" ], [ "Feature requests", "\"Any plans for dark mode in the mobile app?\"" ] ] } }, { "type": "Callout", "props": { "text": "New this week: CSV export timeouts, 41 conversations since Tuesday, mostly from accounts with large exports.", "tone": "warn" } } ] } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. ## Run it on a schedule Suggested: Fridays at 14:00 (`0 14 * * 5`). From cron, with the agent signed in on that machine: ```bash 0 14 * * 5 claude -p "Run the intercom-conversation-themes skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/intercom-conversation-themes#schedule Source: https://briefkin.dev/skills/intercom-conversation-themes