[csdinos]

Why?

The WhatsApp side of POST /messages was described inaccurately in 2.16, 2.17, 2.18 and Preview. The docs claimed a default sender is used, didn't mention from.whatsapp_number, said to can be an array, and gave no WhatsApp examples. Integrators had to find out how WhatsApp sends behave by trial and error.

How?

Corrects those field descriptions and adds WhatsApp success and error examples in all four versions, matching how the API behaves today. Docs only: the API does not change in any version.

Notes for reviewers

• The new 400 examples go after Recipient missing (after No body supplied for message in 2.16). The last 400 example before schema: is unchanged, so Document the WhatsApp monthly limit error on POST /messages #756 can still add its monthly-limit example there.
• fern check with fern-api 5.65.3: 0 errors and 319 warnings, the same as main.

_{Generated with Claude Code}

[shrek-intercom]

❌ PR Review Summary: NEEDS HUMAN REVIEW

	Summary
✅	🎯 Problem — The description clearly and concisely identifies the specific WhatsApp documentation inaccuracies across four API versions and their impact, with a brief 'How' section confirming it's a docs-only change.
✅	📝 Alignment — The diff is fully consistent with the PR description, implementing all the stated corrections (from/whatsapp_number fields, to array behavior, new success/error examples) across the four listed spec files with no undisclosed scope changes.
✅	🧠 Correctness — A minor issue was found where the new WhatsApp success example added in the 2.16 spec conflicts with its referenced schema, since that schema's message_type enum does not include whatsapp.
✅	🦺 Safety — The change is a documentation-only update to OpenAPI spec YAML files across four API versions, correcting descriptions and adding examples with no code, CI, or dependency changes, making it safe to merge.
❌	🚦 Auto-approval — Repo 'intercom/Intercom-OpenAPI' is not in the REPO_CONFIG auto-approval allowlist; Exceeds LOC limit (637 meaningful LOC > 150, raw 637)

Per-criterion details

Problem

The description concisely identifies the specific problem (inaccurate WhatsApp docs across four versions: wrong default sender claim, missing from.whatsapp_number, incorrect array type for to, no examples) and the impact (integrators resorting to trial and error). The 'How' section is brief and clarifies it's docs-only with no API change, and verbose reviewer notes are collapsed.

Alignment

The diff only touches YAML description files (docs/spec text, examples, response descriptions) in descriptions/0 (Preview), 2.16, 2.17, and 2.18 — matching the title and the 'Files Changed' list. The specific corrections described in the PR are all present in the diff: the 'from' field description changes from 'default sender will be used' to 'Required... returns a 400 error'; 'from.whatsapp_number' is newly added with a description; the 'to' array description now explicitly states it's not accepted for whatsapp messages; and new WhatsApp success (200) and error (400/403/500) examples are added across all four files. The admonition text about conversation retrieval for whatsapp vs email/in-app messages is also updated, consistent with 'matching how the API behaves today'. Additional minor additions (500 errors, 403 blocked-recipient example, component usage note) are reasonable elaborations of 'adds WhatsApp success and error examples' rather than undisclosed scope changes. No functional/API code changes are present, consistent with the 'Docs only' claim. Overall the description accurately reflects the diff's content and scope.

Correctness

The PR corrects WhatsApp POST /messages descriptions and adds success and error examples in versions 2.16–2.18 and Preview.

Finding 1: [priority 2]
Location: descriptions/2.16/api.intercom.io.yaml:17533
Issue: The new WhatsApp success example violates its referenced message schema, whose message_type enum excludes whatsapp.
Why it breaks: Schema validation rejects the newly documented successful response; validating all 64 added WhatsApp response examples confirmed this mismatch only in 2.16.

Turns

Turn 1: 1 finding(s) (grade: correct)
Turn 2: 0 finding(s) (grade: correct)

Safety

This PR is a documentation-only change to OpenAPI specification YAML files across four API versions (Preview/0, 2.16, 2.17, 2.18). The changes correct field descriptions, add WhatsApp success/error response examples, and clarify behavior notes — all matching existing API behavior. No code, scripts, CI workflows, CLAUDE.md files, or dependencies are modified.

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