Add Fin Guidance and Escalation Guidance to the Intercom REST API

The problem

We manage Fin with a large, frequently updated ruleset: Context & clarification Guidance plus Escalation Guidance (separate objects in Train → Guidance and Train → Escalation).

Today this content is UI-only. There is no public REST API to list, read, create, update, enable/disable, or delete Guidance entries — unlike Help Center articles, which we already manage programmatically via the Articles API.

This creates real operational pain:

1. No single source of truth — teams maintain a parallel wiki/repo and manually copy-paste into Intercom after every change.
2. No programmatic audit — conversation audit events expose fin_guidance_applied with guidance id and title, but we cannot fetch that object via API to verify live text, diff against git, or detect drift.
3. “Ghost” guidance risk — we have seen guidance applied in production (visible in conversation audit) that does not appear in the editable Train list, making it impossible to fix or retire bad rules without Intercom support.
4. High iteration cost — when routing logic changes (e.g. buy/ramp vs gift card vs swap), updating 15–20 guidance bodies by hand is slow and error-prone (character limits, audience, channels, paused vs live).
5. Multi-workspace sync — other customers already ask for export; we need import + update, not just export.

We already automate Fin training for Help Center and Data Connectors; Guidance is the missing piece.

Proposed solution

Add REST API resources for Fin Guidance and Escalation Guidance, modeled after Articles:

Suggested endpoints (names illustrative):

• GET /fin/guidance — list all guidance entries (paginated)

• GET /fin/guidance/{id} — retrieve one entry by id (same id as fin_guidance_applied)

• POST /fin/guidance — create

• PUT /fin/guidance/{id} — update body/metadata

• DELETE /fin/guidance/{id} — delete or archive

• GET /fin/escalation_guidance (+ CRUD) — separate resource for Train → Escalation tab

Fields to expose (minimum):

• id, title, body (plain text / markdown)
• type or category (e.g. context vs escalation)
• audience, channels
• state (enabled | paused | draft)
• created_at, updated_at
• Optional: usage stats (used, resolved, escalated) for observability

Nice-to-haves:

• Deep link from Inbox audit → specific guidance id in API response
• Webhook / event when guidance is created, updated, or deleted
• MCP server support (same pattern as articles)
• Preview vs production workspace targeting (if applicable)

Why this matters

• Faster, safer Fin iteration — git-reviewed changes deployed via CI, not manual paste.
• Drift detection — compare live Intercom state to repo; catch ghost or stale rules.
• Incident response — pause or patch one guidance entry in seconds when misrouting is detected (e.g. Phaze gift-card rule matching crypto buy conversations).
• Consistency with existing APIs — we already manage articles and snippets are requested separately; Guidance is the core Fin routing layer and should be first-class in the API too.

Related requests (complementary, not duplicate)

• Ability to Export Guidance — export-only; we need full CRUD + escalation
• Add Snippets to the Intercom API
• Direct API Mapping for Fin Data Connectors — our team’s related Fin automation request

Happy to share our workflow (repo mirror, deploy checklist, conversation-driven QA) if useful for prioritization.