Skip to content

docs: audit and fix docs/english markdown files #1883

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
lukegalbraithrussell wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: audit and fix docs/english markdown files #1883

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6484e00
critical fixes
lukegalbraithrussell May 29, 2026
c2217d4
more review and conversion
lukegalbraithrussell May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/maintainers_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions docs/english/audit-logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -34,9 +34,9 @@ api_response = client.schemas()
api_response = client.actions()
```

## AsyncAuditLogsClient {#asyncauditlogsclient}
## 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 the aiohttp library.

``` python
from slack_sdk.audit_logs.async_client import AsyncAuditLogsClient
Expand All @@ -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).

Expand All @@ -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
Expand Down Expand Up @@ -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.
6 changes: 3 additions & 3 deletions docs/english/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|---|
Expand All @@ -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!

Expand All @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions docs/english/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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).

Expand All @@ -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.
Expand All @@ -113,7 +113,7 @@ def pre_install():
'Add to Slack</a>'
```

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

Expand Down Expand Up @@ -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.
Expand Down
10 changes: 5 additions & 5 deletions docs/english/legacy/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.**

Expand All @@ -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).

Expand All @@ -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.
Expand All @@ -75,7 +75,7 @@ def pre_install():
'Add to Slack</a>'
```

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

Expand Down
34 changes: 17 additions & 17 deletions docs/english/legacy/basic_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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()
Expand All @@ -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(
Expand All @@ -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.

Expand All @@ -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.

Expand Down
Loading