fix: handle missing channelData in ConversationUpdateActivity for Direct Line

[rajan-chari]

Summary

Bug: Direct Line sends conversationUpdate activities without channelData, but ConversationUpdateActivity.channel_data is a required field. Pydantic rejects the payload with a ValidationError before any handler code runs.

Fix: Add a model_validator(mode="before") on ConversationUpdateActivity that injects an empty ConversationChannelData when channelData is absent from the incoming payload. This keeps channel_data as a required, non-optional field — preserving the type contract for Teams developers.

Design rationale

We considered four approaches and chose Option C (default at deserialization) after cross-SDK review:

Option	Approach	Rejected because
A	Make channel_data Optional	Weakens type contract for 99% of users (Teams devs). Required 10 None-guards in route selectors — code smell.
B	Polymorphic models per channel	Overkill for field-presence differences.
C	Default at deserialization ✅	—
D	Catch ValidationError at HTTP layer	Fragile, hides real validation problems.

Why Option C: Matches the TypeScript SDK pattern. In TS, IConversationUpdateActivity declares channelData as required (conversation-update.ts:25) but the router uses optional chaining defensively (router.ts:73-87). Python's Pydantic enforces types at runtime (unlike TS interfaces which are erased), so the model_validator bridges the gap — it runs before field validation and ensures channelData is always present.

Result:

• Teams activities: channel_data populated normally, event-type routing works as before
• Direct Line activities: channel_data is an empty ConversationChannelData (with event_type=None), so Teams-specific handlers (e.g. on_channel_created) don't fire, but the generic on_conversation_update handler still does
• Type checkers: See a non-optional ConversationChannelData — no None-guards needed anywhere

Files changed

• conversation_update.py — added model_validator, extensive docstring explaining the design
• activity_route_configs.py — reverted to original (no None-guards needed)

Test plan

• All 577 existing tests pass (no new test failures)
• Bot deployment: Direct Line conversationUpdate without channelData — should succeed (was ValidationError)
• Bot deployment: Teams conversationUpdate with channelData — should parse and route normally
• Regression: on_channel_created, on_team_archived, etc. still fire for Teams events

Fixes #239

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adjusts the ConversationUpdateActivity model in the API package to accept conversationUpdate payloads that omit channelData (notably from Direct Line), preventing Pydantic validation failures during activity parsing.

Changes:

• Changes ConversationUpdateActivity.channel_data to Optional[ConversationChannelData] = None (instead of required).
• Removes the prior pyright: ignore suppression tied to the incompatible override.

[Copilot]

Making ConversationUpdateActivity.channel_data optional fixes Pydantic validation, but it also means downstream code must handle channel_data=None. The apps router evaluates all selectors (ActivityRouter.select_handlers iterates every route), and several selectors in packages/apps/src/microsoft_teams/apps/routing/activity_route_configs.py access activity.channel_data.event_type for ConversationUpdateActivity without a None-guard (e.g., channel_created, team_deleted, etc.). With a Direct Line conversationUpdate missing channel_data, this will raise AttributeError during routing and still fail the request. Update those selectors to short-circuit when activity.channel_data is None before reading event_type.

[rajan-chari]

Manual Test Results — Revised Approach (model_validator)

Tested on branch fix/239-optional-channel-data (commit 3b0af3e). Python echo bot (pr340-echo) deployed to BAMI1 tenant via DevTunnel.

#	Test	Result	Details
1	Direct Line conversationUpdate (no channel_data)	PASS (via pyright + code review)	model_validator defaults empty ConversationChannelData() when channelData is missing. No ValidationError.
2	Teams conversationUpdate (with channel_data)	PASS	Bot replied to messages — Teams conversationUpdate events parsed correctly, no crash
3	Conversation update handlers fire normally	PASS (via code review)	channel_data stays required (non-Optional), so all channel_data.event_type accesses in route selectors work without None-guards

Approach review

The revised model_validator approach is much cleaner than the previous Optional approach:

• Required field preserved — type contract unchanged, no None-guards needed
• model_validator defaults empty — Direct Line payloads get ConversationChannelData() with event_type=None
• No routing changes — activity_route_configs.py reverted to original (no None-guards)
• Consistent with TS SDK — matches the pattern where channelData is declared required but handled defensively

Pyright

• Local: 0 errors on activity_route_configs.py
• 4 pre-existing errors in conversation_update.py (same as main — not from this PR)

CI

• Build, Lint & Test hasn't triggered for latest commit yet (Analyze + CodeQL pass)
• Previous iteration (d5caf76) passed all 3 Python versions

[rajan-chari]

Q&A: Should the model_validator default only apply for Direct Line?

A reviewer question came up: should we check channelId and only default channelData for Direct Line, rather than universally?

Answer: No — the universal approach is architecturally correct.

1. Separation of concerns. The model_validator is a deserialization boundary fix — its job is "make the payload structurally valid for Pydantic." Channel-specific decisions belong in the router (which already handles this: event_type=None means Teams-specific handlers don't fire). Mixing channel awareness into deserialization conflates two layers.

2. Matches the TS SDK pattern. The TS router uses activity.channelData?.eventType (router.ts:73-87) universally — it doesn't check channelId first. It's defensive regardless of source. This fix matches that approach.

3. Scoping to Direct Line is fragile. WebChat, Slack, or custom channels may also omit channelData. A Direct-Line-only check creates a growing allowlist. The universal default handles all channels automatically.

4. Checking channelId in model_validator is unreliable. In mode='before', the raw dict may not have channelId set yet depending on payload structure. The model layer shouldn't depend on channel semantics.

5. The concern about masking Teams bugs is valid but better addressed elsewhere. If Teams sends a payload without channelData (which would be a real bug), the failure mode is still observable: event_type=None, so on_channel_created/on_team_archived don't fire. The developer sees "my handler isn't running" — debuggable. Compare to the current behavior: ValidationError crashes the entire request. The universal default is strictly better.

If early warning is desired: Add a log warning in the router or middleware — if channelId == msteams and channel_data.event_type is None, log a warning. That gives visibility without gating deserialization on channel knowledge.

[corinagum]

The TypeScript reference URLs in the PR description point to nicknow/teams.ts, which is a fork. Use the canonical microsoft/teams.ts URLs.

[corinagum]

MessageUpdateActivity (and MessageDeleteActivity) have the same "required channel_data on output, optional on base" shape, and the route selectors at activity_route_configs.py:107, 129, 137 rely on activity.channel_data.event_type. If Direct Line ever sends a messageUpdate/messageDelete without channelData, the same ValidationError fires that this PR is fixing for conversationUpdate. The fix should be symmetric.

Note: MessageDeleteChannelData.event_type is Literal["softDeleteMessage"] with no default, so {} won't deserialize for it. A shared _default_channel_data mixin would need to be parameterized by the channel-data class.

[corinagum]

The PR description says "all 577 existing tests pass" but adds none.

Add a regression test that parses a Direct Line payload.

[corinagum]

The docstring frames this as "incoming Direct Line payload" handling, but mode="before" + isinstance(data, dict) means it also fires when callers construct ConversationUpdateActivity(**some_dict) in their own code. Either tighten the docstring to describe the actual scope, or document that this is a permanent invariant of constructing the activity from a dict.