Add side_conversations endpoint to OpenAPI spec

[busiq]

Why?

The monolith PR (intercom/intercom branch busiq/add-side-conversation-threads-api) adds a new GET /conversations/{id}/side_conversations public API endpoint. The OpenAPI spec needs to document this endpoint so it appears in the API reference and generated SDKs.

How?

Add the path definition and two new schemas (side_conversation_list, side_conversation_summary) to the Unstable spec, following the existing handling_events sub-resource pattern.

Companion PRs

• Monolith: intercom/intercom — branch busiq/add-side-conversation-threads-api
• Developer Docs: intercom/developer-docs — branch busiq/add-side-conversations-endpoint

Implementation Plan

Plan: Add Side Conversations API Documentation

Context

PR busiq/add-side-conversation-threads-api introduces a new public API endpoint:
GET /conversations/{id}/side_conversations — returns paginated side conversation threads
with their conversation parts. The endpoint is in UnstableVersion, gated by
AddSideConversationsEndpoint version change, and requires read_conversations /
read_extended_conversations OAuth scopes.

The monolith code is complete. Two companion PRs are needed in external repos to fully ship the API.

Step 1: OpenAPI Spec — intercom-openapi

1a. Add path (after /conversations/{id}/handling_events)

Insert new path /conversations/{id}/side_conversations following the exact pattern of
handling_events — same parameter style, same tag (Conversations), same error responses.

Key details from the controller/presenter:

• operationId: listSideConversations
• Parameters: id (path, required), page (query, integer, default 1), per_page (query, integer, default 25, max 50), Intercom-Version (header)
• Response: 200 with side_conversation_list schema
• Errors: 401 (Unauthorized), 404 (Conversation not found)

1b. Add schemas (after handling_event_list)

Two new schemas:

• side_conversation_summary — object with side_conversation_id (string), conversation_parts (array of conversation_part refs), total_count (integer)
• side_conversation_list — object with type (enum side_conversation.list), side_conversations (array of side_conversation_summary), total_count (integer), pages (object with page, per_page, total_pages)

Step 2: Developer Docs — developer-docs

• Copy updated OpenAPI spec into docs/references/@Unstable/rest-api/
• Add changelog entry for the new endpoint

_{Generated with Claude Code}