Fin / Intercom connector — TSANet Connect Developer Hub

Connector class

Why this connector is shaped differently

Every connector TSANet shipped before this one assumes code can run inside the member's own system. Salesforce and Dynamics allow it; Zendesk partly; ServiceNow would, though nothing is built there yet. Intercom does not — and neither will most of the platforms behind it. That single constraint makes TSANet the operator of the integration rather than the author of a specification someone else implements.

Zendesk sits between the two: its apps run client-side in a sandbox and its integration flows are Zendesk-hosted, so some logic has a home in-tenant but arbitrary server code does not.
	In-tenant connector	Gateway adapter
Platforms	Salesforce, Dynamics (ServiceNow would fit here; not built)	Intercom / Fin, Pylon, DevRev, Wolken
Where code runs	Inside the member's own tenant	A service TSANet hosts and runs
Who operates it	The member	TSANet
Credentials live	In the member's tenant	With TSANet, one set per member
Case lifecycle state	The CRM holds it	The gateway must hold it
Connector faults	Isolated to one member	Correlated across members — one hosted service, a single replica in the reference deployment
Platform outage	Affects everyone either way — the Connect API is a shared dependency
Distribution	Installed package or app	Connected app plus a hosted service

The two failure rows are worth reading together. Every member already depends on the Connect API, so a platform outage stops collaboration whichever class they are in — an in-tenant package does not keep working when the platform is down. What a gateway changes is that connector faults become correlated rather than independent, which is a design input rather than a drawback: it is why the gateway is designed to a higher availability target than any single member's install — and, with the reference deployment a single replica today, why that target is met through durability and recovery rather than replication, and why so much of the design below is about exactly that rather than features.

Three differences that force the change

01

There is nowhere in the member's system to put connector code

Intercom offers an API, webhooks, sign-in, and panels rendered from your own servers. There is no equivalent of an installed package running inside the customer's instance, so everything runs on infrastructure TSANet operates.
02

The unit of work is a conversation, not a record

Other connectors assume a case record with a rich status model, custom fields, and a platform-maintained audit trail. Intercom's native object is a conversation thread; tickets were added later and carry only a handful of states. State other connectors get for free has to be kept by the gateway instead.
03

The AI answers first, and a human is the escalation path

Fin is designed to resolve before a person is involved, and Intercom charges per resolution rather than per seat. A collaboration request arriving into that world is expected to be answered, not queued — and the TSANet lifecycle assumes a human picks the case up.

What the lifecycle actually permits

The open design question was whether an incoming partner request could be answered and closed out without ever becoming a ticket — the flow Intercom is built around. Probed against a live environment rather than reasoned from documentation:

partner submits a request 200 status OPEN, response clock starts

we answer with a note 200 allowed without accepting

partner tries to close it 422 "OPEN cases cannot be closed."

we try to close it 422 same refusal — not a permissions issue

Half of it works. Answering requires no change to the case's status at all, so an AI agent can do its entire job inside a conversation, with nothing written back but the answer. But no case can be retired while it is still open, by either party. Every request that ends cleanly must first be accepted.

The refused edge is the constraint the design has to accommodate: acceptance is not optional, so it cannot be treated as the moment work becomes real. Incoming requests land as a conversation and become a ticket only when a person needs to own the work — tying ticket creation to acceptance would create a ticket for every single request, which is precisely what the conversation-first model exists to prevent.

Recommended guardrail: the AI drafts, a person commits. Fin composes the answer and posts it. Accepting, declining, and requesting more information stay with a human. The reasoning is not answer quality — it is that these actions are contractual commitments to another vendor made under a service-level clock, and that partner escalations carry end-customer logs and text pasted in verbatim: untrusted content reaching an AI that then replies under the member's name.

Topology

The system at a glance

One headless Spring Boot process sits between the two platforms. Everything TSANet-facing lives in an embedded gateway-engine shared across adapters — the Connect Gateway, which this connector was the proving ground for and now consumes as a published artifact; everything Intercom-facing goes through a REST gateway. The process border is the trust boundary: signature verification is default-deny, so a route matching no scheme is rejected 401, and a missing secret fails closed. /healthz is the only open route; the TSANet-internal admin plane under /admin/* is a fourth signed edge, under CONNECTOR_ADMIN_API_SECRET.

The runtime as built. Accent edges cross the signed process boundary and are numbered in the legend below; plain edges are in-process calls. The green store is the only state that survives a restart.

1Canvas requests. POST /canvas/initialize and /canvas/submit, signed X-Body-Signature, HMAC-SHA256 over the raw body with the Intercom app client secret.
2Intercom webhooks. POST /webhooks/intercom, signed X-Hub-Signature, HMAC-SHA1 (sha1=<hex>), same client secret. Note the two schemes differ in both algorithm and prefix. Today this edge carries nothing: no handler consumes an Intercom event, so the reference deployment subscribes no topics (verified 2026-08-20 — a full inbound E2E ran green with the list empty). The intake stays signature-gated for the day a feature needs a topic.
3TSANet push. POST /webhooks/tsanet, CloudEvents v2, signed x-hub-signature-256, HMAC-SHA256. Non-routable bodies are refused loudly but still answered 200.
4Connect API calls. REST — the v1 case paths and /v2/collaboration-requests/list reads through the embedded engine; the subscription itself is registered at setup on POST /v2/webhooks (and deleted on the v1 path, the only delete there is), and the inbound push it receives is CloudEvents v2 — with the bearer injected per request by interceptor; OAuth pre-refreshes on a 30s expiry skew. Default deadlines, configurable: 1500ms reads, 4000ms mutations, on virtual threads; the reconciliation list read runs under its own fixed 30s budget. The API mints the subscription secret at creation, so a first-ever deploy is two passes: register with the URL, capture the secret into TSANET_WEBHOOK_SECRET, roll the deployment.
5Intercom API calls. Tickets, admin notes, ticket-state writes. Every mutation is read back and asserted: the API 200s while ignoring unknown fields.

Flow 3 · recovery

Re-driving what push dropped

Between an at-least-once push that can still be lost and a drain that catches internally, anything lost in the middle used to be lost permanently. The reconciliation poller closes that gap: it lists INBOUND cases via listInboundUpdatedSince(cursor − 120s) and drives anything with no link back through the same claim-before-create path.

Cursoring on updatedAt was verified, not assumed: a live-created case came back with updatedAt == createdAt to the nanosecond, and a filter set 60s earlier returned it. A naive reading of the data suggested updatedAt only moved on modification, which would have missed new cases for 24h.
It calls the handler directly, not through the event queue: a recovery batch offered to a bounded queue could evict live webhook events. The claim arbitrates between the poller thread and the drain exactly as between two deliveries.
Success means an anchored link, not a row existing: an unanchored row reads as in-flight and holds the cursor.
The cursor advances only after a fully clean cycle, and only to an updatedAt actually observed. An empty window advances nothing. A wedged cursor degrades to a widening query and loud logs, never lost work.

Terminal cases are prefiltered (still advancing the cursor), so a missed create plus a partner close cannot manufacture a dead pending ticket. The prefilter runs before the claim lookup, so an orphaned claim on a terminal case cannot wedge the cursor.
Orphaned claims are surfaced, not reclaimed: age-based reclaim risks pulling a claim from under a live-but-slow create, recreating the duplicate-ticket class. Releasing one stays a human action.
The cursor is persisted before the cycle is declared healthy, in the same durable store as the links — so a cursor cannot outlive the links it cursors over.
Bounded windows: the list endpoint has no pagination, so the window is the only load control; the first run asks for now − 24h, never epoch. Single instance only.

What survives a restart, and what deliberately does not

Store	Survives restart	Notes
`SubmissionLinkTable`	yes · required	The token ↔ ticket routing substrate; indexed by token, `internalCaseNumber` and conversation id; never evicted. Carries `CaseState`, annotation state, case number and surfaced status.
`PollerStateStore`	yes	Reconciliation cursor. A lost cursor costs one wider re-scan; lost links orphan every open case — which is why only the cursor is allowed an in-memory fallback.
`connect-sdk.db` (SDK cache)	yes	The embedded engine's operational cache: case summaries, note text, response details, webhook receipts. A cache, not the source of truth — the panel and the poller re-fetch by token — which is what makes the optional retention sweep safe: `CONNECTOR_SDK_CACHE_RETENTION` (default off, per deployment) evicts terminal cases and their child rows past the window; OPEN cases never age out. Backed up with the link store (5-minute latest copy plus hourly snapshots on a 48-hour window), so evicted content is gone from every store at most 48h after the sweep.
`FlowStateStore`	no · by design	Canvas flow state. SUBMITTING and UNRESOLVED flows are exempt from eviction and TTL; an expired flow restarts cleanly from the home canvas.
`DedupeStore`	no	In-memory LRU, 10,000 ids. Replay past the bound is re-processed; accepted because downstream handling is idempotent anyway.
`EventQueue`	no	Bounded; `offer()` drops on full. Both annotation offer sites audit the failure with the token so the manual re-drive path holds.
`MemberSessionRegistry`	no	Per-member session, gateway and API client pairing, with a credential fingerprint and rebuild-on-change. The API client is stateful; sharing one across members would bleed credentials.

Deployment answer, probed rather than assumed. SQLite write-ahead logging cannot run on a network-filesystem mount — probed live on Azure Files SMB, where it fails loudly at the very first connection. The reference deployment therefore keeps the database on replica-local storage and pairs it with a backup loop to durable storage (copied every few minutes, restored on boot), and the production profile still refuses to start on a memory store, a relative path or a fake gateway — and a deployment missing SPRING_PROFILES_ACTIVE=prod gets none of those refusals and no signal that it is running on sand. A backup loop is not a database: worst case a restart loses the last few minutes of link writes, which is acceptable for a pilot and not for production — production replaces the file with a managed database, by design a configuration swap rather than a rewrite.

Vocabulary

Connect case status → Intercom ticket state

Connect status	Intercom ticket state	Why
`OPEN`	Submitted	The partner asked; nobody here has answered yet.
`ACCEPTED`	In progress	We took it.
`INFORMATION`	Waiting on customer	Blocked on the partner. Intercom's external label reads "Waiting on you" — cosmetic on Back-office tickets today.
`REJECTED`	Resolved	Terminal. Ticket state alone cannot distinguish declined from finished; the distinction must live on a custom attribute.
`CLOSED`	Resolved	Terminal.
`PENDINGACTION`	never moved	Thinly documented — a bare enum member in the spec; the API page reads it as a case awaiting an action from your side. What this adapter should do with it is an open question.
`UNKNOWN`	never moved	An unrecognised wire value by construction. A stale state is visibly wrong; a guessed one is invisibly wrong.

Read/write asymmetry: a ticket reads ticket_state as a string, but PUT /tickets/{id} requires a numeric ticket_state_id. The ids are per-workspace and only enumerable under Intercom-Version: Unstable, so resolve them once at configuration time, out of band. Never put Unstable in a runtime path.
Verify by id: under the app's default API version the read-back returns a state object with an id; under 2.11 it returns a bare string and the write is silently ignored — so a string-shaped read-back should throw rather than pass.
Closure configuration refuses when unset: a guessed resolved-state id may not 404, it may name a different real state, moving the ticket somewhere wrong without an error.

Platform notes

What an implementer needs to know about Intercom

Measured against a free Intercom development workspace (US region) and the TSANet BETA environment. Development workspaces are free, do not expire, and the Tickets API is available in them — but agents need an Inbox seat before a canvas app renders for them, which is free in a dev workspace and not obvious.

Surface and placement

The panel is server-rendered. Intercom hosts no third-party code, so the server is yours. This is the whole reason a gateway is required.
One placement option for teammates: "add to conversation details" in the Help Desk. There is no ticket-specific placement toggle, and the documentation describes placement in terms of conversations — but it does render on ticket detail panels. Ticket context is detectable by a top-level ticket key, which rides every canvas request from a ticket surface, initialize and submit alike.
Response deadline is roughly 10 seconds. An 8s response renders; a 10s response fails (measured 2026-08-04, decision D2). The connector holds itself to a <2s budget on top of that, which is why the replica stays warm; the 10s figure is Intercom's failure point, the 2s figure is the connector's own. The failure UX is asymmetric and the asymmetry is the dangerous part: a slow initialize shows an error card with a working "Try again", while a slow submit strands the agent on a spinner with no error at all.
A wrong canvas URL fails as a silent infinite spinner with zero app-side trace — nothing ever reaches your endpoint, so there is nothing to log. When a canvas hangs, verify the pasted initialize and submit URLs before debugging the app.

API behaviour traps

Unknown fields return 200 and are silently ignored. PUT /tickets/{id} with admin_assignee_id returns success and does nothing; the working field is assignee_id. This is why read-back-and-assert is a standing rule.
POST /conversations returns a message id, not the conversation id. Reply calls 404 against it. Use the conversation id from a canvas payload or from search.
List-typed attributes: list_items is a comma-separated string. Passing an array returns a 500 — so option labels cannot contain commas.
Datetime attributes are epoch seconds. Round-tripped live.
Custom attributes are keyed by name, both read and write. A workspace-side rename surfaces as a silent read-back failure rather than an error on write.
A ticket carries two ids, and they are not interchangeable. id is the API handle; ticket_id is the number agents see and can search. Send ticket_id to a partner as the case number — a partner quoting the API id sends agents searching for a ticket that does not exist — and use id for API calls.
No native priority field on tickets. Use a custom attribute.
Rate limit: 10,000 requests per minute, per app.

Events

Subscribe no topics today. The connector consumes no Intercom webhook event: no handler claims the Intercom event source, so every delivery of every topic is verified, queued, logged as key names only, and discarded (verified 2026-08-20, including a full inbound E2E with the subscription list empty). An empty list removes an entire data-in-motion surface for free, and it is now the reference deployment's state. The trap to remember for the day a feature needs a topic: topic subscription is separate from permissions — a permissions page showing everything enabled subscribes nothing, and topics must be selected explicitly on the Webhooks page.
Signatures are byte-exact and differ per endpoint. Canvas requests use X-Body-Signature, HMAC-SHA256 over the body, bare lowercase hex. Webhooks use X-Hub-Signature, HMAC-SHA1, with a sha1= prefix. Both are keyed on the same app client secret.
Delivery contract: 5 second timeout, one retry, 429 throttling. Intake should fast-ack and hand to a queue, with a reconciliation poller as the source of truth.
Payloads are full objects, unusually generous: ticket topics carry the complete ticket including attributes and contacts. This removes a whole class of follow-up reads — and is the opposite of TSANet's thin payloads.
ticket.created also fires an initial ticket.state.updated.

Permissions

Verified live against a development workspace (2026-08-20/21) with reduced-grant probe apps, not read off a permissions page. The connector's standing minimum: Read tickets, Write tickets, Read and write users (contact search), Write users and companies (despite the name, the scope that creates and updates contacts — the synthetic partner contact needs it once), and Write conversations. Intercom additionally grants four greyed, un-uncheckable baseline scopes to every app, so reads of segments, companies, tags and admins succeed regardless and are not a misconfiguration.

Permission edits are inert until the access token is regenerated. Saving toggles changes nothing about what the existing token can do; the Authentication page shows a warning banner once they drift. The order that works: save toggles → regenerate → update the connector's environment → restart. Signature verification is unaffected (it keys on the client secret).
Which grant gates what, probed: ticket notes (POST /tickets/{id}/reply) ride Write tickets — 200 under a tickets-only token — and only the conversation-reply endpoint needs Write conversations (401 under the same token on the same underlying object). A genuine per-endpoint split, even though tickets are conversation-backed.
The hardened profile, for workspaces whose security review wants the standing surface minimized, stacks three verified reductions on the minimum: no webhook topics (above); tickets-only mode (CONNECTOR_TICKETS_ONLY=true, default off) refuses new collaborations from plain conversations with a static canvas so Write conversations can be dropped; and Write users and companies is revoked after the synthetic contact is provisioned at onboarding (if it is ever needed again, the failure is loud and the poller recovers after re-grant). Resulting standing set: Read/Write tickets plus Read and write users, plus the baseline scopes. Two consequences to accept deliberately: agents lose canvas visibility into pre-existing conversation-anchored collaborations, and partner-response notes for those same links fail loudly in the audit log once the grant is gone — drop it only when no conversation-anchored links are active.

Object model and tenancy

Cases live on tickets, under a dedicated collaboration ticket type created with category Back-office.
Tickets require exactly one contact, even Back-office ones. There is no natural TSANet counterpart, so inbound cases use a synthetic partner contact.
Tickets are conversation-backed: the ticket id equals its conversation id.
Notes are POST /tickets/{id}/reply with message_type: note, type: admin, and an admin_id. Back-office tickets carry a "Not shared with customer" badge in the UI.
Private app means single workspace, token auth, no app review — the pilot path, requiring nothing from the vendor. Public app means OAuth plus review and App Store distribution, reusable for every Intercom-based member. App review is required for any public app, including unlisted ones.
Regions: US, EU, AU.

Vendor naming. The company renamed itself Fin in May 2026; the helpdesk product is still called Intercom, and the developer platform is documented as the Intercom and Fin Developer Platform. Expect all three names in the official documentation.

Env	Host
Beta	`connect2.tsanet.net`
Prod	`connect2.tsanet.org`

Since the last verification

Recent changes, and what is tracked next

Landed (August 2026)

First full design-level security review against the connector security taxonomy (supply chain, credential lifecycle, authentication boundaries, data flow and retention, audit, untrusted-content rendering), with the authentication boundary live-probed. Findings are filed as security-labelled issues in the repository; several of the items below are its outcomes.
Hardened deployment profile: no webhook topics (verified functionally free), tickets-only mode, verified-minimum grants with a documented provision-then-revoke step — all in the deployment skill's intercom-setup.md.
SDK-cache retention sweep: age-based eviction of terminal-case content on a per-deployment window, default off (see the persistence table). The eviction itself now lives in connect-library (since 0.2.0); the connector keeps only the schedule and the window, and its interim hand-rolled sweep is retired.
Backups gained history: hourly dated snapshots on a 48-hour window beside the 5-minute latest copy, with a delete-first restore procedure that survives a snapshot lacking a WAL file.
Build provenance: the deployable image is built in CI from a repository commit and pushed with a secretless, registry-scoped identity (no admin credential); images are addressed by digest. Dependency updates are automated; workflow actions are SHA-pinned.

Tracked next (not promises)

Registry pull by managed identity and retirement of the registry admin credential — the live-touching half of the provenance work.
Notes in both directions and status sync still wait on estate-wide decisions shared with the Zendesk connector: a note summary convention, severity mapping, and a platform direction field on notes.
Outbound closure policy — see Known gaps.

Evidence standard: everything under "Landed" is merged and was probed; everything under "Tracked next" has an open issue and no merged code.

Honesty section

Deliberately not built, and known gaps

Outbound closure: an agent resolving the ticket does not close the partner's case. This needs a policy decision on which Intercom state transitions propagate — /closure documents only 200/400, so a wrong guess is indistinguishable from any bad request.
Status sync: the poller recovers missing tickets, not missing state.
Notes in both directions, and the information-response reply leg, land with the notes slice; note.created drains unclaimed today.
Multi-case tickets render no panel: byTicketId correctly refuses to pick between several cases, but the agent currently sees nothing at all. A "this ticket has N collaboration cases" panel is the follow-up.

Inbound ambiguity is transient: an ambiguous response action tells the acting agent, but the recorded state has moved, so a later render shows a cleanly answered case. Outbound has UNRESOLVED for this; inbound has no equivalent yet.
Dedupe strategy beyond the CloudEvent id is a later decision; the reconciliation poller remains the source of truth in both directions.
PENDINGACTION is thinly documented in both contracts; what this adapter should do with it is an open question for TSANet.
Attachments are not covered on this page. Whether this adapter implements the contract's forwardAttachments and AttachmentDeliveryHandler has not been verified; see moving files between members.
Orphaned claims hold the poller cursor loudly and indefinitely until a human releases them. Alert on consecutive held cycles, not on consecutive failures.

Build with an assistant

The deployment skill, and how to load it

The connector repository — private during early access, with access granted at onboarding — ships an agent skill — skills/fin-intercom-deploy — that carries this page's operational knowledge in a form an agentic coding assistant can apply while it works on your deployment: the invariants that produce specific defects when violated (one live adapter per member, single replica, a link store that survives restarts), the Intercom workspace setup — the private app's canvas and webhook URLs, the webhook topic list (empty today, and why), the verified-minimum permissions and the hardened profile, the Back-office ticket type with its three exactly-named attributes, the per-workspace ticket-state ids — the TSANet-side provisioning, webhook subscription and go-live flag, and the environment table with a verification checklist — CONNECTOR_SDK_CACHE_RETENTION and CONNECTOR_TICKETS_ONLY, both documented on this page, were added to that table on 2026-09-14 after this page found them missing. It is plain markdown: a SKILL.md that routes, plus three reference files it points into. Every skill TSANet ships, and how to load one into any assistant, is collected on Agentic usage with TSANet Connect.

Loading it

Claude Code — copy the whole folder into your deployment project's skills directory; the references must ride along with the SKILL.md that cites them:

git clone --depth 1 https://github.com/tsanetgit/Fin-Intercom_App.git
cp -R Fin-Intercom_App/skills/fin-intercom-deploy  your-project/.claude/skills/

Other assistants — attach SKILL.md and the references/ files as project instructions; nothing in it is Claude-specific. The skill lives in the connector repository and evolves with it, so refresh your copy when you update the connector.

Typical first steps

Start with the invariants. "Deploy the TSANet connector for our Intercom workspace." The skill's first outputs are the preconditions that hurt most when discovered late: nothing else may run against the same member credentials, and the link store must sit on storage that outlives the container — with the platform trap that SQLite WAL cannot run on a network filesystem.
Let it drive the workspace setup. "Set up our Intercom workspace for TSANet." It knows the traps that do not error: granted permissions subscribe no webhook topics by themselves (and none need subscribing today), ticket attributes are name-keyed identity so a rename surfaces as a failed read-back rather than a write error, and ticket-state ids are enumerable only through a one-off out-of-band call that must never end up in anything that runs continuously.
Paste refusals verbatim. The connector prefers refusing loudly to acting wrongly, and every startup refusal or error-level audit line names its cause. The skill maps each symptom to the unset knob — a paraphrase throws that mapping away.
Finish with the checklist. "Verify the deployment end to end." The boot-log storage path, one outbound submission (submitter email on your registered domain), one inbound test case arriving as a ticket, the unsigned-request 401 check, and the audit lines your monitoring should alert on.

Boundaries worth keeping. Member credentials, Intercom client secrets and access tokens never go into an assistant session — the skill is written against placeholders and never needs a real value. And it is distilled guidance, not the source of truth: it names the repository's own files as the authority (the configuration table defers to application.yml, the reasoning to docs/decisions.md), and where they seem to disagree, the repository is newer.

Fin / Intercom

Why this connector is shaped differently

Three differences that force the change

There is nowhere in the member's system to put connector code

The unit of work is a conversation, not a record

The AI answers first, and a human is the escalation path