diff --git a/docs/english/concepts/adding-agent-features.md b/docs/english/concepts/adding-agent-features.md index cbd164630..87a8d31cb 100644 --- a/docs/english/concepts/adding-agent-features.md +++ b/docs/english/concepts/adding-agent-features.md @@ -190,7 +190,7 @@ def handle_message( # Add eyes reaction only to the first message (DMs only — channel # threads already have the reaction from the initial app_mention) if is_dm and not existing_session_id: - await client.reactions_add( + client.reactions_add( channel=channel_id, timestamp=event["ts"], name="eyes", @@ -274,7 +274,7 @@ The `say_stream` utility streamlines calling the Python Slack SDK's [`WebClient. | `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 be `None`. +If either `channel_id` or `thread_ts` cannot be sourced, the utility will be `None`. ```python streamer = say_stream() @@ -571,7 +571,7 @@ def handle_app_mentioned( except Exception as e: logger.exception(f"Failed to handle app mention: {e}") - await say( + say( text=f":warning: Something went wrong! ({e})", thread_ts=event.get("thread_ts") or event["ts"], ) diff --git a/docs/english/concepts/message-sending.md b/docs/english/concepts/message-sending.md index 090503ff2..c4d1b0467 100644 --- a/docs/english/concepts/message-sending.md +++ b/docs/english/concepts/message-sending.md @@ -54,7 +54,7 @@ The `say_stream` utility streamlines calling the Python Slack SDK's [`WebClient. | `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 be `None`. +If either `channel_id` or `thread_ts` cannot be sourced, the utility will be `None`. For information on calling the `chat_*Stream` API methods directly, see the [_Sending streaming messages_](/tools/python-slack-sdk/web#sending-streaming-messages) section of the Python Slack SDK docs. @@ -79,7 +79,7 @@ def handle_app_mention(client: WebClient, say_stream: SayStream): def handle_message(client: WebClient, say_stream: SayStream): stream = say_stream() - stream.append(markdown_text="Let me consult my *vast knowledge database*...) + stream.append(markdown_text="Let me consult my *vast knowledge database*...") stream.stop() if __name__ == "__main__": diff --git a/docs/english/concepts/updating-pushing-views.md b/docs/english/concepts/updating-pushing-views.md index 8c05e79c8..ce285c814 100644 --- a/docs/english/concepts/updating-pushing-views.md +++ b/docs/english/concepts/updating-pushing-views.md @@ -1,6 +1,6 @@ # Updating & pushing views -Modals contain a stack of views. When you call [`views_open`](https://api./reference/methods/views.open/slack.com/methods/views.open), you add the root view to the modal. After the initial call, you can dynamically update a view by calling [`views_update`](/reference/methods/views.update/), or stack a new view on top of the root view by calling [`views_push`](/reference/methods/views.push/) +Modals contain a stack of views. When you call [`views_open`](/reference/methods/views.open/), you add the root view to the modal. After the initial call, you can dynamically update a view by calling [`views_update`](/reference/methods/views.update/), or stack a new view on top of the root view by calling [`views_push`](/reference/methods/views.push/) ## The `views_update` method diff --git a/docs/english/concepts/using-the-assistant-class.md b/docs/english/concepts/using-the-assistant-class.md index ed004dc35..40c97d0cd 100644 --- a/docs/english/concepts/using-the-assistant-class.md +++ b/docs/english/concepts/using-the-assistant-class.md @@ -51,7 +51,7 @@ You _could_ go it alone and [listen](/tools/bolt-python/concepts/event-listening While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextStore` property — but it also provides a `DefaultThreadContextStore` instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](/messaging/message-metadata/) as the user interacts with the app. -If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods. +If you do provide your own `threadContextStore` property, it must feature `find` and `save` methods. :::tip[Refer to the [reference docs](https://docs.slack.dev/tools/bolt-python/reference/kwargs_injection/args.html) to learn the available listener arguments.] ::: @@ -138,10 +138,10 @@ Messages sent to the app do not contain a [subtype](/reference/events/message#su There are three utilities that are particularly useful in curating the user experience: * [`say`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.Say) -* [`setTitle`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetTitle) -* [`setStatus`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetStatus) +* [`set_title`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetTitle) +* [`set_status`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetStatus) -Within the `setStatus` utility, you can cycle through strings passed into a `loading_messages` array. +Within the `set_status` utility, you can cycle through strings passed into a `loading_messages` list. ```python # This listener is invoked when the human user sends a reply in the assistant thread diff --git a/docs/english/concepts/view-submissions.md b/docs/english/concepts/view-submissions.md index 4ff4c2da7..b961e0376 100644 --- a/docs/english/concepts/view-submissions.md +++ b/docs/english/concepts/view-submissions.md @@ -90,6 +90,6 @@ def handle_submission(ack, body, client, view, logger): # Message the user try: client.chat_postMessage(channel=user, text=msg) - except e: + except Exception as e: logger.exception(f"Failed to post a message {e}") ``` diff --git a/docs/english/experiments.md b/docs/english/experiments.md index 13adf0a32..443a334be 100644 --- a/docs/english/experiments.md +++ b/docs/english/experiments.md @@ -1,30 +1,11 @@ # Experiments -Bolt for Python includes experimental features still under active development. These features may be fleeting, may not be perfectly polished, and should be thought of as available for use "at your own risk." +Bolt for Python occasionally includes experimental features still under active development. These features may be fleeting, may not be perfectly polished, and should be thought of as available for use "at your own risk." Experimental features are categorized as `semver:patch` until the experimental status is removed. We love feedback from our community, so we encourage you to explore and interact with the [GitHub repo](https://github.com/slackapi/bolt-python). Contributions, bug reports, and any feedback are all helpful; let us nurture the Slack CLI together to help make building Slack apps more pleasant for everyone. ## Available experiments -* [Agent listener argument](#agent) -## Agent listener argument {#agent} - -The `agent: BoltAgent` listener argument provides access to AI agent-related features. - -The `BoltAgent` and `AsyncBoltAgent` classes offer a `chat_stream()` method that comes pre-configured with event context defaults: `channel_id`, `thread_ts`, `team_id`, and `user_id` fields. - -The listener argument is wired into the Bolt `kwargs` injection system, so listeners can declare it as a parameter or access it via the `context.agent` property. - -### Example - -```python -from slack_bolt import BoltAgent - -@app.event("app_mention") -def handle_mention(agent: BoltAgent): - stream = agent.chat_stream() - stream.append(markdown_text="Hello!") - stream.stop() -``` +There are currently no active experiments. We're steadily staying stable. diff --git a/docs/english/tutorial/custom-steps-workflow-builder-existing/custom-steps-workflow-builder-existing.md b/docs/english/tutorial/custom-steps-workflow-builder-existing/custom-steps-workflow-builder-existing.md index c3c5e2af7..9a5e3ee50 100644 --- a/docs/english/tutorial/custom-steps-workflow-builder-existing/custom-steps-workflow-builder-existing.md +++ b/docs/english/tutorial/custom-steps-workflow-builder-existing/custom-steps-workflow-builder-existing.md @@ -14,7 +14,7 @@ In this tutorial we will: ## Prerequisites {#prereqs} -The custom steps feature is compatible with Bolt version 1.20.0 and above. First, update your `package.json` file to reflect version 1.20.0 of Bolt, then run the following command in your terminal: +The custom steps feature is compatible with Bolt version 1.20.0 and above. First, update your `requirements.txt` file to reflect version 1.20.0 of Bolt (e.g., `slack-bolt>=1.20.0`), then run the following commands in your terminal: ```sh python3 -m venv .venv @@ -215,9 +215,8 @@ def manager_resp_handler(ack: Ack, action, body: dict, client: WebClient, comple client.chat_update( channel=body['channel']['id'], - message=body['message'], ts=body["message"]["ts"], - text=f'Request {"approved" if request_decision == 'approve' else "denied"}!' + text=f"Request {'approved' if request_decision == 'approve' else 'denied'}!" ) complete({ diff --git a/docs/english/tutorial/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md b/docs/english/tutorial/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md index 1dceed45a..75be7aa32 100644 --- a/docs/english/tutorial/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md +++ b/docs/english/tutorial/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md @@ -47,7 +47,9 @@ You can also open a terminal window from inside VSCode like this: `Ctrl` + `~` Once in VSCode, open the terminal. Let's install our package dependencies: run the following command(s) in the terminal inside VSCode: ```sh -npm install +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt ``` We now have a Bolt app ready for development! Open the `manifest.json` file and copy its contents; you'll need this in the next step. @@ -99,7 +101,7 @@ You will then have a bot token. Again, copy that value and save it somewhere acc ## Starting your local development server {#local} -While building your app, you can see your changes appear in your workspace in real-time with `npm start`. Soon we'll start our local development server and see what our sample code is all about! But first, we need to store those tokens we gathered as environment variables. +While building your app, you can see your changes appear in your workspace in real-time with `python app.py`. Soon we'll start our local development server and see what our sample code is all about! But first, we need to store those tokens we gathered as environment variables. Navigate back to VSCode. Rename the `.env.sample` file to `.env`. Open this file and update `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` with the values you previously saved. It will look like this, with your actual token values where you see `` and ``: @@ -111,7 +113,7 @@ SLACK_BOT_TOKEN= Now save the file and try starting your app: ```sh -npm start +python app.py ``` You'll know the local development server is up and running successfully when it emits a bunch of `[DEBUG]` statements to your terminal, the last one containing `connected:ready`. diff --git a/docs/english/tutorial/custom-steps.md b/docs/english/tutorial/custom-steps.md index 66dc16198..50bd723ce 100644 --- a/docs/english/tutorial/custom-steps.md +++ b/docs/english/tutorial/custom-steps.md @@ -111,9 +111,9 @@ Here is a sample app manifest laying out a step definition. This definition tell "name": "user_id" } }, - "required": { + "required": [ "user_id" - } + ] }, "output_parameters": { "properties": { @@ -124,9 +124,9 @@ Here is a sample app manifest laying out a step definition. This definition tell "name": "user_id" } }, - "required": { + "required": [ "user_id" - } + ] }, } } @@ -157,7 +157,7 @@ Notice in the example code here that the name of the step, `sample_step`, is the ```py @app.function("sample_step") -def handle_sample_step_event(inputs: dict, fail: Fail, complete: Complete,logger: logging.Logger): +def handle_sample_step_event(client: WebClient, inputs: dict, fail: Fail, complete: Complete, logger: logging.Logger): user_id = inputs["user_id"] try: client.chat_postMessage( @@ -226,7 +226,7 @@ The second argument is the callback function, or the logic that will run when yo Field | Description ------|------------ `client` | A `WebClient` instance used to make things happen in Slack. From sending messages to opening modals, `client` makes it all happen. For a full list of available methods, refer to the [Web API methods](/reference/methods). Read more about the `WebClient` for Bolt Python [here](https://docs.slack.dev/tools/bolt-python/concepts/web-api/). -`complete` | A utility method that invokes `functions.completeSuccess`. This method indicates to Slack that a step has completed successfully without issue. When called, `complete` requires you include an `outputs` object that matches your step definition in [`output_parameters`](#inputs-outputs). +`complete` | A utility method that invokes `functions.completeSuccess`. This method indicates to Slack that a step has completed successfully without issue. When called, `complete` accepts an optional `outputs` object that matches your step definition in [`output_parameters`](#inputs-outputs). `fail` | A utility method that invokes `functions.completeError`. True to its name, this method signals to Slack that a step has failed to complete. The `fail` method requires an argument of `error` to be sent along with it, which is used to help users understand what went wrong. `inputs` | An alias for the `input_parameters` that were provided to the step upon execution.