Add descriptions/2.16 spec#604
Conversation
Start v2.16 as a copy of the 2.15 spec so it advertises nothing not yet served; graduated endpoints/fields are layered in via follow-up commits. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contact owner_id (string), conversation priority levels, conversation unassigned assignee (0), ticket assignee (integer), article parent_ids, dedicated Conversation Attributes API, tags skip-missing, reporting no-reply conversations, contacts/merge duplicate validation.
- Attachment files on admin ticket reply - Change ticket type endpoint - Link/unlink conversation to ticket endpoints - previous_ticket_state_id on ticket response - ticket_state_id on convert-conversation-to-ticket request Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…spec - Content Snippets API (with agent-availability, audience_ids, markdown fields) - Content Search API - Content bulk actions API - Content tagging endpoints (articles, internal articles, content snippets) - Audiences API - Data Connectors API Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Deleted conversations list, merge conversation, side conversations endpoints - Sales agent, channel, external references, QA evaluations on conversations - brand_id on conversation create; reply_to on conversation source - retain_metrics parameter on conversation delete - Conversation source author reshape; display_as plaintext behavior Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Contact banners API; contact merge history (endpoint, field, include_merge_history param) - email_verified on contact create/update; company notes API and notes field - update_last_request_at on company create Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…into v2.16 OpenAPI spec - Admin role in responses; macros API; message status (WhatsApp) endpoints - Team metrics API; office hours schedules & exceptions APIs - Admin activity log event types & search endpoints - Email message metadata history on conversation source - reporting data export qualified_id Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…spec - Article version history API; article fin statistics - Agent availability, audit/suggestion, help-center audience, scheduled publishing fields - audience_ids on articles and internal articles - default & locales on help center response Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copies the Preview /contacts/search surface verbatim into 2.16: adds the contact_search_request schema (sort.order enum ascending|descending), repoints the requestBody $ref off shared search_request, adds the 400 invalid_sort_order response, and aligns the timestamp prose + adds the formatted_phone searchable-field row.
Copies the Preview help_center redirects surface verbatim: the
/help_center/help_centers/{id}/redirects list+create and
/redirects/{id} retrieve+delete operations, plus the
help_center_redirect(_list), create_help_center_redirect_request and
deleted_help_center_redirect_object schemas. Distinct from the held
AddArticleUrlRedirects (different resource, schemas and Rails classes).
Adds the body_markdown property (verbatim from Preview) to the 7 article schemas that gained it: article_content, article_list_item, internal_article_list_item, and the create/update (internal_)article request schemas, plus the accompanying 'in HTML / mutually exclusive with body_markdown' body-description text. Surgical inserts only — held fields (folder_id, parent_ids) and Preview-only draft fields are deliberately excluded.
A merged contact now returns 410 Gone with a Link header to the canonical
contact on GET /contacts/{id} and GET /contacts/find_by_external_id/{id}.
Copies Preview's 410 'Contact Merged' response block + the 'Merged contacts
return 410 Gone' description on both retrieve operations, replacing the old
404 wording. Surgical — leaves unrelated formatted_phone example drift and
the pre-existing contact_id/id path-param naming untouched.
Replaces the 2.15-inherited GET /custom_object_instances/{type} operation
(getCustomObjectInstancesByExternalId, external_id required, single-object
response, ObjectNotFound) with Preview's listAll version (external_id
optional, custom_object_instances_paginated_list response, TypeNotFound),
and adds the custom_object_instances_paginated_list schema it references
(its pages_link + custom_object_instance refs already exist in 2.16).
… /messages placement Graduate the AddWhatsappMessageSupport 2.16-cut change (send-path via the messages endpoint), copying only the whatsapp surfaces from Preview and excluding the still-held SMS support: - createMessage operation description: add whatsapp, keep sms out - create_message_request.message_type: add `whatsapp` enum value + description (sms omitted) - create_message_request anyOf: add only the `whatsapp` branch (skip `sms`) - requestBody example: add only admin_whatsapp_message_created (skip admin_sms_message_created and invalid_body_supplied_for_sms_message) Also fix a pre-existing structural defect introduced in 728bd98: the `/messages` path key had been left empty and the createMessage operation was mislocated as a POST under `/messages/status`. Relocated the operation back under `/messages`, restoring the Preview/2.15 layout (/messages -> post, /messages/status -> get, /messages/whatsapp/status -> get). Verified: YAML parses, all internal $refs resolve, whatsapp surfaces are byte-identical to Preview, and no SMS surfaces leaked. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Full structural sweep of descriptions/2.16 found the same defect class fixed for POST /messages in d50a0ae, present in 10 more paths (0 in 2.15 and Preview). During earlier graduation commits, each newly-inserted path appended an orphaned operation as a duplicate HTTP-method key under a neighbouring path, leaving the correct path key null. Impact before fix: 10 endpoints dead at their correct URL, ~8 newly-graduated operations silently shadowed (yaml keeps the last duplicate method key) and thus invisible to fern/SDK generation, and several operations reachable only at the wrong URL. No text was lost and no operationId was duplicated, so fern check, $ref resolution and operationId diffing all passed clean. Relocated each orphaned operation block back to its correct path key: - /me (identifyAdmin), /admins (listAdmins), /admins/activity_logs (listActivityLogs), /articles/{article_id} (retrieve/update/delete), /internal_articles/{internal_article_id} (retrieve/update/delete), /away_status_reasons (listAwayStatusReasons), /contacts/{contact_id}/unarchive (UnarchiveContact), /contacts/{contact_id}/block (BlockContact), /data_attributes/{data_attribute_id} (updateDataAttribute), /teams/{team_id} (retrieveTeam). Verified: YAML parses; zero null paths; zero duplicate-method keys; all $refs resolve; no duplicate operationIds; all 10 repaired paths match the 2.15 baseline exactly; previously-shadowed ops (listMacros, tag-detach, audiences retrieve, office-hours list, teams metrics, etc.) now visible. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Take the richer Preview description of conversation_source: add the `recipients` array (with its `type`, `email` and `drop_reason` item fields) byte-identical to Preview. 2.15 and prior 2.16 lacked the field entirely. The email_address_headers drop_reason surface is not present in Preview, so it is not graduated here. Verified: YAML parses, recipients block byte-identical to Preview. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Take the richer Preview description of the Articles draft surface (2.15 had
none). Graduated from Preview with the standard stable-version
normalizations:
- article_content + article_list_item: add has_unpublished_changes and
draft_updated_at, dropping the "Only returned on the `Preview` API version"
sentence (they are returned on 2.16).
- New paths /articles/{id}/draft (GET retrieveArticleDraft, PUT) and
/articles/{id}/draft/publish (POST publishArticleDraft), dropping the
"Set `Intercom-Version: Preview`." sentence from their descriptions.
- Add the publish_article_draft_request schema (byte-identical to Preview).
Verified: YAML parses, all $refs resolve, no null/duplicate-method paths, no
duplicate operationIds, no residual Preview-only markers in the graduated
surfaces.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ects in v2.16 Normalization miss from the Help Center Redirects graduation (46de188): four operation descriptions still instructed callers to set `Intercom-Version: Preview`, which is wrong in a stable version spec. Removed the sentence on the two redirect paths (read + read_write scopes), matching how every other graduated surface drops the Preview-only marker. Verified: YAML parses; zero residual "Intercom-Version: Preview" in 2.16. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![shrek-intercom[bot]](https://avatars.githubusercontent.com/in/3455240?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
PR 540055 cut v2.16, graduating these surfaces out of Unstable/Preview. Strip their Preview-exclusive designation from descriptions/0 so Preview only marks items still Preview after the cut: - Remove "Set `Intercom-Version: Preview`." from graduated article draft/version/tagging, help-center-redirects and content endpoints - Retarget their `intercom_version_preview` header ref to `intercom_version` - Drop "Only returned on the `Preview` API version." from article draft fields - De-Preview the Banners and Content tag descriptions and the bulk-content summary - Restate the reporting-export version note as "from version 2.16 onward" Still-Unstable surfaces keep their Preview markers (ecommerce catalog upload header ref + schema, Fin capabilities version example). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cross-checked descriptions/2.16 against the v2.16 promoted set in PR 540055: - Add 7 tag definitions for graduated APIs that operations referenced but were undefined (Audiences, Banners, Calls, Content, Content Snippets, Conversations Attributes, Data Connectors), normalizing Preview wording. - Reunite 8 orphaned schema bodies with their empty top-level keys (app, away_status_reason_list, contact_blocked, content_sources_list, convert_visitor_request, update_conversation_attribute_request, merge_contacts_request, untag_company_request). Earlier graduation commits left each key null and its body absorbed as duplicate keys under a neighbour, silently corrupting both schemas — YAML-legal and invisible to fern check. - Remove 3 stray duplicate `example` fragments that overwrote real values. Result: 0 null paths, 0 duplicate keys, 0 dangling refs (was 33 dup keys). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per team convention, the Preview spec (descriptions/0) documents only Unstable/Preview changes, not APIs already served by a numbered version. PR 540055 graduated 72 changes into v2.16, so remove them from Preview, leaving the 2.15 base plus the 34 still-Unstable changes. Removed from descriptions/0: - 70 graduated operations (macros, help-center redirects, article draft & version history, content tagging/search/bulk, content snippets, audiences, banners, data connectors, side conversations, office hours, conversation attributes, deleted-conversations list, team metrics, activity-log search, change-ticket-type, merge conversation, link/unlink ticket, whatsapp/message status, custom-object-instances list, merged-contact redirect, etc.) - 82 graduated fields from 24 shared base schemas (email_verified, channel, brand_id, agent-availability/fin-stats article fields, audience_ids, etc.) - 93 graduated-only schemas and 8 graduated tags - Reverted graduated breaking changes to their 2.15 form: contact.owner_id and ticket assignee ids back to their original types, conversation.priority enum, conversation assignee nullability, restored article parent_id/parent_type, repointed contact search / conversation-source-author / tag-create response to their 2.15 schemas, dropped the reporting-export no-reply note. Also removed the now-dead article-versions, /messages/status and merge_conversations_request entries from preview-openapi-overrides.yml. Result: no v2.16-graduated operation/schema/tag/field remains in Preview; all 17 still-Unstable operations retained; `fern check` passes with 0 errors (clears 3 pre-existing errors for the removed Preview-only endpoints). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
geetikabagga
changed the title
geetikabagga
changed the title
There was a problem hiding this comment.
❌ PR Review Summary: NEEDS HUMAN REVIEW
| Summary | |
|---|---|
| ✅ | 🎯 Problem — The PR title and description clearly explain what is being done (adding API version 2.16 graduated from Preview) but are overly verbose with exhaustive change lists that add little value beyond the diff itself. |
| ✅ | 📝 Alignment — Every substantive claim in the PR description — new endpoints, schema promotions, breaking-change graduations, Preview cleanup, and fern override updates — is fully confirmed by the actual code changes. |
| ℹ️ | 🧠 Correctness — Disabled for this repository. |
| ❌ | 🦺 Safety — The PR creates a new released version spec under descriptions/2.16/, modifies the frozen public contract, and explicitly acknowledges breaking changes — all of which require mandatory human review before merging. |
| ✅ | 🚦 Auto-approval — Within size limit (25/150 LOC). |
Per-criterion details
Problem
The PR explains WHAT it does (adds API version 2.16) and provides context that it's built from 2.15 with approved Preview changes, but it's overly verbose with detailed lists of every endpoint and schema change. The 'why' is implied (graduating preview APIs to stable) but not explicitly stated, and the extensive change lists add little value since the diff shows this.
Alignment
The PR description claims to add API version 2.16 rebuilt from 2.15 as the base with approved changes from Preview. The diff confirms:
-
New 2.16 spec file:
descriptions/2.16/api.intercom.io.yamlis created as a new file (35,423 lines) with version string "2.16" — confirmed. -
New API Endpoints: The description claims Activity Logs Search (
/admins/activity_logs/search), Activity Log Event Types (/admins/activity_log_event_types), Macros (/macrosand/macros/{id}), Data Connectors (/data_connectors), and Side Conversations (/conversations/{id}/side_conversations). All are present in the 2.16 spec and none exist in 2.15 — confirmed. -
New Schemas and Fields: The description claims "promoted schema and field updates for articles, audiences, content, conversations, contacts, tickets, and office hours." The commit history directly corroborates this with commits like "Graduate ticket non-breaking changes", "Graduate content & audiences non-breaking changes", "Graduate conversation non-breaking changes", etc. — confirmed.
-
Breaking changes: Commit
17b1fe3"Graduate 9 breaking changes into v2.16 OpenAPI spec" confirms the claim. -
Preview Cleanup: The description claims graduated APIs are removed from
descriptions/0. Verified that macros, side_conversations, data_connectors, activity_logs/search are no longer in the current Preview spec but were in the pre-PR version — confirmed. -
Reverts graduated breaking changes in Preview: The detailed commit message of
f2f8b0bexplicitly mentions reverting contact.owner_id, ticket assignee ids, conversation.priority enum, etc. back to 2.15 form — confirmed. -
Fern preview overrides updates: The diff shows removal of graduated entries (article versions, /messages/status, merge_conversations_request) from
fern/preview-openapi-overrides.yml— confirmed. -
Files changed: The PR lists 3 files (descriptions/0, descriptions/2.16, fern/preview-openapi-overrides.yml) which matches exactly with the actual diff stat.
All substantive claims in the description are verified by the code changes. No phantom claims or significant omissions were found.
Safety
This PR creates a new released version spec (descriptions/2.16/api.intercom.io.yaml) and promotes APIs from Preview into that stable version. According to the safety criteria, any change under descriptions/2.*/ — including creating a new released version — constitutes a change to the published, frozen public contract and always requires human review. This is true "even when the same PR also edits descriptions/0/."
Additionally, the PR is a significant version promotion that introduces breaking changes (as acknowledged in the PR description: "Breaking changes promoted into 2.16 are reflected in the stable spec"), new API endpoints, and new schemas into a released tier. This is exactly the kind of change that needs careful human verification against the monolith implementation.
<violated_criteria>
Released version specs — creates descriptions/2.16/api.intercom.io.yaml, a new released version directory under descriptions/2.*/, which is the frozen public contract and always needs human review.
Breaking changes in any version — PR description explicitly states "Breaking changes promoted into 2.16 are reflected in the stable spec."
</violated_criteria>
Rate this comment 👍 / 👎 to help us improve 🙏 · Disagree with assessment? Establish ground truth here
1 participant
Summary
Adds API version 2.16, rebuilt from 2.15 as the base with approved changes from Preview.
Changes
New API Endpoints
/admins/activity_logs/search(POST)/admins/activity_log_event_types(GET)/macrosand/macros/{id}New Schemas and Fields
Preview Cleanup
descriptions/0Supporting Updates
Verification
descriptions/2.16descriptions/0Generated with Claude Code