docs: add say_stream notes to the sending messages 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

- "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

+
+## `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

+| `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

+@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

 * [`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

+| `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

+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

 * [`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

 ### 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 mainMarch 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 pageMar 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 422c62fCompare 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-kitMarch 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

feedback
bca2b74

lukegalbraithrussell changed the title ~~docs: add say_stream notes to the experiments page~~docs: add say_stream notes to the sending messages pageMar 31, 2026

lukegalbraithrussell merged commit 65ac185 into docs-agent-kitMar 31, 2026
1 check passed

lukegalbraithrussell deleted the docs-say_stream-docs branch March 31, 2026 18:28


		## `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.

Uh oh!

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!

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lukegalbraithrussell commented Mar 19, 2026•
edited
Loading

codecovBot commented Mar 19, 2026•
edited
Loading