Fin / Intercom

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 means the integration has to run as a service somewhere outside the platform, and someone has to operate it: TSANet, or the member in its own environment. Which one is the member's choice; hosting options compares the two.

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. A member that hosts its own deployment shares a connector fault with no one, and takes on the operating work in exchange.

Three Differences That Force the Change

1. 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 outside the platform: TSANet's, or the member's own.

2. 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.

3. 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:

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.

Hosting

Two Ways to Run It: TSANet-Hosted or Self-Hosted

The adapter is one container image with one configuration surface, and it runs the same way wherever it is deployed. A member can have TSANet host and operate it, or run it in the member's own cloud account. TSANet supports both, and the choice is the member's. The deciding questions are usually about policy rather than engineering: where case content and credentials may live, who is on call for the service, and who holds encryption keys once end-to-end encryption applies.

What a Self-Hosted Deployment Needs

These come from how the engine and the adapter work, so they apply on any cloud and any container service.

• Exactly one instance, always running. Minimum and maximum both one. The stores and the reconciliation cursor assume a single writer, and a cold start breaks the canvas latency budget.
• One live adapter per member. Nothing else may poll or receive webhooks as the same member credential. A second deployment, including a TSANet-hosted one you are moving away from, double-creates tickets for inbound cases.
• The database on local disk, backed up to durable storage. SQLite in write-ahead-log mode fails on a network filesystem, so keep the files on storage local to the running instance, copy them to durable storage on a loop, and restore the latest copy before the app starts. Treat any network filesystem as a backup target only.
• The production profile left on. The image sets it; it arms the guards that refuse fake gateways, an in-memory store and relative store paths.
• Public HTTPS ingress to the container's port 8792, reachable by Intercom's canvas calls and TSANet's webhook deliveries; outbound access to the Connect API, Microsoft Entra's token endpoint and the Intercom API.
• Modest sizing. The reference deployment runs the app at 0.5 vCPU and 1 GiB, with a backup sidecar at 0.25 vCPU and 0.5 GiB.
• Secrets from your platform's secret store, injected as environment variables. A credential change is configuration plus a restart.

Where It Has Actually Run

Getting the Image, and Upgrading

No image is published for members to pull today. You build it from the adapter's release tag with the repository's Dockerfile, which needs JDK 21, Maven and Docker. The build resolves the engine and connect-library from TSANet's GitHub package registry, which requires a GitHub token even for reads; the engine package is private, so registry access is granted at onboarding along with the step-by-step self-hosting guide. A ready-to-pull published image is a known gap.

Every upgrade repeats the same short loop: read the release notes (they carry an "Upgrading a deployment" section), compare the deploy spec between your tag and the new one, build and push the image, confirm your backups are current, deploy in a quiet window, then verify the running image is the one you built. Rolling back is the same loop with the previous tag.

Moving From TSANet-Hosted to Self-Hosted

Agree a cutover window with TSANet first. TSANet stops its deployment and hands over the final copies of both stores, taken after the stop rather than from the last periodic backup; you place them where your restore step reads them and only then start yours. Never run the two side by side: the reconciliation poller alone, with no webhook at all, is enough to double-create tickets.

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 — gateway-engine 3.0.0 with connect-library 3.0.0 since 2026-10-20, the two pins moved together by the build; 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.

• 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 1 · outbound

An Agent Files a Case with a Partner

The canvas flow keeps all real state server-side (stored_data carries an opaque {flow_id} only), makes at most one gateway call per canvas response, and never retries in-handler: the canvas latency budget is hard — an 8s response renders, a 10s one fails, and a slow submit strands the agent on a spinner with no error at all. The flow id doubles as the submission's internalCaseNumber, one per flow by construction.

Flow 1a · submit outcomes

What a Submit Can Become, and Why Ambiguity Is Parked

Case submission is not idempotent and the Connect API offers no idempotency key: createCollaborationRequest documents 200/400/401/403 and no conflict status, so a second POST with the same internalCaseNumber simply creates a second case. The gateway contract therefore splits failures into exactly two kinds, and treats everything ambiguous as ambiguous.

Flow 2 · inbound

A Partner Opens a Case with Us

Push is thin and delivered at-least-once, so intake fast-acks and the fetch is the truth: the event contributes only the token. Ticket creation is claim-before-create, arbitrated by the token's UNIQUE constraint in the link table, because check-then-create is a TOCTOU race that has produced duplicate-ticket defects in an earlier connector (note.created overtaking collaboration-request.created).

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.

What Survives a Restart, and What Deliberately Does Not

Vocabulary

Connect Case Status → Intercom Ticket State

• 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.

Environments

Hosts, Events, and Versions

Since the last verification

Recent Changes, and What Is Tracked Next

Honesty section

Deliberately Not Built, and Known Gaps

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.