Intercom + Fin as code · hands-on verified · CLI 0.13.0 · v2.7

You can build and test Fin as code. You can’t ship it as code.

▲ The ship blocker just fell

Update: you can now build, test, and ship Fin Procedures as code.

Authoring, testing, and now publishing Fin Procedures — one of the most powerful things you can do with Fin — is fully code-first as of CLI 0.10 / 0.11 (fin procedures publish shipped, verified live end-to-end). Still looking forward to more updates to unlock the other areas — and the REST API just got massive updates too (a full Data Connectors API, Fin Agent orchestration, Office Hours & more) that unlock even more.

New this month · Fin Attributes
Fin Attributes are fully code — including switching Fin on.

Fin Attributes are conversation attributes, and fin fin attributes manages them as conversation.*, with is_classification_attribute, is_enabled and classify_on_close on the object. An upload creates them, updates them in place, and switches Fin on. The catch: both switches default to false on create, so an attribute uploaded without them exists, looks normal, and never fills in — and the stock Issue Type and Product Area on our sandbox were shipped switched off.

Also this month: REST can create conversation attributes too (POST /conversations/attributes at Intercom-Version: Unstable), but that object has no classification fields. Attribute types are frozen at creation, descriptions cap at 255 characters (option descriptions, the classifier's instructions, don't), and a workflow can set a conversation attribute — as a rule command inside mid_path_action.

Nathan Sudds

I've been pinging npm daily waiting for these — and here they are. 🙌 Huge thanks to the Fin CLI team for pushing these updates, and a special shout-out to Brian Scanlan for taking the time to meet with me and actually hear the feedback. This is what building in the open looks like.

— Nathan Sudds · Activelabs
📅 Book an intro call — is working together a fit?Free · 30 min · no pitch, just a conversation ⚡ Fin CLI power session — get unstuck$250 · 60 min · the CLI, MCP & APIs with Claude or your favorite AI
works as code partial / needs a UI step blocked — dashboard only not yet audited
Docs & tools → ↗Fin CLI (npm) ↗Hosted MCP ↗REST API ↗Unstable API ↗Claude in Chrome

Three different APIs — which one is which

Half the confusion on this board comes from three separate things all getting called “the API”. They are different surfaces with different contents and different ways of being selected — and a capability is often present on one and unreachable on another. Read the matrix below with these three in mind.

1 · Fin SDK API

api.intercom.io/fin-sdk/… · no version header

Fin’s own objects: procedures, guidance, data-connector config, audiences, monitors, simulations. This is what the fin verbs actually speak. Gated by a per-workspace backend flag, not by API version — when it is off you get 403 Fin SDK is not enabled no matter what else you do.

✓ CLI verbs + fin api /fin-sdk/…

2 · REST API (stable — 2.16)

api.intercom.io · Intercom-Version: 2.16

The rest of Intercom: conversations, contacts, articles, tickets, tags, calls, and — as of the 2.16 graduation — data connectors, office hours and macros. Version is pinned per app in the Developer Hub; the header only matters if you are sending it yourself.

✓ fin api — but only at your workspace’s default version

3 · Unstable / Preview API

api.intercom.io · Intercom-Version: Unstable

The waiting room. Same host, same paths — a preview tier holding things not yet in a numbered version: Reporting Data Export, Fin Agent orchestration, custom object instances, incident.* webhooks. Surfaces graduate out of here into a stable version (macros and office hours both did), so a card marked “Unstable-only” can quietly become stable.

⚠ not natively — the CLI still can’t send the header (#33). Reachable via a loopback proxy and INTERCOM_API_BASE_URL, with no token handling.
And one that is not an API at all: fin api. It is a CLI passthrough — gh api for Intercom — not “the Fin API”. It signs the request with your stored token and sends it at whatever version your workspace defaults to. On 0.13.0 it still has no --version or header flag (fin api --help lists none), which is the whole of #33: anything living above your default version, or on Unstable, is curl-reachable and not natively CLI-reachable. Workaround: the CLI honours INTERCOM_API_BASE_URL, so pointing it at a small loopback proxy that injects Intercom-Version gives fin api any version — while the CLI keeps doing its own keychain auth. The tell is the error text — Requested resource is not available in current API version means the route exists and you are pointed at the wrong version, not that the capability is missing.

Fin as code — top wins & top blockers

The headline before the detail: what the CLI already nails, and the three things still standing between it and a deploy pipeline you would trust unattended.

▲ Top wins

  • ✓Procedures ship as code. publish / pause / versions (0.10.0) closed the loop — author → test → set live, verified end-to-end, without opening the dashboard.
  • ✓Help Center content ships AND publishes as code — fin articles create · update · delete with -F body=@file.md and -f state=published. A docs repo can drive the Help Center in one line.
  • ✓simulations generate / run / result is real CI-style regression testing from the terminal — it caught the 0.9.0 regression for us. fin setup still provisions a whole workspace in one command.
  • ✓Guidance is full CRUD via fin api, and call transcripts + audio are pullable via /calls — including human-answered calls, back to Jan 2025.

▼ Top blockers

  • ✕Authoring a runnable Workflow is UI-only. The single biggest gap left — upload id:new 200s but yields a hollow shell, and the SDK paths layer is not the builder graph. Three of the ten jobs below are blocked on this one thing.
  • ✕The CLI can’t select an API version (#33). Cited by five cards on this board as the actual block — stable 2.16 (macros, office hours, connector CRUD) and the Unstable-only surfaces (Reports export, custom objects) are curl-reachable but not CLI-reachable. One flag unlocks a lot.
  • ✕The failures that remain are silent, not missing. get --version <id> with a space is swallowed by the CLI’s global version flag — no request is sent, it prints 0.13.0 and exits 0 (#82). Procedures and workflows alike; --version=<id> works. Nothing reports what a token may do, so a 403 is indistinguishable from a 404 (#78). A missing verb blocks you; a wrong answer misleads you.

The delivery pipeline

Six stages of shipping a Fin change. The publish gate just fell for Procedures (0.10.0) — author → test → ship, all as code; workflow authoring is the stage that’s still artisanal. Each stage’s bar shows how much is green. Click a stage for the detail.

Capability matrix — activity × surface

Where each job actually runs. The old “REST / Unstable” column has been split in two, because those are different surfaces and welding them together hid exactly the case this board keeps hitting — a capability that is live on one and unreachable on the other. Three things to read off it: the Dashboard column is still the only one green all the way down, MCP is green on exactly one row (Help Center content), and the Fin SDK API column and the REST 2.16 column barely overlap — Fin’s own objects and the rest of Intercom really are two different estates.

✓ works as code ~ partial / needs a UI step ✗ blocked — dashboard only – not applicable on that surface Columns 2–4 are the three APIs above, kept apart on purpose. On a phone each activity becomes a card, and surfaces marked “not applicable” are left out.

The wider Intercom surface — audit & rollout

Beyond Fin: the rest of the estate we review, configure and roll out. Two areas already prove the “ship-as-code” pattern works — the platform just hasn’t extended it everywhere. “Not yet audited” marks the live rollout backlog, not a known gap.

▲ Surface wins

  • ✓Articles ship as code — REST Articles API + MCP create/update_article; fin setup even seeds them.
  • ✓Workflows: read + toggle as code — list / get (a 55-workflow inventory in one call) + enable / disable. Authoring the graph is UI-only, though (see blockers).
  • ✓Tickets ship as code — POST /tickets creates (validation-confirmed); types & states are readable.
  • ✓Outbound messages ship as code — POST /messages (email / in-app, admin→user).

▼ Surface blockers & unknowns

  • ✕Series & News campaigns have no public API, and SLA policies are config-only in the UI (SLA status reads per conversation via sla_applied) — 404 on default + Unstable.
  • ✕Authoring a runnable Workflow is UI-only — upload id:new 200s but yields a hollow shell (blank visual builder, runs empty); the SDK paths layer ≠ the builder graph, and upload silently mangles channels→web.
  • ✕Help Center config is read-only as code — website toggle & custom domain are UI-only.

Can I build it? — the jobs we actually take on

The rest of this board is organised by surface. This one is organised by outcome — real engagements we run, what ships as code today, and the single thing each blocked one is waiting on.

Closing the UI-only gaps today — Claude in Chrome. The dashboard-only steps (Set-live, the workflow visual builder, business hours) can be driven right now with Claude in Chrome agent-driving the UI — so the loop can be closed end-to-end today. But it's a brittle stopgap: no stable selectors, a human often has to step in, and it breaks when the UI shifts. A real code verb (an apply/publish, a workflow-graph API) replaces the browser hack with something deterministic and CI-safe.

The API just leveled up — 2.16 & Preview

The REST API moved as hard as the CLI — a big graduation into stable 2.16, plus new Preview surfaces. Several of these close gaps this board has flagged for months. Caveat: the CLI can’t select an API version yet (#33), so most are curl-reachable today, not CLI-reachable — bump your workspace’s Developer-Hub default to 2.16 to reach them.

What’s new — does it ship as code?

The newest intercom.com/changes features — 10 from Aug 11–Sep 2 2026 (swept 2026-09-02) on top of the Jul 21–Aug 3 batch — each checked against CLI / REST / Unstable / MCP. ★ marks the ones that matter most for code-first. Sorted by impact · ★ = matters most for code-first · verdicts are “we couldn’t find a code path,” not “impossible” — pointers to anything we missed are welcome. Click a row for detail.

Changelog
⚙️ Coding against the new APIs? Check your Developer Hub scopes + version first. The 2.16 graduation added new resources (Data Connectors, Office Hours & more). If your access token predates them, those scopes may be off by default — open your Developer Hub → your app → Authentication and enable the scopes for anything you want to reach (data connectors, office hours, tickets, etc.). And set your app’s default API version to 2.16 there — the CLI rides that default and can’t override it per request yet (#33), so bumping it is how you reach the new surface from fin api.
Last updated 2026-09-27 · v2.7 · verified hands-on on @intercom/cli 0.13.0 · Prepared by Nathan Sudds (Activelabs) · client-anonymized