Skip to content

feat: add task_display_mode option to the start of chat streams #1820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zimeg merged 12 commits into from
Jan 17, 2026
+24 −0
Merged

feat: add task_display_mode option to the start of chat streams #1820

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
c3bdb2d
feat: accept chunks as arguments to chat.{start,append,stop}Stream me…
zimeg Dec 11, 2025
8c56e22
fix: remove unsupported and unused identifiers for full support
zimeg Dec 16, 2025
783ada5
style: remove mypy extra ignore comment for overriden attributes
zimeg Dec 17, 2025
1fb7355
test: confirm chunks parse as expected json values
zimeg Dec 17, 2025
5de794b
feat: support and flush chunks in the chat stream helper
zimeg Dec 17, 2025
61d6d53
test: dump chunks json before comparison for exact parsings
zimeg Dec 18, 2025
85081e1
test: update async tests to expect chunks when flushing buffer
zimeg Dec 18, 2025
a6bb951
style: prefer using markdown text chunks in internal calls
zimeg Dec 18, 2025
92c93e0
fix: support explicit json values as chunk objects
zimeg Dec 18, 2025
7c32814
fix: mirror dictionary chunk option to async streamer
zimeg Jan 13, 2026
efb7ba2
feat: add task_display_mode option to the start of chat streams
zimeg Jan 13, 2026
41b068d
chore: merge w base branch
zimeg Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions slack_sdk/web/async_chat_stream.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ def __init__(
buffer_size: int,
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
task_display_mode: Optional[str] = None,
**kwargs,
):
"""Initialize a new ChatStream instance.
Expand All @@ -54,6 +55,8 @@ def __init__(
recipient_team_id: The encoded ID of the team the user receiving the streaming text belongs to. Required when
streaming to channels.
recipient_user_id: The encoded ID of the user to receive the streaming text. Required when streaming to channels.
task_display_mode: Specifies how tasks are displayed in the message. A "timeline" displays individual tasks
interleaved with text and "plan" displays all tasks together.
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.
**kwargs: Additional arguments passed to the underlying API calls.
Expand All @@ -66,6 +69,7 @@ def __init__(
"thread_ts": thread_ts,
"recipient_team_id": recipient_team_id,
"recipient_user_id": recipient_user_id,
"task_display_mode": task_display_mode,
**kwargs,
}
self._buffer = ""
Expand Down
6 changes: 6 additions & 0 deletions slack_sdk/web/async_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2889,6 +2889,7 @@ async def chat_startStream(
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
chunks: Optional[Sequence[Union[Dict, Chunk]]] = None,
task_display_mode: Optional[str] = None, # timeline, plan
Copy link
Contributor

@WilliamBergamin WilliamBergamin Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(take it or leave it) we could potentially use enums here, but if it does not fall in line with existing patterns we shouldn't do it

Edit: actually maybe it would be worth having the web API return a proper error message with the possible options if an invalid value is passed

Copy link
Member

@mwbrooks mwbrooks Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, I think it's good to expect the API return an error message with the the available options when an invalid option value is passed.

The display modes are aiming to support what's common in LLM UIs, so I imagine there will be more in the future that Slack will want to support. It would be nice for developers to have access to the new modes without upgrading the SDK version (I'm assuming an enum would require an SDK upgrade to support the new options?)

Copy link
Member Author

@zimeg zimeg Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@WilliamBergamin @mwbrooks Oh dang, the tradeoffs are fascinating! 😳

I think I agree letting the API error for invalid values might be best for ongoing maintenance and I hope for now this comment is quick enough to jump to for fast reference. I'll update some notes to avoid using enums in adjacent changes too 📚

Prior art for me was found just above:

python-slack-sdk/slack_sdk/web/client.py

Line 2765 in efb7ba2

parse: Optional[str] = None, # none, full

**kwargs,
) -> AsyncSlackResponse:
"""Starts a new streaming conversation.
Expand All @@ -2902,6 +2903,7 @@ async def chat_startStream(
"recipient_team_id": recipient_team_id,
"recipient_user_id": recipient_user_id,
"chunks": chunks,
"task_display_mode": task_display_mode,
}
)
_parse_web_class_objects(kwargs)
Expand Down Expand Up @@ -2944,6 +2946,7 @@ async def chat_stream(
thread_ts: str,
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
task_display_mode: Optional[str] = None,
**kwargs,
) -> AsyncChatStream:
"""Stream markdown text into a conversation.
Expand All @@ -2970,6 +2973,8 @@ async def chat_stream(
recipient_team_id: The encoded ID of the team the user receiving the streaming text belongs to. Required when
streaming to channels.
recipient_user_id: The encoded ID of the user to receive the streaming text. Required when streaming to channels.
task_display_mode: Specifies how tasks are displayed in the message. A "timeline" displays individual tasks
interleaved with text and "plan" displays all tasks together.
**kwargs: Additional arguments passed to the underlying API calls.

Returns:
Expand All @@ -2995,6 +3000,7 @@ async def chat_stream(
thread_ts=thread_ts,
recipient_team_id=recipient_team_id,
recipient_user_id=recipient_user_id,
task_display_mode=task_display_mode,
buffer_size=buffer_size,
**kwargs,
)
Expand Down
4 changes: 4 additions & 0 deletions slack_sdk/web/chat_stream.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ def __init__(
buffer_size: int,
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
task_display_mode: Optional[str] = None,
**kwargs,
):
"""Initialize a new ChatStream instance.
Expand All @@ -44,6 +45,8 @@ def __init__(
recipient_team_id: The encoded ID of the team the user receiving the streaming text belongs to. Required when
streaming to channels.
recipient_user_id: The encoded ID of the user to receive the streaming text. Required when streaming to channels.
task_display_mode: Specifies how tasks are displayed in the message. A "timeline" displays individual tasks
interleaved with text and "plan" displays all tasks together.
Copy link
Contributor

@srtaalej srtaalej Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 lgtm

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.
**kwargs: Additional arguments passed to the underlying API calls.
Expand All @@ -56,6 +59,7 @@ def __init__(
"thread_ts": thread_ts,
"recipient_team_id": recipient_team_id,
"recipient_user_id": recipient_user_id,
"task_display_mode": task_display_mode,
**kwargs,
}
self._buffer = ""
Expand Down
6 changes: 6 additions & 0 deletions slack_sdk/web/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2879,6 +2879,7 @@ def chat_startStream(
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
chunks: Optional[Sequence[Union[Dict, Chunk]]] = None,
task_display_mode: Optional[str] = None, # timeline, plan
**kwargs,
) -> SlackResponse:
"""Starts a new streaming conversation.
Expand All @@ -2892,6 +2893,7 @@ def chat_startStream(
"recipient_team_id": recipient_team_id,
"recipient_user_id": recipient_user_id,
"chunks": chunks,
"task_display_mode": task_display_mode,
}
)
_parse_web_class_objects(kwargs)
Expand Down Expand Up @@ -2934,6 +2936,7 @@ def chat_stream(
thread_ts: str,
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
task_display_mode: Optional[str] = None,
**kwargs,
) -> ChatStream:
"""Stream markdown text into a conversation.
Expand All @@ -2960,6 +2963,8 @@ def chat_stream(
recipient_team_id: The encoded ID of the team the user receiving the streaming text belongs to. Required when
streaming to channels.
recipient_user_id: The encoded ID of the user to receive the streaming text. Required when streaming to channels.
task_display_mode: Specifies how tasks are displayed in the message. A "timeline" displays individual tasks
interleaved with text and "plan" displays all tasks together.
**kwargs: Additional arguments passed to the underlying API calls.

Returns:
Expand All @@ -2985,6 +2990,7 @@ def chat_stream(
thread_ts=thread_ts,
recipient_team_id=recipient_team_id,
recipient_user_id=recipient_user_id,
task_display_mode=task_display_mode,
buffer_size=buffer_size,
**kwargs,
)
Expand Down
2 changes: 2 additions & 0 deletions slack_sdk/web/legacy_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2890,6 +2890,7 @@ def chat_startStream(
recipient_team_id: Optional[str] = None,
recipient_user_id: Optional[str] = None,
chunks: Optional[Sequence[Union[Dict, Chunk]]] = None,
task_display_mode: Optional[str] = None, # timeline, plan
**kwargs,
) -> Union[Future, SlackResponse]:
"""Starts a new streaming conversation.
Expand All @@ -2903,6 +2904,7 @@ def chat_startStream(
"recipient_team_id": recipient_team_id,
"recipient_user_id": recipient_user_id,
"chunks": chunks,
"task_display_mode": task_display_mode,
}
)
_parse_web_class_objects(kwargs)
Expand Down
2 changes: 2 additions & 0 deletions tests/slack_sdk/web/test_chat_stream.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,7 @@ def test_streams_a_chunk_message(self):
recipient_team_id="T0123456789",
recipient_user_id="U0123456789",
thread_ts="123.000",
task_display_mode="timeline",
)
streamer.append(markdown_text="**this is ")
streamer.append(markdown_text="buffered**")
Expand Down Expand Up @@ -223,6 +224,7 @@ def test_streams_a_chunk_message(self):
)
self.assertEqual(start_request.get("recipient_team_id"), "T0123456789")
self.assertEqual(start_request.get("recipient_user_id"), "U0123456789")
self.assertEqual(start_request.get("task_display_mode"), "timeline")

append_request = self.thread.server.chat_stream_requests.get("/chat.appendStream", {})
self.assertEqual(append_request.get("channel"), "C0123456789")
Expand Down