[nijeesh-stream]

Submit a pull request

CLA

• I have signed the Stream CLA (required).
• The code changes follow best practices
• Code changes are tested (add some information if not applicable)

Description of the pull request

TLDR

Lets a backend schedule a chat message to be sent later on behalf of a user, and then edit, cancel, send now or list those scheduled messages. Adds SDK methods only (sync and async). Existing behavior is unchanged unless scheduled_at is passed.

Risk: if scheduled_at is sent to a backend that does not know it yet, the backend ignores the field and sends the message immediately. The response then has no scheduled_message, which is how callers (and the integration tests) can tell.

Backend endpoints are behind a per-app flag and not yet released; merge after backend CHA-5924 ships.

Ticket

• https://linear.app/stream/issue/CHA-5933

What's added

• Channel.send_message(..., scheduled_at=datetime | str): a datetime is converted to UTC ISO 8601 (naive datetimes are taken as UTC). The response then carries scheduled_message.
• update_scheduled_message(scheduled_message_id, message=None, scheduled_at=None) → PATCH /scheduled_messages/{id} (at least one of the two is required).
• delete_scheduled_message(scheduled_message_id) → DELETE /scheduled_messages/{id} (cancel, or remove a failed one).
• send_scheduled_message_now(scheduled_message_id) → POST /scheduled_messages/{id}/send_now.
• query_scheduled_messages(user_id, filter=None, sort=None, options=None) → POST /scheduled_messages/query, mirroring query_drafts (filter by cid and status; sort scheduled_at ascending only; limit 1-100; next cursor).
• Types in stream_chat/types/scheduled_messages.py: QueryScheduledMessagesFilter, QueryScheduledMessagesOptions, ScheduledMessageStatus.
• Docs: docs/messages/scheduled_messages.md (includes the scheduled_message.* events; this SDK does not model event types).

Not added: include_scheduled_messages on channel query. The backend ignores it on server-side requests, so it has no effect from this SDK. App settings for the feature are not exposed by the app settings API.

Tests

• test_scheduled_messages_unit.py: mock-based tests (like test_channel_delete.py) for the request each new call sends, sync and async, plus datetime formatting.
• test_scheduled_messages.py and async_chat/test_scheduled_messages.py: integration tests (schedule → query → update → delete, and send now). They skip when the app does not have scheduled messages enabled (scheduled_messages_disabled) or the API does not return scheduled_message. The flag is set per app by Stream and is not in the app settings API, so the CI app cannot be baselined into it. Against a local backend with the flag off, they skip as intended.
• black, flake8, mypy clean on the changed files. CHANGELOG is generated at release time, so it is not edited here.

🤖 Generated with Claude Code

---

Note

Medium Risk
New message-send path and tight coupling to a per-app backend flag; on servers that ignore scheduled_at, messages may send immediately without scheduled_message in the response.

Overview
Adds scheduled messages support to the sync and async Stream Chat Python clients, wired to the new scheduled_messages/* APIs.

Scheduling: Channel.send_message(..., scheduled_at=...) now accepts a UTC datetime or ISO 8601 string (via format_scheduled_at) and includes that field on the channel message POST when set; responses can include scheduled_message instead of publishing immediately.

Lifecycle APIs on the client: update_scheduled_message, delete_scheduled_message, send_scheduled_message_now, and query_scheduled_messages (filter by cid/status, paginate with limit/next), with matching abstract methods on StreamChatInterface and typed helpers in stream_chat/types/scheduled_messages.py.

Also adds user-facing docs in docs/messages/scheduled_messages.md and unit plus integration tests for request shapes and the schedule → query → update → delete / send-now flows.

^{Reviewed by Cursor Bugbot for commit 7addceb. Bugbot is set up for automated code reviews on this repo. Configure here.}