From 6484e0002e852d31838a8e8cdfb5a8074936e084 Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Fri, 29 May 2026 09:00:39 -0700 Subject: [PATCH 1/2] critical fixes --- .github/maintainers_guide.md | 2 +- docs/english/audit-logs.md | 2 +- docs/english/oauth.md | 3 +-- docs/english/rtm.md | 4 ++-- docs/english/scim.md | 4 ++-- docs/english/socket-mode.md | 2 +- docs/english/tutorial/uploading-files.md | 2 +- docs/english/v3-migration.md | 2 +- docs/english/web.md | 11 ++++------- docs/english/webhook.md | 4 ++-- 10 files changed, 16 insertions(+), 20 deletions(-) diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md index 27927530d..90246af4c 100644 --- a/.github/maintainers_guide.md +++ b/.github/maintainers_guide.md @@ -19,7 +19,7 @@ You can hook `pyenv` into your shell automatically by running `pyenv init` and f Install necessary Python runtimes for development/testing. It is not necessary to install all the various Python versions we test in [continuous integration on -GitHub Actions](https://github.com/slackapi/python-slack-sdk/blob/main/.github/workflows/tests.yml), +GitHub Actions](https://github.com/slackapi/python-slack-sdk/blob/main/.github/workflows/ci-build.yml), but make sure you are running at least one version that we execute our tests in locally so that you can run the tests yourself. diff --git a/docs/english/audit-logs.md b/docs/english/audit-logs.md index 1d8b930ce..23b9b9576 100644 --- a/docs/english/audit-logs.md +++ b/docs/english/audit-logs.md @@ -36,7 +36,7 @@ api_response = client.actions() ## AsyncAuditLogsClient {#asyncauditlogsclient} -If you are keen to use asyncio for SCIM API calls, we offer AsyncSCIMClient for it. This client relies on aiohttp library. +If you are keen to use asyncio for Audit Logs API calls, we offer AsyncAuditLogsClient for it. This client relies on aiohttp library. ``` python from slack_sdk.audit_logs.async_client import AsyncAuditLogsClient diff --git a/docs/english/oauth.md b/docs/english/oauth.md index 61b9af98f..0e961eace 100644 --- a/docs/english/oauth.md +++ b/docs/english/oauth.md @@ -76,9 +76,8 @@ def oauth_callback(): client = WebClient() # no prepared token needed for this # Complete the installation by calling oauth.v2.access API method oauth_response = client.oauth_v2_access( - client_id=client_id, + client_id=os.environ["SLACK_CLIENT_ID"], client_secret=client_secret, - redirect_uri=redirect_uri, code=request.args["code"] ) installed_enterprise = oauth_response.get("enterprise") or {} diff --git a/docs/english/rtm.md b/docs/english/rtm.md index d609aab04..cec9a6032 100644 --- a/docs/english/rtm.md +++ b/docs/english/rtm.md @@ -4,7 +4,7 @@ The [Legacy Real Time Messaging (RTM) API](/legacy/legacy-rtm-api) is a WebSocke If you prefer events to be pushed to your app, we recommend using the HTTP-based [Events API](/apis/events-api) instead. The Events API contains some events that aren't supported in the Legacy RTM API (such as the [app_home_opened event](/reference/events/app_home_opened)), and it supports most of the event types in the Legacy RTM API. If you'd like to use the Events API, you can use the [Python Slack Events Adaptor](https://github.com/slackapi/python-slack-events-api). -The RTMClient allows apps to communicate with the Legacy RTM API. +The `RTMClient` allows apps to communicate with the Legacy RTM API. The event-driven architecture of this client allows you to simply link callbacks to their corresponding events. When an event occurs, this client executes your callback while passing along any information it receives. We also give you the ability to call our web client from inside your callbacks. @@ -75,7 +75,7 @@ rtm_client.start() By default, the RTM client uses the [`rtm.connect`](/reference/methods/rtm.connect) API method to establish a WebSocket connection with Slack. The response contains basic information about the team and WebSocket URL. -See the [`rtm.connect`](/reference/methods/rtm.connect) and [`rtm.start`](/reference/methods/rtm.start) API methods for more details. Note that `slack.rtm_v2.RTMClient` does not support `rtm.start`. +See the [`rtm.connect`](/reference/methods/rtm.connect) and [`rtm.start`](/reference/methods/rtm.start) API methods for more details. Note that `slack_sdk.rtm_v2.RTMClient` does not support `rtm.start`. ## RTM events {#rtm-events} diff --git a/docs/english/scim.md b/docs/english/scim.md index 78f696056..2839ec86f 100644 --- a/docs/english/scim.md +++ b/docs/english/scim.md @@ -6,7 +6,7 @@ Refer to [using the Slack SCIM API](/admins/scim-api) for more details. View the [Python document for this module](https://docs.slack.dev/tools/python-slack-sdk/reference). -## SCIMClient {#scimclient} +## `SCIMClient` {#scimclient} An OAuth token with [the admin scope](/reference/scopes/admin) is required to access the SCIM API. To fetch provisioned user data, you can use the `search_users` method in the client. @@ -19,7 +19,7 @@ client = SCIMClient(token=os.environ["SLACK_ORG_ADMIN_USER_TOKEN"]) response = client.search_users( start_index=1, count=100, - filter="""filter=userName Eq "Carly"""", + filter='userName Eq "Carly"', ) response.users # List[User] ``` diff --git a/docs/english/socket-mode.md b/docs/english/socket-mode.md index a1bf9984e..b9b58a4c8 100644 --- a/docs/english/socket-mode.md +++ b/docs/english/socket-mode.md @@ -118,7 +118,7 @@ This SDK offers its own WebSocket client covering only required features for Soc To use the [`websocket_client`](https://pypi.org/project/websocket_client/) based-one, add the[`websocket_client`](https://pypi.org/project/websocket_client/) dependency and change the import as below. ``` python -# Note that the pockage is different +# Note that the package is different from slack_sdk.socket_mode.websocket_client import SocketModeClient client = SocketModeClient( diff --git a/docs/english/tutorial/uploading-files.md b/docs/english/tutorial/uploading-files.md index a9a624758..927ae23a1 100644 --- a/docs/english/tutorial/uploading-files.md +++ b/docs/english/tutorial/uploading-files.md @@ -115,7 +115,7 @@ At this point, while no files have been uploaded yet, you can call the `files.li ```python >>> files = client.files_list(user=bot_user_id) -DEBUG:slack_sdk.web.base_client:Sending a request - url: https://www.slack.com/api/files.list, query_params: {}, body_params: {'user': 'U02PY3HA48G'}, files: {}, json_body: None, headers: {} +DEBUG:slack_sdk.web.base_client:Sending a request - url: https://slack.com/api/files.list, query_params: {}, body_params: {'user': 'U02PY3HA48G'}, files: {}, json_body: None, headers: {} DEBUG:slack_sdk.web.base_client:Received the following response - status: 200, headers: {}, body: {"ok":true,"files":[],"paging":{"count":100,"total":0,"page":1,"pages":0}} ``` diff --git a/docs/english/v3-migration.md b/docs/english/v3-migration.md index d599ac28a..2ab860e9b 100644 --- a/docs/english/v3-migration.md +++ b/docs/english/v3-migration.md @@ -35,7 +35,7 @@ The biggest reason for the renaming is the feature coverage in v3 and newer. The Most imports can be simply replaced by `find your_app -name '*.py' | xargs sed -i '' 's/from slack /from slack_sdk /g'` or similar. If you use `slack.web.classes.*`, the conversion is not so simple that we recommend manually replacing imports for those. -That said, all existing code can be migrated to v3 without any code changes. If you don't have time for it, you can use the `slack` package with deprecation warnings saying `UserWarning: slack package is deprecated. Please use slack_sdk.web/webhook/rtm package instead. For more info, go to https://tools slack.dev/python-slack-sdk/v3-migration/` for a while. +That said, all existing code can be migrated to v3 without any code changes. If you don't have time for it, you can use the `slack` package with deprecation warnings saying `UserWarning: slack package is deprecated. Please use slack_sdk.web/webhook/rtm package instead. For more info, go to https://docs.slack.dev/tools/python-slack-sdk/v3-migration/` for a while. ------------------------------------------------------------------------ diff --git a/docs/english/web.md b/docs/english/web.md index 315d9e4c2..9f325426b 100644 --- a/docs/english/web.md +++ b/docs/english/web.md @@ -446,7 +446,7 @@ def slack_app(): if "payload" in request.form: payload = json.loads(request.form["payload"]) - if payload["type"] == "shortcut" and payload["callback_id"] == "test-shortcut": + if payload["type"] == "shortcut" and payload["callback_id"] == "open-modal-shortcut": # Open a new modal by a global shortcut try: api_response = client.views_open( @@ -506,10 +506,7 @@ if __name__ == "__main__": See the [`views.open`](/reference/methods/views.open) API method more details and additional parameters. -Also, to run the above example, the following [Slack app -configurations](https://api.slack.com/apps) are required. - -To run the above example, the following [app configurations](https://api.slack.com/apps) are required: +To run the above example, the following [Slack app configurations](https://api.slack.com/apps) are required: * Enable **Interactivity** with a valid Request URL: `https://{your-public-domain}/slack/events` * Add a global shortcut with the callback ID: `open-modal-shortcut` @@ -683,7 +680,7 @@ assert response["message"]["text"] == "Hello world!" ## AsyncWebClient {#asyncwebclient} -The webhook client is available in asynchronous programming using the standard [asyncio](https://docs.python.org/3/library/asyncio.html) library. You use `AsyncWebhookClient` instead. `AsyncWebhookClient` internally relies on the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library, but it is an optional dependency. To use this class, run `pip install aiohttp` beforehand. +The Web API client is available in asynchronous programming using the standard [asyncio](https://docs.python.org/3/library/asyncio.html) library. You use `AsyncWebClient` instead. `AsyncWebClient` internally relies on the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library, but it is an optional dependency. To use this class, run `pip install aiohttp` beforehand. ``` python import asyncio @@ -732,7 +729,7 @@ rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1) client.retry_handlers.append(rate_limit_handler) ``` -You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_retry`). Check out the source code for the ones that are built in to learn how to properly implement them. +You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry.RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_attempt`). Check out the source code for the ones that are built in to learn how to properly implement them. ``` python import socket diff --git a/docs/english/webhook.md b/docs/english/webhook.md index feaa4c7a9..c9850d506 100644 --- a/docs/english/webhook.md +++ b/docs/english/webhook.md @@ -113,10 +113,10 @@ from slack_sdk.http_retry.builtin_handlers import RateLimitErrorRetryHandler rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1) # Enable rate limited error retries as well -client.retry_handlers.append(rate_limit_handler) +webhook.retry_handlers.append(rate_limit_handler) ``` -You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_retry`). Check out the source code for the ones that are built in to learn how to properly implement them. +You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry.RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_attempt`). Check out the source code for the ones that are built in to learn how to properly implement them. ``` python import socket From c2217d473555cc73fcea300b881bfa36bad8b13d Mon Sep 17 00:00:00 2001 From: Luke Russell Date: Fri, 29 May 2026 09:13:19 -0700 Subject: [PATCH 2/2] more review and conversion --- docs/english/audit-logs.md | 12 ++-- docs/english/index.md | 6 +- docs/english/installation.md | 12 ++-- docs/english/legacy/auth.md | 10 ++-- docs/english/legacy/basic_usage.md | 34 +++++------ docs/english/legacy/conversations.md | 12 ++-- docs/english/legacy/index.md | 4 +- docs/english/legacy/real_time_messaging.md | 10 ++-- docs/english/oauth.md | 16 ++--- docs/english/rtm.md | 12 ++-- docs/english/scim.md | 10 ++-- docs/english/socket-mode.md | 6 +- .../tutorial/understanding-oauth-scopes.md | 8 +-- docs/english/tutorial/uploading-files.md | 22 +++---- docs/english/v3-migration.md | 22 +++---- docs/english/web.md | 58 +++++++++---------- docs/english/webhook.md | 10 ++-- 17 files changed, 132 insertions(+), 132 deletions(-) diff --git a/docs/english/audit-logs.md b/docs/english/audit-logs.md index 23b9b9576..36762479c 100644 --- a/docs/english/audit-logs.md +++ b/docs/english/audit-logs.md @@ -8,7 +8,7 @@ You'll need a valid token in order to use the Audit Logs API. In addition, the S --- -## AuditLogsClient {#auditlogsclient} +## AuditLogsClient {/* #auditlogsclient */} An OAuth token with [the admin scope](/reference/scopes/admin) is required to access this API. @@ -34,9 +34,9 @@ api_response = client.schemas() api_response = client.actions() ``` -## AsyncAuditLogsClient {#asyncauditlogsclient} +## AsyncAuditLogsClient {/* #asyncauditlogsclient */} -If you are keen to use asyncio for Audit Logs API calls, we offer AsyncAuditLogsClient for it. This client relies on aiohttp library. +If you are keen to use asyncio for Audit Logs API calls, we offer AsyncAuditLogsClient for it. This client relies on the aiohttp library. ``` python from slack_sdk.audit_logs.async_client import AsyncAuditLogsClient @@ -48,7 +48,7 @@ api_response.typed_body # slack_sdk.audit_logs.v1.LogsResponse --- -## RetryHandler {#retryhandler} +## RetryHandler {/* #retryhandler */} With the default settings, only `ConnectionErrorRetryHandler` with its default configuration (=only one retry in the manner of [exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)) is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., connection reset by peer). @@ -67,7 +67,7 @@ rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1) client.retry_handlers.append(rate_limit_handler) ``` -You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_retry`). Check out the source code for the ones that are built in to learn how to properly implement them. +You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry.RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_attempt`). Check out the source code for the ones that are built in to learn how to properly implement them. ``` python import socket @@ -100,4 +100,4 @@ client = AuditLogsClient( ) ``` -For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those methods are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. +For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those modules are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. diff --git a/docs/english/index.md b/docs/english/index.md index 7fdbcd6e4..fce1205a6 100644 --- a/docs/english/index.md +++ b/docs/english/index.md @@ -4,7 +4,7 @@ The Slack Python SDK has corresponding packages for Slack APIs. They are small a The Slack platform offers several APIs to build apps. Each Slack API delivers part of the capabilities from the platform, so that you can pick just those that fit your needs. -## Features {#features} +## Features {/* #features */} | Feature | Use | Package | |---|---|---| @@ -20,7 +20,7 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa You can also view the [Python module documents](https://docs.slack.dev/tools/python-slack-sdk/reference)! -## Getting help {#getting-help} +## Getting help {/* #getting-help */} These docs have lots of information on the Python Slack SDK. There's also an in-depth Reference section. Please explore! @@ -29,7 +29,7 @@ If you get stuck, we're here to help. The following are the best ways to get ass * [Issue Tracker](http://github.com/slackapi/python-slack-sdk/issues) for questions, bug reports, feature requests, and general discussion related to the Python Slack SDK. Try searching for an existing issue before creating a new one. * [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. -## Contributing {#contributing} +## Contributing {/* #contributing */} These docs live within the [Python Slack SDK](https://github.com/slackapi/python-slack-sdk) repository and are open source. diff --git a/docs/english/installation.md b/docs/english/installation.md index 17bae95d2..cb3bc7780 100644 --- a/docs/english/installation.md +++ b/docs/english/installation.md @@ -39,7 +39,7 @@ python test.py It's also good to try on the Python REPL. -## Access tokens {#handling-tokens} +## Access tokens {/* #handling-tokens */} Making calls to the Slack API often requires a [token](/authentication/tokens) with associated scopes that grant access to resources. Collecting a token can be done from app settings or with an OAuth installation depending on your app's requirements. @@ -71,13 +71,13 @@ SLACK_BOT_TOKEN = os.environ["SLACK_BOT_TOKEN"] Refer to our [best practices for security](/security) page for more information. -## Installing on a single workspace {#single-workspace} +## Installing on a single workspace {/* #single-workspace */} If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow. Once you've set up your features, click the **Install App to Team** button on the **Install App** page. If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for the changes to take effect. Refer to the [Slack quickstart](/quickstart) guide for more details. -## Installing on multiple workspaces {#multi-workspace} +## Installing on multiple workspaces {/* #multi-workspace */} If you intend for an app to be installed on multiple Slack workspaces, you will need to handle this installation via the industry-standard OAuth protocol. Read more about [installing with OAuth](/authentication/installing-with-oauth). @@ -97,7 +97,7 @@ oauth_scope = os.environ["SLACK_SCOPES"] app = Flask(__name__) ``` -### The OAuth initiation link {#oauth-link} +### The OAuth initiation link {/* #oauth-link */} To begin the OAuth flow that will install your app on a workspace, you'll need to provide the user with a link to the Slack OAuth page. This can be a simple link to `https://slack.com/oauth/v2/authorize` with the `scope` and `client_id` query parameters. @@ -113,7 +113,7 @@ def pre_install(): 'Add to Slack' ``` -### The OAuth completion page {#oauth-completion} +### The OAuth completion page {/* #oauth-completion */} Once the user has agreed to the permissions you've requested, Slack will redirect the user to your auth completion page, which includes a `code` query string parameter. You'll use the `code` parameter to call the [`oauth.v2.access`](/reference/methods/oauth.v2.access) API method that will grant you the token. @@ -172,7 +172,7 @@ Once your user has completed the OAuth flow, you'll be able to use the provided Refer to the [basic usage](/tools/python-slack-sdk/legacy/basic_usage) page for more examples. -## Installation troubleshooting {#troubleshooting} +## Installation troubleshooting {/* #troubleshooting */} We recommend using [virtualenv (venv)](https://docs.python.org/3/tutorial/venv.html) to set up your Python runtime. diff --git a/docs/english/legacy/auth.md b/docs/english/legacy/auth.md index 23fe0aa23..0b5d7b6b6 100644 --- a/docs/english/legacy/auth.md +++ b/docs/english/legacy/auth.md @@ -6,7 +6,7 @@ The v3 SDK provides additional features such as Socket Mode, OAuth flow, SCIM AP ::: -## Access tokens {#handling-tokens} +## Access tokens {/* #handling-tokens */} **Always keep your access tokens safe.** @@ -33,13 +33,13 @@ SLACK_BOT_TOKEN = os.environ["SLACK_BOT_TOKEN"] Refer to our [best practices for security](/security) page for more information. -## Installing on a single workspace {#single-workspace} +## Installing on a single workspace {/* #single-workspace */} If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow. Once you've set up your features, click the **Install App to Team** button on the **Install App** page. If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for the changes to take effect. Refer to the [quickstart](/quickstart) guide for more details. -## Installing on multiple workspaces {#multi-workspace} +## Installing on multiple workspaces {/* #multi-workspace */} If you intend for an app to be installed on multiple Slack workspaces, you will need to handle this installation via the industry-standard OAuth protocol. Read more about [installing with OAuth](/authentication/installing-with-oauth). @@ -59,7 +59,7 @@ oauth_scope = os.environ["SLACK_SCOPES"] app = Flask(__name__) ``` -### The OAuth initiation link {#oauth-link} +### The OAuth initiation link {/* #oauth-link */} To begin the OAuth flow that will install your app on a workspace, you'll need to provide the user with a link to the Slack OAuth page. This can be a simple link to `https://slack.com/oauth/v2/authorize` with the `scope` and `client_id` query parameters. @@ -75,7 +75,7 @@ def pre_install(): 'Add to Slack' ``` -### The OAuth completion page {#oauth-completion} +### The OAuth completion page {/* #oauth-completion */} Once the user has agreed to the permissions you've requested, Slack will redirect the user to your auth completion page, which includes a `code` query string parameter. You'll use the `code` parameter to call the [`oauth.v2.access`](/reference/methods/oauth.v2.access) API method that will grant you the token. diff --git a/docs/english/legacy/basic_usage.md b/docs/english/legacy/basic_usage.md index 75094dd9f..cee89cde5 100644 --- a/docs/english/legacy/basic_usage.md +++ b/docs/english/legacy/basic_usage.md @@ -12,7 +12,7 @@ Accessing Slack API methods requires an OAuth token — read more about [install Each of these [API methods](/reference/methods) is fully documented on our developer site at [docs.slack.dev](/). -## Sending a message {#sending-messages} +## Sending a message {/* #sending-messages */} One of the primary uses of Slack is posting messages to a channel using the channel ID, or as a DM to another person using their user ID. This method will handle either a channel ID or a user ID passed to the `channel` parameter. @@ -55,7 +55,7 @@ response = client.chat_postEphemeral( See the [`chat.postEphemeral`](/reference/methods/chat.postEphemeral) API method for more details. -## Formatting messages with Block Kit {#block-kit} +## Formatting messages with Block Kit {/* #block-kit */} Messages posted from apps can contain more than just text; they can also include full user interfaces composed of blocks using [Block Kit](/block-kit). @@ -104,7 +104,7 @@ client.chat_postMessage( ::: -## Threading messages {#threading-messages} +## Threading messages {/* #threading-messages */} Threaded messages are a way of grouping messages together to provide greater context. You can reply to a thread or start a new threaded conversation by simply passing the original message's `ts` ID in the `thread_ts` attribute when posting a message. If you're replying to a threaded message, you'll pass the `thread_ts` ID of the message you're replying to. @@ -137,7 +137,7 @@ When appearing in the channel, it won't contain any attachments or message butto Refer to the [threading messages](/messaging#threading) page for more information. -## Updating a message {#updating-messages} +## Updating a message {/* #updating-messages */} Let's say you have a bot that posts the status of a request. When that request changes, you'll want to update the message to reflect it's state. @@ -151,7 +151,7 @@ response = client.chat_update( See the [`chat.update`](/reference/methods/chat.update) API method for formatting options and some special considerations when calling this with a bot user. -## Deleting a message {#deleting-messages} +## Deleting a message {/* #deleting-messages */} Sometimes you need to delete things. @@ -165,7 +165,7 @@ response = client.chat_delete( See the [`chat.delete`](/reference/methods/chat.delete) API method for more details. -## Opening a modal {#opening-modals} +## Opening a modal {/* #opening-modals */} Modals allow you to collect data from users and display dynamic information in a focused surface. Modals use the same blocks that compose messages, with the addition of an `input` block. @@ -244,14 +244,14 @@ if __name__ == "__main__": app.run("localhost", 3000) ``` -See the [`views.open`](/reference/methods/views.open) API method more details and additional parameters. +See the [`views.open`](/reference/methods/views.open) API method for more details and additional parameters. To run the above example, the following [app configurations](https://api.slack.com/apps) are required: * Enable **Interactivity** with a valid Request URL: `https://{your-public-domain}/slack/events` * Add a global shortcut with the callback ID: `open-modal-shortcut` -## Updating and pushing modals {#updating-pushing-modals} +## Updating and pushing modals {/* #updating-pushing-modals */} You can dynamically update a view inside of a modal by calling the `views.update` API method and passing the view ID returned in the previous `views.open` API method call. @@ -298,7 +298,7 @@ See the [`views.update`](/reference/methods/views.update) API method for more de If you want to push a new view onto the modal instead of updating an existing view, see the [`views.push`](/reference/methods/views.push) API method. -## Emoji reactions {#emoji} +## Emoji reactions {/* #emoji */} You can quickly respond to any message on Slack with an emoji reaction. Reactions can be used for any purpose: voting, checking off to-do items, showing excitement, or just for fun. @@ -324,7 +324,7 @@ response = client.reactions_remove( See the [`reactions.add`](/reference/methods/reactions.add) and [`reactions.remove`](/reference/methods/reactions.remove) API methods for more details. -## Listing public channels {#listing-public-channels} +## Listing public channels {/* #listing-public-channels */} At some point, you'll want to find out what channels are available to your app. This is how you get that list. @@ -340,7 +340,7 @@ response = client.conversations_list(exclude_archived=1) See the [`conversations.list`](/reference/methods/conversations.list) API method for more details. -## Getting a channel's info {#get-channel-info} +## Getting a channel's info {/* #get-channel-info */} Once you have the ID for a specific channel, you can fetch information about that channel. @@ -350,7 +350,7 @@ response = client.conversations_info(channel="C0XXXXXXX") See the [`conversations.info`](/reference/methods/conversations.info) API method for more details. -## Joining a channel {#join-channel} +## Joining a channel {/* #join-channel */} Channels are the social hub of most Slack teams. Here's how you hop into one: @@ -364,7 +364,7 @@ See the [`conversations.join`](/reference/methods/conversations.join) API method ------------------------------------------------------------------------ -## Leaving a channel {#leave-channel} +## Leaving a channel {/* #leave-channel */} Maybe you've finished up all the business you had in a channel, or maybe you joined one by accident. This is how you leave a channel. @@ -374,7 +374,7 @@ response = client.conversations_leave(channel="C0XXXXXXX") See the [`conversations.leave`](/reference/methods/conversations.leave) API method for more details. -## Listing team members {#list-team-members} +## Listing team members {/* #list-team-members */} ``` python response = client.users_list() @@ -384,7 +384,7 @@ user_ids = list(map(lambda u: u["id"], users)) See the [`users.list`](/reference/methods/users.list) API method for more details. -## Uploading files {#uploading-files} +## Uploading files {/* #uploading-files */} ``` python response = client.files_upload_v2( @@ -396,7 +396,7 @@ response = client.files_upload_v2( See the [`files.upload`](/reference/methods/files.upload) API method for more details. -## Calling API methods {#calling-API-methods} +## Calling API methods {/* #calling-API-methods */} This library covers all the public endpoints as the methods in `WebClient`. That said, you may see a bit of a delay with the library release. When you're in a hurry, you can directly use the `api_call` method as below. @@ -412,7 +412,7 @@ response = client.api_call( assert response["message"]["text"] == "Hello world!" ``` -## Rate limits {#rate-limits} +## Rate limits {/* #rate-limits */} When posting messages to a channel, Slack allows apps to send no more than one message per channel per second. We allow bursts over that limit for short periods; however, if your app continues to exceed the limit over a longer period of time, it will be rate limited. Different API methods have other limits — be sure to check the [rate limits](/apis/web-api/rate-limits) and test that your app has a graceful fallback if it should hit those limits. diff --git a/docs/english/legacy/conversations.md b/docs/english/legacy/conversations.md index e617273ae..c271db47f 100644 --- a/docs/english/legacy/conversations.md +++ b/docs/english/legacy/conversations.md @@ -10,7 +10,7 @@ The Slack Conversations API provides your app with a unified interface to work w Refer to [using the Conversations API](/apis/web-api/using-the-conversations-api) for more information. -## Direct messages {#direct-messages} +## Direct messages {/* #direct-messages */} The `conversations.open` API method opens either a 1:1 direct message with a single user or a multi-person direct message, depending on the number of users supplied to the `users` parameter. (For public or private channels, use the `conversations.create` API method.) @@ -28,7 +28,7 @@ response = client.conversations_open(users=["W123456789", "U987654321"]) See the [`conversations.open`](/reference/methods/conversations.open) API method for additional details. -## Creating channels {#creating-channels} +## Creating channels {/* #creating-channels */} Creates a new channel, either public or private. The `name` parameter is required and may contain numbers, letters, hyphens, or underscores, and must contain fewer than 80 characters. To make the channel private, set the optional `is_private` parameter to `True`. @@ -49,7 +49,7 @@ response = client.conversations_archive(channel=channel_id) See the [`conversations.create`](/reference/methods/conversations.create) API method for additional details. -## Getting conversation information {#more-information} +## Getting conversation information {/* #more-information */} To retrieve a set of metadata about a channel (public, private, DM, or multi-party DM), use the `conversations.info` API method. The `channel` parameter is required and must be a valid channel ID. The optional `include_locale` boolean parameter will return locale data, which may be useful if you wish to return localized responses. The `include_num_members` boolean parameter will return the number of people in a channel. @@ -66,7 +66,7 @@ response = client.conversations_info( See the [`conversations.info`](/reference/methods/conversations.info) API method for more details. -## Listing conversations {#listing-conversations} +## Listing conversations {/* #listing-conversations */} To get a list of all the conversations in a workspace, use the `conversations.list` API method. By default, only public conversations are returned. Use the `types` parameter specify which types of conversations you're interested in. Note that `types` is a string of comma-separated values. @@ -93,7 +93,7 @@ response = client.conversations_list( See the [`conversations.list`](/reference/methods/conversations.list) API method for more details. -## Getting members of a conversation {#get-members} +## Getting members of a conversation {/* #get-members */} To get a list of members for a conversation, use the `conversations.members` API method with the required `channel` parameter. @@ -108,7 +108,7 @@ user_ids = response["members"] See the [`conversations.members`](/reference/methods/conversations.members) API method for more details. -## Leaving a conversation {#leave-conversations} +## Leaving a conversation {/* #leave-conversations */} To leave a conversation, use the `conversations.leave` API method with the required `channel` parameter containing the ID of the channel to leave. diff --git a/docs/english/legacy/index.md b/docs/english/legacy/index.md index e2ca20613..584dc5456 100644 --- a/docs/english/legacy/index.md +++ b/docs/english/legacy/index.md @@ -12,7 +12,7 @@ Slack APIs allow anyone to build full featured integrations that extend and expa To make it easier for Python programmers to build Slack applications, we've provided this open source SDK that will help you get started building Python apps as quickly as possible. The current version is built for Python 3.7 and higher. -## Slack platform basics {#platform-basics} +## Slack platform basics {/* #platform-basics */} If you're new to the Slack platform, we have a general purpose [quickstart guide](/quickstart) that isn't specific to any language or framework. Its a great place to learn all about the concepts that go into building a great Slack app. @@ -20,7 +20,7 @@ Before you get started building on the Slack platform, you need to set up [your The app configuration page is also where you'll acquire the OAuth token you'll use to call Slack API methods. Treat this token with care, just like you would a password, because it has access to your workspace and can potentially read and write data to and from it. -## Installation {#installation} +## Installation {/* #installation */} We recommend using [PyPI](https://pypi.python.org/pypi) to install as follows: diff --git a/docs/english/legacy/real_time_messaging.md b/docs/english/legacy/real_time_messaging.md index 3b16e3ecd..4208a4923 100644 --- a/docs/english/legacy/real_time_messaging.md +++ b/docs/english/legacy/real_time_messaging.md @@ -8,7 +8,7 @@ The v3 SDK provides additional features such as Socket Mode, OAuth flow, SCIM AP The [Legacy Real Time Messaging (RTM) API](/legacy/legacy-rtm-api) is a WebSocket-based API that allows you to receive events from Slack in real time and to send messages as users. -If you prefer events to be pushed to your app, we recommend using the HTTP-based [Events API](/apis/events-api) instead. The Events API contains some events that aren't supported in the Legacy RTM API (such as the [app_home_opened event](/reference/events/app_home_opened)), and it supports most of the event types in the Legacy RTM API. If you'd like to use the Events API, you can use the [Python Slack Events Adaptor](https://github.com/slackapi/python-slack-events-api). +If you prefer events to be pushed to your app, we recommend using the HTTP-based [Events API](/apis/events-api) instead. The Events API contains some events that aren't supported in the Legacy RTM API (such as the [app_home_opened event](/reference/events/app_home_opened)), and it supports most of the event types in the Legacy RTM API. If you'd like to use the Events API, you can use the [Python Slack Events Adapter](https://github.com/slackapi/python-slack-events-api). The RTMClient allows apps to communicate with the Legacy RTM API. @@ -16,13 +16,13 @@ The event-driven architecture of this client allows you to simply link callbacks In our example below, we watch for a [message event](/reference/events/message) that contains \"Hello\" and if it's received, we call the `say_hello()` function. We then issue a call to the web client to post back to the channel saying \"Hi\" to the user. -## Configuring the RTM API {#configuration} +## Configuring the RTM API {/* #configuration */} Events using the Legacy RTM API **must** use a Slack app with a plain `bot` scope. If you already have a Slack app with a plain `bot` scope, you can use those credentials. If you don't and need to use the Legacy RTM API, you can create a Slack app [here](https://api.slack.com/apps?new_classic_app=1). Even if the Slack app configuration pages encourage you to upgrade to a newer permission model, don't upgrade it and continue using the \"classic\" bot permission. -## Connecting to the RTM API {#connecting} +## Connecting to the RTM API {/* #connecting */} ``` python import os @@ -49,7 +49,7 @@ rtm_client = RTMClient(token=slack_token) rtm_client.start() ``` -## The `rtm.start` vs. `rtm.connect` API methods {#rtm-methods} +## The `rtm.start` vs. `rtm.connect` API methods {/* #rtm-methods */} By default, the RTM client uses the [`rtm.connect`](/reference/methods/rtm.connect) API method to establish a WebSocket connection with Slack. The response contains basic information about the team and WebSocket URL. @@ -84,7 +84,7 @@ rtm_client.start() See the [`rtm.connect`](/reference/methods/rtm.connect) and [`rtm.start`](/reference/methods/rtm.start) API methods for more details. -## RTM events {#rtm-events} +## RTM events {/* #rtm-events */} ``` javascript { diff --git a/docs/english/oauth.md b/docs/english/oauth.md index 0e961eace..f2b1c32b8 100644 --- a/docs/english/oauth.md +++ b/docs/english/oauth.md @@ -4,19 +4,19 @@ This page explains how to handle the Slack OAuth flow. If you're looking for a m Refer to the [Python document for this module](https://docs.slack.dev/tools/python-slack-sdk/reference) for more details. -## App installation flow {#app-installation} +## App installation flow {/* #app-installation */} OAuth allows a user in any Slack workspace to install your app. At the end of the OAuth flow, your app gains an access token. Refer to the [installing with OAuth](/authentication/installing-with-oauth) guide for details. The Python Slack SDK provides the necessary modules for building the OAuth flow. -### Starting an OAuth flow {#oauth-flow} +### Starting an OAuth flow {/* #oauth-flow */} The first step of the OAuth flow is to redirect a Slack user to [authorize](https://slack.com/oauth/v2/authorize) with a valid `state` parameter. To implement this process, you can use the following modules. -Module | What its for | Default Implementation +Module | What it's for | Default Implementation ----------------------|-----------------------------------------|------------------------- -`InstallationStore` | Persist installation data and lookup it by IDs. | `FileInstallationStore` +`InstallationStore` | Persist installation data and look it up by IDs. | `FileInstallationStore` `OAuthStateStore` | Issue and consume `state` parameter value on the server-side. | `FileOAuthStateStore` `AuthorizeUrlGenerator` | Build https://slack.com/oauth/v2/authorize with sufficient query parameters | (same) @@ -31,7 +31,7 @@ from slack_sdk.oauth.state_store import FileOAuthStateStore # Issue and consume state parameter value on the server-side. state_store = FileOAuthStateStore(expiration_seconds=300, base_dir="./data") -# Persist installation data and lookup it by IDs. +# Persist installation data and look it up by IDs. installation_store = FileInstallationStore(base_dir="./data") # Build https://slack.com/oauth/v2/authorize with sufficient query parameters @@ -56,7 +56,7 @@ def oauth_start(): When accessing `https://(your domain)/slack/install`, you will see an \"Add to Slack\" button on the page. You can start the app's installation flow by clicking the button. -### Handling a callback request from Slack {#handling-callback-requests} +### Handling a callback request from Slack {/* #handling-callback-requests */} If all is well, a user goes through the Slack app installation UI and accepts all the scopes your app requests. After that happens, Slack redirects the user back to your specified Redirect URL. @@ -128,7 +128,7 @@ def oauth_callback(): return make_response(f"Something is wrong with the installation (error: {html.escape(error)})", 400) ``` -## Token lookup {#token-lookup} +## Token lookup {/* #token-lookup */} Now that your Flask app can choose the right access token for incoming event requests, let's add the Slack event handler endpoint. You can use the same `InstallationStore` in the Slack event handler. @@ -219,7 +219,7 @@ def slack_app(): return make_response("", 404) ``` -## Sign in with Slack {#siws} +## Sign in with Slack {/* #siws */} [Sign in with Slack](/authentication/sign-in-with-slack) helps users log into your service using their Slack profile. The platform feature was upgraded to be compatible with the standard [OpenID Connect](https://openid.net/connect/) specification. With slack-sdk v3.9+, implementing the OAuth flow is much easier. diff --git a/docs/english/rtm.md b/docs/english/rtm.md index cec9a6032..eb8ea726e 100644 --- a/docs/english/rtm.md +++ b/docs/english/rtm.md @@ -2,7 +2,7 @@ The [Legacy Real Time Messaging (RTM) API](/legacy/legacy-rtm-api) is a WebSocket-based API that allows you to receive events from Slack in real time and to send messages as users. -If you prefer events to be pushed to your app, we recommend using the HTTP-based [Events API](/apis/events-api) instead. The Events API contains some events that aren't supported in the Legacy RTM API (such as the [app_home_opened event](/reference/events/app_home_opened)), and it supports most of the event types in the Legacy RTM API. If you'd like to use the Events API, you can use the [Python Slack Events Adaptor](https://github.com/slackapi/python-slack-events-api). +If you prefer events to be pushed to your app, we recommend using the HTTP-based [Events API](/apis/events-api) instead. The Events API contains some events that aren't supported in the Legacy RTM API (such as the [app_home_opened event](/reference/events/app_home_opened)), and it supports most of the event types in the Legacy RTM API. If you'd like to use the Events API, you can use the [Python Slack Events Adapter](https://github.com/slackapi/python-slack-events-api). The `RTMClient` allows apps to communicate with the Legacy RTM API. @@ -10,13 +10,13 @@ The event-driven architecture of this client allows you to simply link callbacks In our example below, we watch for a [message event](/reference/events/message) that contains \"Hello\" and if it's received, we call the `say_hello()` function. We then issue a call to the web client to post back to the channel saying \"Hi\" to the user. -## Configuring the RTM API {#configuration} +## Configuring the RTM API {/* #configuration */} Events using the Legacy RTM API **must** use a Slack app with a plain `bot` scope. If you already have a Slack app with a plain `bot` scope, you can use those credentials. If you don't and need to use the Legacy RTM API, you can create a Slack app [here](https://api.slack.com/apps?new_classic_app=1). Even if the Slack app configuration pages encourage you to upgrade to a newer permission model, don't upgrade it and continue using the \"classic\" bot permission. -## Connecting to the RTM API {#connecting} +## Connecting to the RTM API {/* #connecting */} Note that the import here is not `from slack_sdk.rtm import RTMClient` but `from slack_sdk.rtm_v2 import RTMClient` (`_v2` is added in the latter one). @@ -42,7 +42,7 @@ def handle(client: RTMClient, event: dict): rtm.start() ``` -## Connecting to the RTM API (v1 client) {#connecting-v1} +## Connecting to the RTM API (v1 client) {/* #connecting-v1 */} Below is a code snippet that uses the legacy version of `RTMClient`. For new app development, we **do not recommend** using it as it contains issues that have been resolved in v2. Please refer to the [list of these issues](https://github.com/slackapi/python-slack-sdk/issues?q=is%3Aissue+is%3Aclosed+milestone%3A3.3.0+label%3Artm-client) for more details. @@ -71,13 +71,13 @@ rtm_client = RTMClient(token=slack_token) rtm_client.start() ``` -## The `rtm.start` vs. `rtm.connect` API methods (v1 client) {#rtm-methods} +## The `rtm.start` vs. `rtm.connect` API methods (v1 client) {/* #rtm-methods */} By default, the RTM client uses the [`rtm.connect`](/reference/methods/rtm.connect) API method to establish a WebSocket connection with Slack. The response contains basic information about the team and WebSocket URL. See the [`rtm.connect`](/reference/methods/rtm.connect) and [`rtm.start`](/reference/methods/rtm.start) API methods for more details. Note that `slack_sdk.rtm_v2.RTMClient` does not support `rtm.start`. -## RTM events {#rtm-events} +## RTM events {/* #rtm-events */} ``` javascript { diff --git a/docs/english/scim.md b/docs/english/scim.md index 2839ec86f..f561c338d 100644 --- a/docs/english/scim.md +++ b/docs/english/scim.md @@ -6,7 +6,7 @@ Refer to [using the Slack SCIM API](/admins/scim-api) for more details. View the [Python document for this module](https://docs.slack.dev/tools/python-slack-sdk/reference). -## `SCIMClient` {#scimclient} +## `SCIMClient` {/* #scimclient */} An OAuth token with [the admin scope](/reference/scopes/admin) is required to access the SCIM API. To fetch provisioned user data, you can use the `search_users` method in the client. @@ -72,7 +72,7 @@ update_result = client.update_user(user=user_to_update) delete_result = client.delete_user(user_to_update.id) ``` -## AsyncSCIMClient {#asyncscimclient} +## AsyncSCIMClient {/* #asyncscimclient */} If you are keen to use asyncio for SCIM API calls, we offer `AsyncSCIMClient`. This client relies on the aiohttp library. @@ -92,7 +92,7 @@ asyncio.run(main()) ------------------------------------------------------------------------ -## RetryHandler {#retryhandler} +## RetryHandler {/* #retryhandler */} With the default settings, only `ConnectionErrorRetryHandler` with its default configuration (=only one retry in the manner of [exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)) is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., connection reset by peer). @@ -111,7 +111,7 @@ rate_limit_handler = RateLimitErrorRetryHandler(max_retry_count=1) client.retry_handlers.append(rate_limit_handler) ``` -You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_retry`). Check out the source code for the ones that are built in to learn how to properly implement them. +You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry.RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_attempt`). Check out the source code for the ones that are built in to learn how to properly implement them. ``` python import socket @@ -144,4 +144,4 @@ client = SCIMClient( ) ``` -For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those methods are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. +For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those modules are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. diff --git a/docs/english/socket-mode.md b/docs/english/socket-mode.md index b9b58a4c8..2b4c02a7c 100644 --- a/docs/english/socket-mode.md +++ b/docs/english/socket-mode.md @@ -2,7 +2,7 @@ Socket Mode is a method of connecting your app to the Slack APIs using WebSockets instead of HTTP. You can use `slack_sdk.socket_mode.SocketModeClient` for managing [Socket Mode](/apis/events-api/using-socket-mode) connections and performing interactions with Slack. -## Using Socket Mode {#socket-mode} +## Using Socket Mode {/* #socket-mode */} Let's start with enabling Socket Mode. Visit [app page](http://api.slack.com/apps), choose the app you're working on, and go to **Settings** on the left pane. There are a few things to do on this page. @@ -104,7 +104,7 @@ Event().wait() --- -## Supported libraries {#supported-libraries} +## Supported libraries {/* #supported-libraries */} This SDK offers its own WebSocket client covering only required features for Socket Mode. In addition, `SocketModeClient` is implemented with a few 3rd party open source libraries. If you prefer any of the following, you can use it over the built-in one. @@ -131,7 +131,7 @@ You can pass a few additional arguments that are specific to the library. Apart --- -## Asyncio-based libraries {#asyncio-libraries} +## Asyncio-based libraries {/* #asyncio-libraries */} To use the asyncio-based ones such as aiohttp, your app needs to be compatible with asyncio's async/await programming model. The `SocketModeClient` only works with `AsyncWebClient` and async listeners. diff --git a/docs/english/tutorial/understanding-oauth-scopes.md b/docs/english/tutorial/understanding-oauth-scopes.md index fc1c96f9f..cf28a20e2 100644 --- a/docs/english/tutorial/understanding-oauth-scopes.md +++ b/docs/english/tutorial/understanding-oauth-scopes.md @@ -5,13 +5,13 @@ In this tutorial, we'll: * explore Slack app permissions and distribution using OAuth, and along the way, learn how to identify which scopes apps need and how to use OAuth to request them. * build an app that sends a direct message to users joining a specific channel. Once installed in a workspace, it will create a new channel named **#the-welcome-channel** if it doesn’t already exist. The channel will be used to thank users for joining the channel. We'll also share code snippets from the app, but the full source code is available on [GitHub](https://github.com/stevengill/slack-python-oauth-example). The code and implementation of OAuth is general enough that you should be able to follow along, even if Python isn't your preferred language. -## Prerequisites {#prerequisites} +## Prerequisites {/* #prerequisites */} Before we get started, ensure you have a development workspace with permissions to install apps. If you don’t have one set up, go ahead and [create one](https://slack.com/create). You also need to [create a new app](https://api.slack.com/apps/new) if you haven’t already. Let’s get started! -## Determining scopes {#determine-scopes} +## Determining scopes {/* #determine-scopes */} Scopes are used to grant your app permission to perform functions in Slack, such as calling Web API methods and receiving Events API events. As a user goes through your app's installation flow, they'll need to permit access to the scopes your app is requesting. @@ -71,7 +71,7 @@ Our final list of scopes required are: * `channels:manage` * `chat:write` -## Setting up OAuth and requesting scopes {#setup} +## Setting up OAuth and requesting scopes {/* #setup */} If you want users to be able to install your app on additional workspaces or from the [Slack Marketplace](/slack-marketplace/slack-marketplace-review-guide), you'll need to implement an OAuth flow. @@ -155,7 +155,7 @@ We'll be following the general flow of OAuth with Slack, which is covered in the return "Auth complete!" ``` -## Next steps {#next} +## Next steps {/* #next */} At this point, you should feel more comfortable learning what scopes your app needs and using OAuth to request those scopes. A few resources you can check out next include: diff --git a/docs/english/tutorial/uploading-files.md b/docs/english/tutorial/uploading-files.md index 927ae23a1..85223f536 100644 --- a/docs/english/tutorial/uploading-files.md +++ b/docs/english/tutorial/uploading-files.md @@ -2,11 +2,11 @@ This tutorial details how to use the [`slack-sdk` package for Python](https://pypi.org/project/slack-sdk/) to upload files to a channel in Slack with some code samples. In addition to looking at how to upload files, we'll also cover listing and deleting files via the Web API using the Python SDK. -## Creating an app {#create-app} +## Creating an app {/* #create-app */} First, create a [Slack app](https://api.slack.com/apps/new). -## Configuring your app's settings with an app manifest {#configuration} +## Configuring your app's settings with an app manifest {/* #configuration */} Creating your app using this method will include all the required settings for this tutorial, and you won't be bogged down with too many details - all you'll need to do is decide where this app will live. If you're curious about the inner workings of how this button works, refer to [App Manifests](/app-manifests) for more information. @@ -30,7 +30,7 @@ oauth_config: - files:write ``` -## Installing your app in a workspace {#installing} +## Installing your app in a workspace {/* #installing */} Once you've created your app, you'll see an **Install to Workspace** button. Click it to install your app in your workspace. @@ -52,9 +52,9 @@ export SLACK_BOT_TOKEN= With this, all your Slack app configuration is done. Let's start coding. -## Using Python to upload a file {#upload-file-with-python} +## Using Python to upload a file {/* #upload-file-with-python */} -### Creating a new project {#create-new-project} +### Creating a new project {/* #create-new-project */} First, ensure you're using Python version 3.7 or above. While the current standard is for the `python3` and `pip3` commands to use Python 3.7 or above, it's best to ensure your runtime is always using the latest version of Python. [pyenv](https://github.com/pyenv/pyenv) is a handy tool that can do this for you. @@ -68,7 +68,7 @@ pip install -U pip pip install -r requirements.txt ``` -### Uploading a file {#upload-file} +### Uploading a file {/* #upload-file */} While it's possible to enter the following into the Python shell, we've gathered some code samples and wrote it in script form. @@ -154,7 +154,7 @@ DEBUG:slack_sdk.web.base_client:Received the following response - status: 200, h Back in Slack, you'll notice that nothing has happened. How curious... -### Sharing a file within a channel {#sharing} +### Sharing a file within a channel {/* #sharing */} At this point, we have indeed uploaded a file to Slack, but only the bot user is able to view it. @@ -180,7 +180,7 @@ By doing this, you'll be able to see the file within Slack. ![Upload file](upload-files-first-upload.png) -### Specifying a channel when uploading a file {#specifying-channel} +### Specifying a channel when uploading a file {/* #specifying-channel */} While this exercise was very informative, having to do these two steps every time we upload a file is a bit cumbersome. Instead, we can specify the `channel` parameter to the function. This is the more common way of uploading a file from an app. @@ -198,7 +198,7 @@ By running the above code, you'll share the same file without having to send a m ![Share file with message](upload-files-with-channel.png) -### Uploading local files {#upload-local-files} +### Uploading local files {/* #upload-local-files */} If you have an image file lying around, feel free to use that but for simplicity's sake. We'll continue using a text file here. You can create a local file by using the following command: @@ -221,7 +221,7 @@ Again, we'll see that the file has been uploaded to Slack and shared within the ![File uploaded](upload-files-local-file.png) -## Deleting a file {#deleting} +## Deleting a file {/* #deleting */} Next, we'll cover how to delete a file. @@ -254,7 +254,7 @@ Once we run this, the `files` array should be empty. The count for files found w ![Delete a file](upload-files-delete.png) -## Next steps {#next} +## Next steps {/* #next */} This tutorial summarized how to use the Slack API to upload files and share them within a channel, using the Python SDK. The same principles apply to other languages as well, so if Python isn't your fancy, feel free to try out our other SDKs: diff --git a/docs/english/v3-migration.md b/docs/english/v3-migration.md index 2ab860e9b..1d4fe2a8a 100644 --- a/docs/english/v3-migration.md +++ b/docs/english/v3-migration.md @@ -2,11 +2,11 @@ sidebar_label: Migrating from slackclient --- -# Migrating from v2.x to v3.x {#migrating} +# Migrating from v2.x to v3.x {/* #migrating */} You may still view the legacy `slackclient` v2 [documentation](/tools/python-slack-sdk/legacy/). However, the **slackclient** project is in maintenance mode and this **slack_sdk** project is the successor. -## From `slackclient` 2.x {#fromv2} +## From `slackclient` 2.x {/* #fromv2 */} There are a few changes introduced in v3.0: @@ -53,11 +53,11 @@ If you use some modules that require `aiohttp`, your `requirements.txt` needs to The new `slack_sdk.web.WebClient` doesn't rely on `aiohttp` internally at all. The class provides only the synchronous way to call Web APIs. If you need a v2 compatible one, you can use `LegacyWebClient`. Apart from the name, there is no breaking change in the class. -If you're using `run_async=True` option, we highly recommend switching to `AsyncWebClient`. `AsyncWebClient` is a straight-forward async HTTP client. You can expect the class properly works in the nature of `async/await` provided by the standard `asyncio` library. +If you're using `run_async=True` option, we highly recommend switching to `AsyncWebClient`. `AsyncWebClient` is a straightforward async HTTP client. You can expect the class properly works in the nature of `async/await` provided by the standard `asyncio` library. --- -## Migration from v1.x to v2.x {#fromv1} +## Migration from v1.x to v2.x {/* #fromv1 */} If you're migrating from v1.x of `slackclient` to v2.x, here's what you need to change to ensure your app continues working after updating. @@ -67,7 +67,7 @@ If you don't wish to upgrade yet, be sure to pin your module for the Python `sla ::: -### Minimum Python versions {#minimum-versions} +### Minimum Python versions {/* #minimum-versions */} `slackclient` v2.x requires Python 3.7 (or higher). @@ -78,7 +78,7 @@ Client v1 support: - We are no longer addressing bug or security fixes. - Github branching: The `master` branch is used for v2 code. The `v1` branch is used for v1 code. -### Import changes {#import-changes} +### Import changes {/* #import-changes */} The goal of this project is to provide a set of tools that ease the creation of Python Slack apps. To better align with this goal, we’re renaming the main module to `slack`. From `slack`, developers can import various tools. @@ -90,7 +90,7 @@ Client v1 support: from slack import WebClient ``` -### RTM API changes {#RTM-changes} +### RTM API changes {/* #RTM-changes */} An RTMClient allows apps to communicate with the Slack platform's Legacy RTM API. This client allows you to link callbacks to their corresponding events. When an event occurs, this client executes your callback while passing along any information it receives. @@ -168,11 +168,11 @@ def get_team_data(**payload): RTM usage has been completely redesigned. -For new projects, we recommend using [Events API](/apis/events-api). This package `slackclient` v2 doesn't have any supports for Events API but you can try https://github.com/slackapi/python-slack-events-api that works as an enhancement of Flask web framework. +For new projects, we recommend using [Events API](/apis/events-api). This package `slackclient` v2 doesn't have any support for Events API but you can try https://github.com/slackapi/python-slack-events-api that works as an enhancement of Flask web framework. -In the near future, we'll be providing better supports for Events API in the official SDK. +In the near future, we'll be providing better support for Events API in the official SDK. -### Web Client API changes {#web-client-changes} +### Web Client API changes {/* #web-client-changes */} **Token refresh removed**: @@ -219,6 +219,6 @@ The WebClient provides built-in methods for the Slack Web API. These methods act - Token type validation: This gives you better error messaging when you're attempting to consume an API method your token doesn't have access to. - Constructs requests using Slack preferred HTTP methods and content-types. -### Error handling changes {#error-handling-changes} +### Error handling changes {/* #error-handling-changes */} In version 1.x, a failed API call would return the error payload to you and expect you to handle the error. In version 2.x, a failed API call will throw an exception. To handle this in your code, you will have to wrap API calls with a `try except` block. diff --git a/docs/english/web.md b/docs/english/web.md index 9f325426b..56695eaaf 100644 --- a/docs/english/web.md +++ b/docs/english/web.md @@ -6,7 +6,7 @@ Accessing Slack API methods requires an OAuth token — read more about [install Each of these [API methods](/reference/methods) is fully documented on our developer site at [docs.slack.dev](/). -## Sending a message {#sending-messages} +## Sending a message {/* #sending-messages */} One of the primary uses of Slack is posting messages to a channel using the channel ID, or as a DM to another person using their user ID. This method will handle either a channel ID or a user ID passed to the `channel` parameter. @@ -53,7 +53,7 @@ response = client.chat_postEphemeral( See the [`chat.postEphemeral`](/reference/methods/chat.postEphemeral) API method for more details. -### Sending streaming messages {#sending-streaming-messages} +### Sending streaming messages {/* #sending-streaming-messages */} You can have your app's messages stream in to replicate conventional AI chatbot behavior. This is done through three Web API methods: @@ -64,7 +64,7 @@ You can have your app's messages stream in to replicate conventional AI chatbot You can streamline calling these methods by using the [`chat_stream()`](#chat_stream) helper. -#### Starting the message stream {#starting-stream} +#### Starting the message stream {/* #starting-stream */} First you need to begin the message stream: @@ -87,7 +87,7 @@ def handle_message(message, client): stream_ts = stream_response["ts"] ``` -#### Appending content to the message stream {#appending-stream} +#### Appending content to the message stream {/* #appending-stream */} With the stream started, you can then append text to it in chunks to convey a streaming effect. @@ -106,7 +106,7 @@ The structure of the text coming in will depend on your source. The following co continue ``` -#### Stopping the message stream {#stopping-stream} +#### Stopping the message stream {/* #stopping-stream */} Your app can then end the stream with the `chat_stopStream` method: @@ -158,7 +158,7 @@ def handle_message(message, client): See [Formatting messages with Block Kit](#block-kit) below for more details on using Block Kit with messages. -#### Using the `chat_stream()` helper {#chat_stream} +#### Using the `chat_stream()` helper {/* #chat_stream */} 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): @@ -182,7 +182,7 @@ feedback_block = create_feedback_block() streamer.stop(blocks=feedback_block) ``` -## Formatting messages with Block Kit {#block-kit} +## Formatting messages with Block Kit {/* #block-kit */} Messages posted from apps can contain more than just text; they can also include full user interfaces composed of blocks using [Block Kit](/block-kit). @@ -232,7 +232,7 @@ client.chat_postMessage( ::: -## Threading messages {#threading-messages} +## Threading messages {/* #threading-messages */} Threaded messages are a way of grouping messages together to provide greater context. You can reply to a thread or start a new threaded conversation by simply passing the original message's `ts` ID in the `thread_ts` attribute when posting a message. If you're replying to a threaded message, you'll pass the `thread_ts` ID of the message you're replying to. @@ -264,7 +264,7 @@ When appearing in the channel, it won't contain any attachments or message butto Refer to the [threading messages](/messaging#threading) page for more information. -## Updating a message {#updating-messages} +## Updating a message {/* #updating-messages */} Let's say you have a bot that posts the status of a request. When that request changes, you'll want to update the message to reflect it's state. @@ -278,7 +278,7 @@ response = client.chat_update( See the [`chat.update`](/reference/methods/chat.update) API method for formatting options and some special considerations when calling this with a bot user. -## Deleting a message {#deleting-messages} +## Deleting a message {/* #deleting-messages */} Sometimes you need to delete things. @@ -292,13 +292,13 @@ response = client.chat_delete( See the [`chat.delete`](/reference/methods/chat.delete) API method for more details. -## Conversations {#conversations} +## Conversations {/* #conversations */} The Slack Conversations API provides your app with a unified interface to work with all the channel-like things encountered in Slack: public channels, private channels, direct messages, group direct messages, and shared channels. Refer to [using the Conversations API](/apis/web-api/using-the-conversations-api) for more information. -### Direct messages {#direct-messages} +### Direct messages {/* #direct-messages */} The `conversations.open` API method opens either a 1:1 direct message with a single user or a multi-person direct message, depending on the number of users supplied to the `users` parameter. (For public or private channels, use the `conversations.create` API method.) @@ -316,7 +316,7 @@ response = client.conversations_open(users=["W123456789", "U987654321"]) See the [`conversations.open`](/reference/methods/conversations.open) API method for additional details. -### Creating channels {#creating-channels} +### Creating channels {/* #creating-channels */} Creates a new channel, either public or private. The `name` parameter is required and may contain numbers, letters, hyphens, or underscores, and must contain fewer than 80 characters. To make the channel private, set the optional `is_private` parameter to `True`. @@ -337,7 +337,7 @@ response = client.conversations_archive(channel=channel_id) See the [`conversations.create`](/reference/methods/conversations.create) API method for additional details. -### Getting conversation information {#getting-conversation-info} +### Getting conversation information {/* #getting-conversation-info */} To retrieve a set of metadata about a channel (public, private, DM, or multi-party DM), use the `conversations.info` API method. The `channel` parameter is required and must be a valid channel ID. The optional `include_locale` boolean parameter will return locale data, which may be useful if you wish to return localized responses. The `include_num_members` boolean parameter will return the number of people in a channel. @@ -354,7 +354,7 @@ response = client.conversations_info( See the [`conversations.info`](/reference/methods/conversations.info) API method for more details. -### Listing conversations {#listing-conversations} +### Listing conversations {/* #listing-conversations */} To get a list of all the conversations in a workspace, use the `conversations.list` API method. By default, only public conversations are returned. Use the `types` parameter specify which types of conversations you're interested in. Note that `types` is a string of comma-separated values. @@ -387,7 +387,7 @@ response = client.conversations_list(exclude_archived=True) See the [`conversations.list`](/reference/methods/conversations.list) API method for more details. -### Getting members of a conversation {#getting-conversation-members} +### Getting members of a conversation {/* #getting-conversation-members */} To get a list of members for a conversation, use the `conversations.members` API method with the required `channel` parameter. @@ -402,7 +402,7 @@ user_ids = response["members"] See the [`conversations.members`](/reference/methods/conversations.members) API method for more details. -### Joining a conversation {#joining-conversations} +### Joining a conversation {/* #joining-conversations */} Channels are the social hub of most Slack teams. Here's how you hop into one: @@ -414,7 +414,7 @@ If you are already in the channel, the response is slightly different. The `alre See the [`conversations.join`](/reference/methods/conversations.join) API method for more details. -### Leaving a conversation {#leaving-conversations} +### Leaving a conversation {/* #leaving-conversations */} To leave a conversation, use the `conversations.leave` API method with the required `channel` parameter containing the ID of the channel to leave. @@ -428,7 +428,7 @@ response = client.conversations_leave(channel="C27182818") See the [`conversations.leave`](/reference/methods/conversations.leave) API method for more details. -## Opening a modal {#opening-modals} +## Opening a modal {/* #opening-modals */} Modals allow you to collect data from users and display dynamic information in a focused surface. Modals use the same blocks that compose messages, with the addition of an `input` block. @@ -504,14 +504,14 @@ if __name__ == "__main__": app.run("localhost", 3000) ``` -See the [`views.open`](/reference/methods/views.open) API method more details and additional parameters. +See the [`views.open`](/reference/methods/views.open) API method for more details and additional parameters. To run the above example, the following [Slack app configurations](https://api.slack.com/apps) are required: * Enable **Interactivity** with a valid Request URL: `https://{your-public-domain}/slack/events` * Add a global shortcut with the callback ID: `open-modal-shortcut` -## Updating and pushing modals {#updating-pushing-modals} +## Updating and pushing modals {/* #updating-pushing-modals */} In response to `view_submission` requests, you can tell Slack to update the current modal view by having `"response_action": update` and an updated view. There are also other `response_action` types, such as `errors` and `push`. Refer to the [modals](/surfaces/modals) page for more details. @@ -594,7 +594,7 @@ See the [`views.update`](/reference/methods/views.update) API method for more de If you want to push a new view onto the modal instead of updating an existing view, see the [`views.push`](/reference/methods/views.push) API method. -## Emoji reactions {#emoji} +## Emoji reactions {/* #emoji */} You can quickly respond to any message on Slack with an emoji reaction. Reactions can be used for any purpose: voting, checking off to-do items, showing excitement, or just for fun. @@ -620,7 +620,7 @@ response = client.reactions_remove( See the [`reactions.add`](/reference/methods/reactions.add) and [`reactions.remove`](/reference/methods/reactions.remove) API methods for more details. -## Uploading files {#upload-files} +## Uploading files {/* #upload-files */} You can upload files to Slack and share them with people in channels. Note that your app's bot user needs to be in the channel (otherwise, you will get either `not_in_channel` or `channel_not_found` error code). @@ -647,7 +647,7 @@ response = client.files_upload_v2( See the [`files.upload`](/reference/methods/files.upload) API method for more details. -## Adding a remote file {#adding-remote-files} +## Adding a remote file {/* #adding-remote-files */} You can add a file information that is stored in an external storage rather than in Slack. @@ -662,7 +662,7 @@ response = client.files_remote_add( See the [files.remote.add](/reference/methods/files.remote.add) API method for more details. -## Calling API methods {#calling-API-methods} +## Calling API methods {/* #calling-API-methods */} This library covers all the public endpoints as the methods in `WebClient`. That said, you may see a bit of a delay with the library release. When you're in a hurry, you can directly use the `api_call` method as below. @@ -678,7 +678,7 @@ response = client.api_call( assert response["message"]["text"] == "Hello world!" ``` -## AsyncWebClient {#asyncwebclient} +## AsyncWebClient {/* #asyncwebclient */} The Web API client is available in asynchronous programming using the standard [asyncio](https://docs.python.org/3/library/asyncio.html) library. You use `AsyncWebClient` instead. `AsyncWebClient` internally relies on the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library, but it is an optional dependency. To use this class, run `pip install aiohttp` beforehand. @@ -710,7 +710,7 @@ async def post_message(): asyncio.run(post_message()) ``` -## RetryHandler {#retryhandler} +## RetryHandler {/* #retryhandler */} With the default settings, only `ConnectionErrorRetryHandler` with its default configuration (=only one retry in the manner of [exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)) is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., connection reset by peer). @@ -762,9 +762,9 @@ client = WebClient( ) ``` -For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those methods are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. +For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those modules are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. -## Rate limits {#rate-limits} +## Rate limits {/* #rate-limits */} When posting messages to a channel, Slack allows apps to send no more than one message per channel per second. We allow bursts over that limit for short periods; however, if your app continues to exceed the limit over a longer period of time, it will be rate limited. Different API methods have other limits — be sure to check the [rate limits](/apis/web-api/rate-limits) and test that your app has a graceful fallback if it should hit those limits. diff --git a/docs/english/webhook.md b/docs/english/webhook.md index c9850d506..d3feeb7f7 100644 --- a/docs/english/webhook.md +++ b/docs/english/webhook.md @@ -1,6 +1,6 @@ # Webhook client -## Incoming webhooks {#incoming-webhooks} +## Incoming webhooks {/* #incoming-webhooks */} You can use `slack_sdk.webhook.WebhookClient` for [incoming webhooks](/messaging/sending-messages-using-incoming-webhooks) and message responses using [`response_url`](/interactivity/handling-user-interaction#message_responses) in payloads. @@ -38,7 +38,7 @@ response = webhook.send( ## The `response_url` -User actions in channels generates a [`response_url`](/interactivity/handling-user-interaction#message_responses) and includes the URL in its payload. You can use `WebhookClient` to send a message via the `response_url`. +User actions in channels generate a [`response_url`](/interactivity/handling-user-interaction#message_responses) and include the URL in the payload. You can use `WebhookClient` to send a message via the `response_url`. ``` python import os @@ -76,7 +76,7 @@ def slack_app(): return make_response("", 404) ``` -## AsyncWebhookClient {#asyncwebhookclient} +## AsyncWebhookClient {/* #asyncwebhookclient */} The webhook client is available in asynchronous programming using the standard [asyncio](https://docs.python.org/3/library/asyncio.html) library. You use `AsyncWebhookClient` instead. `AsyncWebhookClient` internally relies on the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library, but it is an optional dependency. To use this class, run `pip install aiohttp` beforehand. @@ -97,7 +97,7 @@ async def send_message_via_webhook(url: str): asyncio.run(send_message_via_webhook(url)) ``` -## RetryHandler {#retryhandler} +## RetryHandler {/* #retryhandler */} With the default settings, only `ConnectionErrorRetryHandler` with its default configuration (=only one retry in the manner of [exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)) is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., connection reset by peer). @@ -149,4 +149,4 @@ webhook = WebhookClient( ) ``` -For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those methods are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details. +For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those modules are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details.