docs: add say_stream notes to the experiments page by lukegalbraithrussell · Pull Request #1463 · slackapi/bolt-python

lukegalbraithrussell · 2026-03-19T00:11:41Z

Summary

This PR adds docs for the say_stream helper in the sending messages page. Picture is the preview:

/tools/bolt-python/concepts/message-sending:

Testing

Requirements

Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you are agreeing to those rules.

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 ./scripts/install_all_and_run_tests.sh after making the changes.

lukegalbraithrussell · 2026-03-19T00:12:12Z

docs/english/_sidebar.json

-		"label": "Experiments",
-		"items": ["tools/bolt-python/experiments"]
-	},
+	"tools/bolt-python/experiments",


this was my bad; should've been a page from the beginning

codecov · 2026-03-19T04:01:25Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.31%. Comparing base (ba7df02) to head (fd123aa).
⚠️ Report is 1 commits behind head on docs-agent-kit.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@                Coverage Diff                 @@
##           docs-agent-kit    #1463      +/-   ##
==================================================
- Coverage           91.43%   91.31%   -0.12%     
==================================================
  Files                 232      229       -3     
  Lines                7340     7266      -74     
==================================================
- Hits                 6711     6635      -76     
- Misses                629      631       +2

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

zimeg · 2026-03-19T16:55:12Z

⚠️ Merge conflicts bewarned! These commits might show odd diff now I think?

lukegalbraithrussell · 2026-03-19T17:04:17Z

⚠️ Merge conflicts bewarned! These commits might show odd diff now I think?

@zimeg I reset the branch to just be docs changes!

WilliamBergamin

Awesome work on this 🥇 Wasn't sure how to frame all this but this is spot on

WilliamBergamin · 2026-03-19T20:35:57Z

docs/english/experiments.md

+
+## `say_stream` utility {#say-stream}
+
+The `say_stream` utility is a listener argument available on `app.event` and `app.message` listeners. 


WilliamBergamin · 2026-03-19T20:36:52Z

docs/english/experiments.md

+| `recipient_team_id` | Sourced from the event `team_id` (`enterprise_id` if the app is installed on an org).
+| `recipient_user_id` | Sourced from the `user_id` of the event.
+
+If neither a `channel_id` or `thread_ts` can be sourced, then the utility will merely be `None`.


Fantastic 🥇

WilliamBergamin · 2026-03-19T20:37:44Z

docs/english/experiments.md

+@app.message("")
+def handle_message(client: WebClient, say_stream: SayStream):
+  stream = say_stream()
+


Nit: do we need this empty space?

srtaalej

looks really great luke! ⭐

srtaalej · 2026-03-26T16:13:02Z

docs/english/concepts/message-sending.md

 * [`chat_stopStream`](/reference/methods/chat.stopStream)

-The Python Slack SDK provides a [`chat_stream()`](https://docs.slack.dev/tools/python-slack-sdk/reference/web/client.html#slack_sdk.web.client.WebClient.chat_stream) helper utility to streamline calling these methods. Here's an excerpt from our [Assistant template app](https://github.com/slack-samples/bolt-python-assistant-template):
+Bolt for Python provides a `say_stream` listener argument available on `app.event` and `app.message` listeners. 


super nice ⭐

srtaalej · 2026-03-26T16:16:15Z

docs/english/concepts/message-sending.md

+| `recipient_team_id` | Sourced from the event `team_id` (`enterprise_id` if the app is installed on an org).
+| `recipient_user_id` | Sourced from the `user_id` of the event.
+
+If neither a `channel_id` or `thread_ts` can be sourced, then the utility will merely be `None`.


nit: i feel like this can be clearer

Suggested change

If neither a `channel_id` or `thread_ts` can be sourced, then the utility will merely be `None`.

If neither a `channel_id` or `thread_ts` can be sourced, then the utility will just be `None`.

mwbrooks

✅ Looking great! I've left a few minor suggestions but nothing is blocking.

mwbrooks · 2026-03-26T18:46:51Z

docs/english/concepts/message-sending.md

+You can have your app's messages stream in to replicate conventional agent behavior. This is done through three Web API methods:

 * [`chat_startStream`](/reference/methods/chat.startStream)
 * [`chat_appendStream`](/reference/methods/chat.appendStream)
 * [`chat_stopStream`](/reference/methods/chat.stopStream)


nit(non-blocking): Showing the 3 Web API methods to manually stream messages at the very top is a little confusing. Also, L54 mentions that say_stream uses this API under-the-hood and there's a nice callout at the bottom explaining how to manually use the Web API Streaming methods.

Could this sentence be merged with the next paragraph? For example:

You can have your app's messages stream in to replicate conventional agent behaviour. Bolt for Python provides a say_stream utility is available on app.event and app.message listeners.

mwbrooks · 2026-03-26T18:51:37Z

docs/english/concepts/message-sending.md

 * [`chat_stopStream`](/reference/methods/chat.stopStream)

-The Python Slack SDK provides a [`chat_stream()`](https://docs.slack.dev/tools/python-slack-sdk/reference/web/client.html#slack_sdk.web.client.WebClient.chat_stream) helper utility to streamline calling these methods. Here's an excerpt from our [Assistant template app](https://github.com/slack-samples/bolt-python-assistant-template):
+Bolt for Python provides a `say_stream` listener argument available on `app.event` and `app.message` listeners. 


suggestion: The current sentence is correct, but "argument" is often thought of as a simple variable or object. We use the term "utility" below, so maybe can clarify that say_stream is a utility provided as a listener argument.

Suggested change

Bolt for Python provides a `say_stream` listener argument available on `app.event` and `app.message` listeners.

Bolt for Python provides a `say_stream` utility as a listener argument for `app.event` and `app.message` listeners.

mwbrooks · 2026-03-26T18:53:51Z

docs/english/experiments.md

 ### Limitations

-The `chat_stream()` method currently only works when the `thread_ts` field is available in the event context (DMs and threaded replies). Top-level channel messages do not have a `thread_ts` field, and the `ts` field is not yet provided to `BoltAgent`.
+The `chat_stream()` method currently only works when the `thread_ts` field is available in the event context (DMs and threaded replies). Top-level channel messages do not have a `thread_ts` field, and the `ts` field is not yet provided to `BoltAgent`.


note: I believe we've fixed this issue so say_stream() is now available on top-level channel messages and uses the ts as the thread_ts value. We've also updated chat_stream() to be say_stream().

.cc @WilliamBergamin

lukegalbraithrussell requested a review from a team as a code owner March 19, 2026 00:11

lukegalbraithrussell requested review from WilliamBergamin, mwbrooks and zimeg March 19, 2026 00:11

lukegalbraithrussell commented Mar 19, 2026

View reviewed changes

Base automatically changed from say_stream to main March 19, 2026 13:57

WilliamBergamin requested a review from a team as a code owner March 19, 2026 13:57

zimeg changed the title ~~Docs: say_stream~~ docs: add say_stream notes to the experiments page Mar 19, 2026

zimeg added docs Improvements or additions to documentation semver:patch experiment Experimental feature documented with ExperimentalWarning and pydoc Experiment section labels Mar 19, 2026

just docs

422c62f

lukegalbraithrussell force-pushed the docs-say_stream-docs branch from 6048885 to 422c62f Compare March 19, 2026 17:03

WilliamBergamin approved these changes Mar 19, 2026

View reviewed changes

Merge branch 'main' into docs-say_stream-docs

34530f7

lukegalbraithrussell changed the base branch from main to docs-agent-kit March 20, 2026 18:49

lukegalbraithrussell added 2 commits March 24, 2026 16:12

go

14a4273

remove experiment

fd123aa

lukegalbraithrussell requested a review from WilliamBergamin March 24, 2026 23:17

lukegalbraithrussell mentioned this pull request Mar 24, 2026

docs - adds chat_stream helper to python sdk docs (removing from bolt-py) slackapi/python-slack-sdk#1846

Merged

15 tasks

srtaalej approved these changes Mar 26, 2026

View reviewed changes

srtaalej reviewed Mar 26, 2026

View reviewed changes

mwbrooks approved these changes Mar 26, 2026

View reviewed changes


		## `say_stream` utility {#say-stream}

		The `say_stream` utility is a listener argument available on `app.event` and `app.message` listeners.

	If neither a `channel_id` or `thread_ts` can be sourced, then the utility will merely be `None`.
	If neither a `channel_id` or `thread_ts` can be sourced, then the utility will just be `None`.

	Bolt for Python provides a `say_stream` listener argument available on `app.event` and `app.message` listeners.
	Bolt for Python provides a `say_stream` utility as a listener argument for `app.event` and `app.message` listeners.

Conversation

lukegalbraithrussell commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Category

Requirements

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

zimeg commented Mar 19, 2026

Uh oh!

lukegalbraithrussell commented Mar 19, 2026

Uh oh!

WilliamBergamin 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!

srtaalej 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lukegalbraithrussell commented Mar 19, 2026 •

edited

Loading

codecov bot commented Mar 19, 2026 •

edited

Loading