Add descriptions/2.16 spec

[geetikabagga]

Summary

Adds API version 2.16 as descriptions/2.16/api.intercom.io.yaml, built from the 2.15 baseline plus the APIs and fields approved for graduation from Preview. This is add-only: the Preview spec (descriptions/0) and the Fern preview overrides are left untouched, matching prior version cuts (2.13 / 2.14 / 2.15). Graduated surfaces remain in Preview in their newest form.

Graduated into 2.16

New endpoints

• Activity Logs search — POST /admins/activity_logs/search
• Activity Log Event Types — GET /admins/activity_log_event_types
• Macros — /macros, /macros/{id}
• Data Connectors API
• Side Conversations API
• Help Center Redirects API
• Content Snippets API, Content search & bulk actions
• Office Hours (schedules + exceptions)
• Article drafts, version history, scheduled publishing
• WhatsApp message send + status
• Company Notes API, dedicated Conversation Attributes API

Schema & field graduations

Promoted field/schema updates across articles, audiences, content, contacts, conversations, tickets, office hours, and help center (e.g. audience_ids, agent-availability fields, body_markdown, merge_history, external_references, channel, drop_reason, email_domain).

Breaking changes (10)

Contact owner_id → string; conversation unassigned assignee ids → 0; ticket assignee ids → integer; conversation.priority granular levels; article parent_ids replaces parent_id/parent_type; POST /contacts/merge requires duplicates; POST /contacts/search validates sort.order; merged contacts return 410 Gone; POST /tags response status; Reporting Data Export includes no-reply conversations.

Verification

• info.version / intercom_version = 2.16
• 2.16 = 2.15 baseline + graduation set (no invented endpoints; 0 removed paths vs 2.15)
• YAML parses; no dangling $ref
• Preview (descriptions/0) and Fern overrides unchanged vs base (add-only)
• WhatsApp tag declared in the top-level tags array

_{Generated with Claude Code}

[markdennis22]

Reviewed with three independent passes (2.16 graduation correctness / Preview cleanup / spec integrity + wiring). Graduation mechanics are clean — one issue worth fixing before merge, rest is optional.

🔴 Fix before merge: Preview lost GET /custom_object_instances/{custom_object_type_identifier}

The graduated breaking change (getCustomObjectInstancesByExternalId → listCustomObjectInstances) was deleted from Preview instead of reverted to the 2.15 form. Net effect: 2.15 and 2.16 both expose a GET on this path, but Preview now exposes none — Preview is behind stable on this endpoint.

Operation-level check:

Spec	GET operationId
descriptions/2.15	getCustomObjectInstancesByExternalId ✅
descriptions/0 (Preview, this PR)	absent ❌
descriptions/2.16	listCustomObjectInstances ✅ (correct)

Fix: restore the 2.15 getCustomObjectInstancesByExternalId GET into descriptions/0 (source block at descriptions/2.15/api.intercom.io.yaml:8998; in Preview it belongs just before createCustomObjectInstances, ~descriptions/0/api.intercom.io.yaml:10025). 2.16 needs no change.

🟡 Optional / low

• WhatsApp tag is used by GET /messages/whatsapp/status and GET /messages/status in 2.16 but isn't in the top-level tags array. Consistent with the existing pattern (2.15 has Calls undeclared, Preview has Folders), so fern check only warns — add a {name: WhatsApp} entry if we want it clean.
• Three now-orphaned component defs in Preview (company_note, whatsapp_message_status_list, ValidationError response) — dead definitions, no dangling refs. Harmless cleanup.
• PR body undersells the graduation set — WhatsApp status, Audiences, Office Hours, Content Snippets, etc. also graduated (all verified Preview-sourced). Worth a changelog line.

✅ Verified clean

• 2.16 = 2.15 + graduation set: 69 added ops, 0 removed paths, 96 added schemas, 0 duplicate operationIds/keys; every addition traces back to Preview (zero invented endpoints).
• 0 dangling $ref in both 2.16 (of 1333) and post-PR Preview (of 1019).
• Breaking-change promotions consistent across request/response/examples (ticket assignee→int, contact owner→string, conversation.priority enum re-value, article parent fields removed).
• Preview cleanup: all removed paths/schemas landed in 2.16; held-back Preview-only fields retained (ai_topics, formatted_phone); all 4 removed Fern overrides match removed paths.
• info.version/intercom_version correct; 2.16 skeleton matches 2.15; no missing wiring (upload/Postman/version scripts are path-driven, and leaving generators.yml on 2.14 is correct).

Note: fern check (passed, 0 errors) only covers the 2.14 + Preview groups per generators.yml — it does not parse descriptions/2.16; that was validated separately (clean). Also worth knowing all workflows are currently under .github/workflows-disabled/, so nothing here is CI-gated.

~ Automated via Claude

[geetikabagga]

Thanks Mark. Reworked this to be add-only — reverted all edits to descriptions/0 and fern/preview-openapi-overrides.yml back to base, so the PR now touches only descriptions/2.16 (matches the 2.13/2.14/2.15 precedent). Pushed in 5f33de1.

That change resolves the findings:

• 🔴 Preview lost GET /custom_object_instances/{...} — resolved. With Preview untouched it keeps the operation (listCustomObjectInstances, its current newest form). No 2.15-form restore needed, since we no longer prune Preview.
• 🟡 WhatsApp tag missing — added to the 2.16 top-level tags array (alphabetical, with description).
• 🟡 Orphaned Preview component defs — resolved; Preview is unchanged from base.
• 🟡 PR body undersold the graduation set — rewritten with the fuller endpoint/field/breaking-change summary.

Net diff is now a single added file (descriptions/2.16); 2.16 YAML parses with 0 dangling $ref.

~ Automated via Claude

[markdennis22]

Re-reviewed after the latest push (5f33de1). The recut to an add-only cut is exactly right — descriptions/0 (Preview) and fern/preview-openapi-overrides.yml are now byte-identical to main, so the whole PR is a single new file (descriptions/2.16, +35,426). That matches how every prior version was cut (Preview is a full superset spec and has never been pruned on graduation). 👍

✅ Addressed

• Preview kept intact — custom_object_instances GET is back (listCustomObjectInstances); Preview is again a superset of stable (175 paths vs 2.16's 163).
• WhatsApp tag declared (0 undeclared-but-used tags now).
• owner_id → String — consistent at both the schema level (contact / create_contact_request / update_contact_request) and the contact-search fields doc table.

✅ Integrity re-check (2.16)

• 2.15 → 2.16 = +69 ops / −0 removed (clean add-only graduation).
• 0 dangling $ref of 1,333.
• Parses clean; no new duplicate paths/operationIds (the 4 blank-operationId reporting_data ops are pre-existing, identical in 2.15 + Preview).

🟡 One open item

sales_agent.collected_data graduated into 2.16 with its value-type constraint dropped:

# 2.16 (this PR)
collected_data:
  type: object
  additionalProperties:        # empty → unconstrained (any value type)

# Preview source it graduated from
collected_data:
  type: object
  additionalProperties:
    type: string
  example:
    email: user@example.com
    company.name: Acme Inc

sales_agent is live in 2.16 (referenced by conversation / conversation_list_item), so this is a reachable, looser-than-intended stable schema. Suggest restoring additionalProperties: {type: string} (and the example) to match the source.

ℹ️ Optional / not blocking

• Preview's intercom_version enum still tops out at 2.15 + Preview (no 2.16). That's a consequence of keeping Preview byte-identical, and matches the pre-existing per-spec generation lag — 2.16's own enum correctly lists 2.16 (default: 2.16). Fine to leave unless we want all specs' enums kept current.

Everything else verified clean. With the sales_agent tweak this looks good to merge.

~ Automated via Claude

[geetikabagga]

Fixed in 475c048. Restored sales_agent.collected_data to match its Preview source — additionalProperties: {type: string} plus the example (email, company.name). The graduation slice had dropped the value-type constraint; 2.16 now constrains the map to string values as intended. YAML parses, 0 dangling $ref.

~ Automated via Claude

[shrek-intercom]

❌ PR Review Summary: NEEDS HUMAN REVIEW

	Summary
✅	🎯 Problem — The PR title and description clearly communicate the addition of API version 2.16 following established patterns, though the extensive endpoint and field listings make the core message verbose.
✅	📝 Alignment — The PR description accurately and thoroughly reflects the single-file addition of the 2.16 spec, with all claimed new endpoints, version stamps, breaking changes, and the untouched Preview/Fern directories confirmed in the diff.
ℹ️	🧠 Correctness — Disabled for this repository.
❌	🦺 Safety — The PR modifies the descriptions/2.*/ path (adding descriptions/2.16/api.intercom.io.yaml), which represents a frozen public contract requiring mandatory human review, and explicitly introduces 10 breaking changes including type changes, field renames, and new required fields.
✅	🚦 Auto-approval — Within size limit (0/150 LOC).

Per-criterion details

Problem

The PR clearly explains what's being added (API version 2.16) and follows an established pattern ('matching prior version cuts'). However, it's quite verbose with extensive lists of endpoints and fields that could be summarized more concisely - the detailed changelog information buries the core message that this is a routine version graduation following existing conventions.

Alignment

All claims verify. The description accurately describes that this PR adds the 2.16 spec file, built from the 2.15 baseline with graduated APIs from Preview. The specific endpoints mentioned (activity logs, macros, data connectors, side conversations, help center redirects, content snippets, office hours, article drafts/versions/scheduled publishing, WhatsApp, company notes, conversation attributes) are all present in the 2.16 spec. The breaking changes mentioned (owner_id → string, parent_ids replacing parent_id) are reflected in the code. The PR is add-only (only adds one new file), and Preview/Fern are untouched.

The PR description claims this adds descriptions/2.16/api.intercom.io.yaml built from the 2.15 baseline plus graduated APIs from Preview. This is confirmed:

1. Single file addition: The diff shows only descriptions/2.16/api.intercom.io.yaml as a new file — matches the "add-only" claim.
2. Version stamping: info.version: '2.16', intercom_version enum includes '2.16', default is '2.16' — confirmed.
3. Preview and Fern untouched: No changes to descriptions/0/ or fern/ directory — confirmed via git diff.
4. New endpoints claimed: All verified present in 2.16:
   • Activity Logs search (/admins/activity_logs/search) ✓
   • Activity Log Event Types (/admins/activity_log_event_types) ✓
   • Macros (/macros, /macros/{id}) ✓
   • Data Connectors (/data_connectors) ✓
   • Side Conversations (/conversations/{id}/side_conversations) ✓
   • Help Center Redirects ✓
   • Content Snippets (/content_snippets) ✓
   • Office Hours (schedules + exceptions) ✓
   • Article drafts (/articles/{id}/draft), versions (/articles/{article_id}/versions), scheduled publishing ✓
   • WhatsApp message send + status (/messages/whatsapp/status) ✓
   • Company Notes (/companies/{company_id}/notes) ✓
   • Conversation Attributes ✓
5. Breaking changes: owner_id documented as String type in contact search fields table; parent_ids used in articles (replacing parent_id) — confirmed.
6. WhatsApp tag in top-level tags array: Present at line 35427 — confirmed.
7. Baseline growth: 2.15 has 117 paths / 24K lines; 2.16 has 163 paths / 35K lines — consistent with adding graduated APIs.

The description accurately and thoroughly describes what the code changes do.

Safety

This PR adds a new released version spec at descriptions/2.16/api.intercom.io.yaml. Per the repo-specific safety criteria, any change under descriptions/2.*/ requires human review, as these represent the published, frozen public contract. Even though this is a new version (not modifying an existing released version), it still falls squarely under the descriptions/2.*/ path pattern that mandates human review.

Additionally, the PR description explicitly lists 10 breaking changes being graduated into version 2.16 (e.g., owner_id type change from integer to string, assignee ID type changes, parent_ids replacing parent_id/parent_type, new required fields, status code changes). Breaking changes in any version are never auto-approvable per the safety criteria.

This is a significant version cut that establishes a new public API contract and contains intentional breaking changes from the previous version — exactly the kind of change that requires careful human review.

<violated_criteria>
Released version specs — change under descriptions/2.*/ (adds descriptions/2.16/api.intercom.io.yaml), which is the frozen public contract requiring human review.
Breaking changes in any version — PR explicitly documents 10 breaking changes (type changes, field renames, new required fields, status code changes) being introduced in 2.16.
</violated_criteria>

_{Rate this comment 👍 / 👎 to help us improve 🙏 · Disagree with assessment? Establish ground truth here}