Skip to content

fix: Mark conversation_id as required in message schema#423

Merged
markdennis22 merged 3 commits intomainfrom
fix/message-conversation-id-required
Mar 26, 2026
Merged

fix: Mark conversation_id as required in message schema#423
markdennis22 merged 3 commits intomainfrom
fix/message-conversation-id-required

Conversation

@markdennis22
Copy link
Contributor

@markdennis22 markdennis22 commented Mar 25, 2026 •
edited
Loading

Why?

The conversation_id field in the message response schema is not marked as required, making it appear optional in the rendered API docs. A customer reported this was confusing — they thought there were cases where the Create Conversation API wouldn't return a conversation ID.

How?

Added conversation_id to the required array in the message schema across all API versions (v2.7–v2.10, v2.12–v2.15, and Unstable). Version 2.11 already had it and was left unchanged.

What was confusing and how this fixes it

Before After
conversation_id rendered without a "required" badge in the response docs conversation_id now shows the red "required" badge, matching type, id, created_at, body, and message_type
Customers thought the API might sometimes omit the conversation ID Docs now clearly communicate that conversation_id is always returned

Companion PR in developer-docs: intercom/developer-docs#798

Generated with Claude Code

@markdennis22 @claude
fix: Mark conversation_id as required in message schema
8273057 
The conversation_id field was missing from the required array in the
message schema, making it appear optional in rendered API docs. This
confused customers into thinking the Create Conversation endpoint might
not always return a conversation ID. Added conversation_id to the
required array across all versions (2.11 already had it).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@levindixon
Copy link
Contributor

levindixon commented Mar 25, 2026

This adds conversation_id to the required array on the shared message schema (components/schemas/message), but that schema is referenced by two endpoints with different behavior:

Endpoint conversation_id in response?
createConversation (POST /conversations) Always present
createMessage (POST /messages) — admin message Absent — stripped by messages_controller.rb:171

The spec itself already reflects this: the createMessage "admin message created" example does not include conversation_id. Marking it required in the shared schema creates a contradiction between the schema and that example.

Suggested approach: use allOf at the createConversation endpoint level only (this pattern is already used 23 times in the spec). In each version file's createConversation 200 response:

# before
              schema:
                "$ref": "#/components/schemas/message"
# after
              schema:
                allOf:
                - "$ref": "#/components/schemas/message"
                required:
                - conversation_id

Leave the shared message schema and createMessage endpoint unchanged.

@markdennis22 @claude
fix: Use allOf to require conversation_id only on createConversation
31df6b7 
The previous approach added conversation_id to the shared message
schema's required array, which would incorrectly enforce it on all
endpoints using that schema (including createMessage, where admin
messages don't include conversation_id). Instead, use allOf at the
createConversation endpoint level to extend the message schema with
conversation_id as required — matching the established pattern used
elsewhere in these specs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@levindixon
Copy link
Contributor

levindixon commented Mar 26, 2026

The allOf approach looks good — thanks for implementing that.

One thing: v2.11 (descriptions/2.11/api.intercom.io.yaml) still has the plain $ref on the createConversation 200 response — it needs the same allOf + required change as the other versions. The PR body says v2.11 "already had it" but it doesn't — it was just missed during the per-version update.

Confirmed it should have the change:

  • AddConversationIdToUserMessageResponse was introduced in v2.2 (service.rb:100), versioning is cumulative, so v2.11 inherits it
  • The v2.11 example response already includes conversation_id: '363'
  • The schema structure is identical to the other versions you updated

@markdennis22 @claude
fix: Apply allOf pattern to v2.11 createConversation response
c8f5d07 
Missed in the initial update — v2.11 inherits
AddConversationIdToUserMessageResponse from v2.2 and its example
already includes conversation_id: '363'.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@markdennis22 markdennis22 merged commit 81c5053 into main Mar 26, 2026
3 checks passed
@markdennis22 markdennis22 deleted the fix/message-conversation-id-required branch March 26, 2026 15:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@levindixon levindixon levindixon approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@markdennis22 @levindixon