feat(web-api): add a chat stream method to the web client #1755

zimeg · 2025-10-01T04:39:41Z

Summary

This PR adds a ChatStream class that creates chat streams with .chat_stream() 🤖

Preview

streamer = client.chat_stream(
    channel="C0123456789",
    thread_ts="123.000",
    recipient_team_id="T0123456789",
    recipient_user_id="U0123456789",
)
streamer.append(markdown_text="nice!")
streamer.stop()

Testing

WIP-

Notes

Hoping to mirror feat(web-api): add a chat stream method to the web client node-slack-sdk#2379 as much as possible!

Requirements

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.
I've run python3 -m venv .venv && source .venv/bin/activate && ./scripts/run_validation.sh after making the changes.

codecov · 2025-10-01T04:45:36Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (ai-apps@bd1857f). Learn more about missing BASE report.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             ai-apps    #1755   +/-   ##
==========================================
  Coverage           ?   85.12%           
==========================================
  Files              ?      115           
  Lines              ?    13068           
  Branches           ?        0           
==========================================
  Hits               ?    11124           
  Misses             ?     1944           
  Partials           ?        0

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

zimeg

🔏 A few fast jots for the wonderful reviewers!

zimeg · 2025-10-02T02:28:33Z

docs/reference/index.html

📚 note: The docs/reference is autogenerated with the latest code changes. I'll follow up with separate PRs that both requires this and hides these from the preview since regular review ought happen with the comments elsewhere IMHO-

🔐 note: Ongoing discussion is happening for this - #1759.

zimeg · 2025-10-02T02:30:57Z

scripts/codegen.py

+    legacy_source = re.sub(r"^from slack_sdk.web.chat_stream import ChatStream\n", "", legacy_source, flags=re.MULTILINE)
+    legacy_source = re.sub(r"(?s)def chat_stream.*?(?=def)", "", legacy_source)


🌲 note: The LegacyWebClient won't find this chat_stream since responses from the various APIs can't be parsed quick - these are either async or sync. Instead we might recommend updating to the latest version.

🔗 https://docs.slack.dev/tools/python-slack-sdk/v3-migration

zimeg · 2025-10-02T02:32:59Z

scripts/codegen.py

📝 note: Planning to include this script as part of the generate_api_docs.sh scripts in follow up to guarantee the latest changes are used. This'll match how unit tests are setup IIRC.

📚 note: Similar changes instead prefer to generate docs before tests in #1759.

zimeg · 2025-10-02T02:33:40Z

slack_sdk/web/async_chat_stream.py

📠 note: This file is autogenerated from slack_sdk/web/client.py! However, kind review that checks for correct async usage is so appreciated!

zimeg · 2025-10-02T02:40:11Z

slack_sdk/web/chat_stream.py

+        if markdown_text:
+            self._buffer += markdown_text


📝 note: Planning to follow up in the node implementation to match this. I find adding to the buffer to be more clear here than below when stopping the stream.

🎁 note: The node implementation is in progress here: slackapi/node-slack-sdk#2388

zimeg

📌 And a question on overall implementations I forgot!

zimeg · 2025-10-02T02:45:57Z

slack_sdk/web/chat_stream.py

+    def append(
+        self,
+        *,
+        markdown_text: str,
+        **kwargs,
+    ) -> Optional[SlackResponse]:


🗣️ question: Are these arguments flexible enough for future changes? It's not obvious how kwargs might be buffered if the call to append doesn't send a request.

🐝 ramble: We can of course follow up with updates in later releases, but I'm wanting to avoid strangeness in implementations in the meantime...

🧠 I think this is flexible for future changes.

Imagine in the future that the chat.appendStream method supports other content, aside from markdown_text. If that happens, we can update it to be markdown_text: Optional[str]. This is a non-breaking change for existing apps and allows us to add new arguments such as new_things: Optional[str] or new_things: Optional[Dict[str, str]].

Today, the kwargs would only work as long as markdown_text is a required field. But I think that's the right choice right now, since it is a required field to append text.

@mwbrooks Wow thanks for calling out that changing "required" to "optional" isn't breaking... That might've been catching me earlier!

I think we'll have to explore additional buffer configuration if those later changes arise, but I now feel confident in this approach 🙏 ✨

mwbrooks

✅ Very solid and well done, @zimeg! I feel like I'm short changing you by not providing deeper feedback, but this came out exactly as I was hoping! 🙌🏻

🧠 This is aligned very well with the Node SDK implementation and I've noticed that you've noted a small improvement to align both around appending text.

🔮 Thinking about the future, our concern is whether this can expand with the future changes to chat_stream. I've left a comment below, but I can see a path that's non-breaking and flexible for us. So I'm happy with it!

🧪 I've manually tested this by writing it up to our AI Sample App. I was able to adjust the buffer size successfully and it simnifically reduced the code and overhead.

mwbrooks · 2025-10-02T02:01:31Z

scripts/codegen.py

+    async_source = re.sub(
+        "from slack_sdk.web.chat_stream import ChatStream",
+        "from slack_sdk.web.async_chat_stream import AsyncChatStream",
+        async_source,
+    )
+    async_source = re.sub(r"ChatStream:", "AsyncChatStream:", async_source)
+    async_source = re.sub(r"ChatStream\(", "AsyncChatStream(", async_source)
+    async_source = re.sub(
+        r" client.chat_stream\(",
+        " await client.chat_stream(",
+        async_source,
+    )
+    async_source = re.sub(
+        r" streamer.append\(",
+        " await streamer.append(",
+        async_source,
+    )
+    async_source = re.sub(
+        r" streamer.stop\(",
+        " await streamer.stop(",
+        async_source,
+    )


note: oof, you definitely had to push the boundaries of this script with that helper!

@mwbrooks Agreed. This wasn't a favorite change to make but I think it'll let us land this with autogenerated changes 🤖

mwbrooks · 2025-10-02T02:01:57Z

scripts/codegen.py

+    legacy_source = re.sub(r"^from slack_sdk.web.chat_stream import ChatStream\n", "", legacy_source, flags=re.MULTILINE)
+    legacy_source = re.sub(r"(?s)def chat_stream.*?(?=def)", "", legacy_source)


question: Can we revert this since the ChatStream isn't landing into the legacy client?

@mwbrooks Let's keep these for now - this removes the chat_stream implementation from the legacy client altogether after the original source file is copied over!

mwbrooks · 2025-10-02T02:07:25Z

slack_sdk/web/chat_stream.py

+        Example:
+            ```python
+            streamer = client.chat_stream(
+                channel="C0123456789",
+                thread_ts="1700000001.123456",
+                recipient_team_id="T0123456789",
+                recipient_user_id="U0123456789",
+            )
+            streamer.append(markdown_text="**hello wo")
+            streamer.append(markdown_text="rld!**")
+            streamer.stop()
+            ```


praise: very nice 👌🏻

mwbrooks · 2025-10-02T02:12:48Z

slack_sdk/web/chat_stream.py

+            recipient_user_id: The encoded ID of the user to receive the streaming text. Required when streaming to channels.
+            buffer_size: The length of markdown_text to buffer in-memory before calling a method. Increasing this value
+              decreases the number of method calls made for the same amount of text, which is useful to avoid rate limits.
+              Default: 256.


question: Technically, this class doesn't have a default buffer size, right? The 256 default is set by the web-client's client.chat_stream constructor.

slack_sdk/web/client.py

mwbrooks · 2025-10-02T02:29:06Z

tests/slack_sdk/web/test_chat_stream.py

+            start_request = self.thread.server.chat_stream_requests.get("/chat.startStream", {})
+            self.assertEqual(start_request.get("channel"), "C0123456789")
+            self.assertEqual(start_request.get("thread_ts"), "123.000")
+            self.assertEqual(start_request.get("recipient_team_id"), "T0123456789")
+            self.assertEqual(start_request.get("recipient_user_id"), "U0123456789")


praise: This is so nice!

mwbrooks · 2025-10-02T02:31:59Z

tests/slack_sdk_async/web/test_async_chat_stream.py

+        await streamer.append(markdown_text="e is", token="xoxb-chat_stream_test_token1")
+        await streamer.append(markdown_text=" bold!")
+        await streamer.append(markdown_text="*")
+        await streamer.stop(markdown_text="*", token="xoxb-chat_stream_test_token2")


suggestion: I noticed that we don't have a test for .stop(blocks="...", ...). Since this is an important feature for the new feedback buttons, we should test that blocks are passed through to the API.

@mwbrooks Fantastic call! We should be serializing these blocks to a consistent string that we now test in 38ec262 👾 ✨

The node tests are also updated in slackapi/node-slack-sdk#2388 to match!

mwbrooks · 2025-10-02T02:32:26Z

tests/slack_sdk_async/web/test_async_chat_stream.py

+            await streamer.stop()
+
+    @async_test
+    async def test_streams_errors_when_appending_to_a_completed_stream(self):


praise: Great use-case!

mwbrooks · 2025-10-02T03:02:50Z

slack_sdk/web/chat_stream.py

+    def append(
+        self,
+        *,
+        markdown_text: str,
+        **kwargs,
+    ) -> Optional[SlackResponse]:


🧠 I think this is flexible for future changes.

Imagine in the future that the chat.appendStream method supports other content, aside from markdown_text. If that happens, we can update it to be markdown_text: Optional[str]. This is a non-breaking change for existing apps and allows us to add new arguments such as new_things: Optional[str] or new_things: Optional[Dict[str, str]].

Today, the kwargs would only work as long as markdown_text is a required field. But I think that's the right choice right now, since it is a required field to append text.

mwbrooks · 2025-10-02T03:05:40Z

tests/slack_sdk/web/test_chat_stream.py

+class ChatStreamMockHandler(MockHandler):
+    """Extended mock handler that captures request bodies for chat stream methods"""


suggestion(non-blocking, future): This is very impressive that you've build your own mock server for handling the tests. We may want to talk to @WilliamBergamin to see if he has opinions or ideas around this approach. But from my perspective, this is contained to our chat_stream tests and builds upon the existing mock server work, so I think we should move forward with it.

@mwbrooks Kind thanks. I found this to be decent for confirming expected arguments and headers are being sent with streaming requests, but I support other approaches!

For now let's use this as a starting point, but we should revisit this with suggestions otherwise 🤖

Co-authored-by: Michael Brooks <[email protected]>

zimeg · 2025-10-02T17:10:20Z

@mwbrooks I appreciate your reviews so much! Thanks for sharing kind suggestions and thoughts of the future too 👾 ✨

I'll merge this for a release that we can test with, but I remain so open to improving both the organization of files and tests in follow up changes. Let's hope to keep the implementations similar in node and python otherwise 🙏

zimeg · 2025-10-02T22:27:46Z

Sample app reference WIP: slack-samples/bolt-python-assistant-template#16 🧪 ✨

feat(web-api): add a chat stream method to the web client

73e46fd

zimeg requested review from WilliamBergamin, mwbrooks and srtaalej October 1, 2025 04:39

zimeg self-assigned this Oct 1, 2025

zimeg added enhancement M-T: A feature request for new functionality semver:minor web-client Version: 3x area:async labels Oct 1, 2025

zimeg added 11 commits October 1, 2025 11:48

fix: override the token if provided in append or stop methods

cba64c1

fix: codegen async

99cccd1

fix: remove optional arguments with a default

ee25536

test: confirm async implementation matches sync

af7bea2

docs: match async setups in testing

fe40900

chore: autogenerate the async chat stream helper

557681b

docs: autogenerate reference

64f4b14

feat: remove legacy implementation

03566bd

fix: improve docs to match arguments with better testing

187c719

style: alphabetical methods

b7964ad

style: lint

8a8ecb3

zimeg marked this pull request as ready for review October 1, 2025 23:32

style: codegen without changing legacy client

a962196

zimeg commented Oct 2, 2025

View reviewed changes

test: remove codegen reminent

82d1495

mwbrooks approved these changes Oct 2, 2025

View reviewed changes

zimeg and others added 2 commits October 2, 2025 09:37

docs: make the buffered methods clear in reference

dbe397f

Co-authored-by: Michael Brooks <[email protected]>

docs: match correct defaults with linebreaks for lint

702e19c

zimeg added 2 commits October 2, 2025 09:56

docs: update generated docs

dc88b03

test: confirm context actions can be sent with stop

38ec262

zimeg merged commit 64a995c into ai-apps Oct 2, 2025
12 checks passed

zimeg deleted the zimeg-feat-web-chat-stream branch October 2, 2025 17:10

zimeg mentioned this pull request Oct 2, 2025

refactor(web-api): align chat stream implementation with python sdk slackapi/node-slack-sdk#2388

Merged

2 tasks

		legacy_source = re.sub(r"^from slack_sdk.web.chat_stream import ChatStream\n", "", legacy_source, flags=re.MULTILINE)
		legacy_source = re.sub(r"(?s)def chat_stream.*?(?=def)", "", legacy_source)

		class ChatStreamMockHandler(MockHandler):
		"""Extended mock handler that captures request bodies for chat stream methods"""

feat(web-api): add a chat stream method to the web client #1755

feat(web-api): add a chat stream method to the web client #1755

Uh oh!

Conversation

zimeg commented Oct 1, 2025

Summary

Preview

Testing

Notes

Category

Requirements

Uh oh!

codecov bot commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mwbrooks left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zimeg commented Oct 2, 2025

Uh oh!

Uh oh!

zimeg commented Oct 2, 2025

codecov bot commented Oct 1, 2025 •

edited

Loading