Skip to content

API Docs: Update docs links to go to new docs site #1464

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
haleychaas merged 1 commit into from
Apr 14, 2025
Merged

API Docs: Update docs links to go to new docs site #1464

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
34 changes: 17 additions & 17 deletions docs/content/guides/ai-apps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,29 @@ If you don't have a paid workspace for development, you can join the [Developer

:::

AI apps comprise a new messaging experience for Slack. If you're unfamiliar with using AI apps within Slack, you'll want to read the [API documentation on the subject](https://api.slack.com/docs/apps/ai). Then come back here to implement them with Bolt!
AI apps comprise a new messaging experience for Slack. If you're unfamiliar with using AI apps within Slack, you'll want to read the [API documentation on the subject](https://docs.slack.dev/ai/). Then come back here to implement them with Bolt!

## Configuring your app to support AI apps features {#configuring-your-app}

1. Within [App Settings](https://api.slack.com/apps), enable the **Agents & AI Apps** feature.

2. Within the App Settings **OAuth & Permissions** page, add the following scopes:
* [`assistant:write`](https://api.slack.com/scopes/assistant:write)
* [`chat:write`](https://api.slack.com/scopes/chat:write)
* [`im:history`](https://api.slack.com/scopes/im:history)
* [`assistant:write`](https://docs.slack.dev/reference/scopes/assistant.write)
* [`chat:write`](https://docs.slack.dev/reference/scopes/chat.write)
* [`im:history`](https://docs.slack.dev/reference/scopes/im.history)

3. Within the App Settings **Event Subscriptions** page, subscribe to the following events:
* [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started)
* [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed)
* [`message.im`](https://api.slack.com/events/message.im)
* [`assistant_thread_started`](https://docs.slack.dev/reference/events/assistant_thread_started)
* [`assistant_thread_context_changed`](https://docs.slack.dev/reference/events/assistant_thread_context_changed)
* [`message.im`](https://docs.slack.dev/reference/events/message.im)

## The `Assistant` class instance {#assistant-class}

The [`Assistant`](/reference#the-assistantconfig-configuration-object) class can be used to handle the incoming events expected from a user interacting with an AI app in Slack. A typical flow would look like:

1. [The user starts a thread](#handling-a-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event.
2. [The thread context may change at any point](#handling-thread-context-changes). The `Assistant` class can handle any incoming [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) events. The class also provides a default `context` store to keep track of thread context changes as the user moves through Slack.
3. [The user responds](#handling-user-response). The `Assistant` class handles the incoming [`message.im`](https://api.slack.com/events/message.im) event.
1. [The user starts a thread](#handling-a-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](https://docs.slack.dev/reference/events/assistant_thread_started) event.
2. [The thread context may change at any point](#handling-thread-context-changes). The `Assistant` class can handle any incoming [`assistant_thread_context_changed`](https://docs.slack.dev/reference/events/assistant_thread_context_changed) events. The class also provides a default `context` store to keep track of thread context changes as the user moves through Slack.
3. [The user responds](#handling-user-response). The `Assistant` class handles the incoming [`message.im`](https://docs.slack.dev/reference/events/message.im) event.

```java
App app = new App();
Expand Down Expand Up @@ -71,7 +71,7 @@ assistant.userMessage((req, ctx) -> {
app.assistant(assistant);
```

While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextService` property — but it also provides a `DefaultAssistantThreadContextService` instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](https://api.slack.com/metadata/using) as the user interacts with the app.
While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextService` property — but it also provides a `DefaultAssistantThreadContextService` instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](https://docs.slack.dev/messaging/message-metadata/) as the user interacts with the app.

If you do provide your own `threadContextService` property, it must feature `get` and `save` methods.

Expand All @@ -81,15 +81,15 @@ Be sure to give the [AI apps reference docs](/reference#agents--assistants) a lo

## Handling a new thread {#handling-a-new-thread}

When the user opens a new thread with your AI app, the [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event will be sent to your app.
When the user opens a new thread with your AI app, the [`assistant_thread_started`](https://docs.slack.dev/reference/events/assistant_thread_started) event will be sent to your app.

:::tip
When a user opens a thread with your app while in a channel, the channel info is stored as the thread's `AssistantThreadContext` data. You can grab that info by using the `context.getThreadContext()` utility, as subsequent user message event payloads won't include the channel info.
:::

### Block Kit interactions in the AI app thread {#block-kit-interactions}

For advanced use cases, Block Kit buttons may be used instead of suggested prompts, as well as the sending of messages with structured [metadata](https://api.slack.com/metadata) to trigger subsequent interactions with the user.
For advanced use cases, Block Kit buttons may be used instead of suggested prompts, as well as the sending of messages with structured [metadata](https://docs.slack.dev/messaging/message-metadata/) to trigger subsequent interactions with the user.

For example, an app can display a button like "Summarize the referring channel" in the initial reply. When the user clicks the button and submits detailed information (such as the number of messages, days to check, the purpose of the summary, etc.), the app can handle that information and post a message that describes the request with structured metadata.

Expand Down Expand Up @@ -175,9 +175,9 @@ app.assistant(assistant);

## Handling thread context changes {#handling-thread-context-changes}

When the user switches channels, the [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) event will be sent to your app.
When the user switches channels, the [`assistant_thread_context_changed`](https://docs.slack.dev/reference/events/assistant_thread_context_changed) event will be sent to your app.

If you use the built-in `Assistant` middleware without any custom configuration, the updated context data is automatically saved as [message metadata](https://api.slack.com/metadata/using) of the first reply from the assistant bot.
If you use the built-in `Assistant` middleware without any custom configuration, the updated context data is automatically saved as [message metadata](https://docs.slack.dev/messaging/message-metadata/) of the first reply from the assistant bot.

As long as you use the built-in approach, you don't need to store the context data within a datastore. The downside of this default behavior is the overhead of additional calls to the Slack API. These calls include those to `conversations.history`, which are used to look up the stored message metadata that contains the thread context (via `context.getThreadContextService().findCurrentContext(channelId, threadTs)`).

Expand All @@ -189,9 +189,9 @@ Assistant assistant = new Assistant(new YourOwnAssistantThreadContextService());

## Handling the user response {#handling-user-response}

When the user messages your app, the [`message.im`](https://api.slack.com/events/message.im) event will be sent to your app.
When the user messages your app, the [`message.im`](https://docs.slack.dev/reference/events/message.im) event will be sent to your app.

Messages sent to the app do not contain a [subtype](https://api.slack.com/events/message#subtypes) and must be deduced based on their shape and any provided [message metadata](https://api.slack.com/metadata/using).
Messages sent to the app do not contain a [subtype](https://docs.slack.dev/reference/events/message) and must be deduced based on their shape and any provided [message metadata](https://docs.slack.dev/messaging/message-metadata/).

There are three utilities that are particularly useful in curating the user experience:
* [`say`](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/#slack_bolt.Say)
Expand Down
22 changes: 11 additions & 11 deletions docs/content/guides/app-distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@ lang: en

# App Distribution (OAuth)

A newly created Slack app can only be installed in its development workspace in the beginning. By setting an OAuth Redirect URL and enabling [App Distribution](https://api.slack.com/start/distributing), the app becomes to be ready for installation in any other workspaces.
A newly created Slack app can only be installed in its development workspace in the beginning. By setting an OAuth Redirect URL and enabling [App Distribution](https://docs.slack.dev/distribution/), the app becomes to be ready for installation in any other workspaces.

* [Installing with OAuth](https://api.slack.com/authentication/oauth-v2)
* [Distributing Slack Apps](https://api.slack.com/start/distributing)
* [Installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth)
* [Distributing Slack Apps](https://docs.slack.dev/distribution/)

### Slack App Configuration

To enable App Distribution, visit the [Slack App configuration page](http://api.slack.com/apps), choose the app you're working on, go to **Settings** > **Manage Distribution** on the left pane, and follow the instructions there.

For **Redirect URL**, Bolt apps respond to `https://{your app's public URL domain}/slack/oauth/callback` if you go with recommended settings. To know how to configure such settings, consult the list of the available env variables below in this page.

Bolt for Java automatically includes support for [org wide installations](https://api.slack.com/enterprise/apps) since version `1.4.0`. Org wide installations can be enabled in your app configuration settings under **Org Level Apps**.
Bolt for Java automatically includes support for [org wide installations](https://docs.slack.dev/enterprise-grid/) since version `1.4.0`. Org wide installations can be enabled in your app configuration settings under **Org Level Apps**.

### What Your Bolt App Does

Expand All @@ -26,7 +26,7 @@ All your app needs to do to properly handle OAuth Flow are:
* Append `client_id`, `scope`, `user_scope` (only for v2), and `state` to the URL
* Provide an endpoint to handle user redirection from Slack
* Make sure if the `state` parameter is valid
* Complete the installation by calling [oauth.v2.access](https://api.slack.com/methods/oauth.v2.access) (or [oauth.access](https://api.slack.com/methods/oauth.access) if you maintain legacy OAuth apps) method and store the acquired tokens
* Complete the installation by calling [oauth.v2.access](https://docs.slack.dev/reference/methods/oauth.v2.access) (or [oauth.access](https://docs.slack.dev/reference/methods/oauth.access) if you maintain legacy OAuth apps) method and store the acquired tokens
* Provide the endpoints to navigate installers for the completion/cancellation of the installation flow
* The URLs are usually somewhere else but Bolt has simple functionality to serve them

Expand Down Expand Up @@ -147,23 +147,23 @@ SlackAppServer server = new SlackAppServer(new HashMap<>(Map.ofEntries(
server.start(); // http://localhost:3000
```

If you want to turn [the token rotation feature](https://api.slack.com/authentication/rotation) on, your `InstallationService` should be compatible with it. Refer to the [v1.9.0 release notes](https://github.com/slackapi/java-slack-sdk/releases/tag/v1.9.0) for more details.
If you want to turn [the token rotation feature](https://docs.slack.dev/authentication/using-token-rotation) on, your `InstallationService` should be compatible with it. Refer to the [v1.9.0 release notes](https://github.com/slackapi/java-slack-sdk/releases/tag/v1.9.0) for more details.

### Granular Permission Apps or Classic Apps

Slack has two types of OAuth flows for Slack app installations. The V2 (this is a bit confusing but it's not the version of OAuth spec, but the version of the Slack OAuth flow) OAuth flow enables Slack apps to request more granular permissions than the classic ones, especially for bot users. The differences between the two types are having `v2` in the endpoint to issue access tokens and the OAuth Authorization URL, plus some changes to the response data structure returned by the `oauth(.v2).access` endpoint.

#### [V2 OAuth 2.0 Flow](https://api.slack.com/authentication/oauth-v2) (default)
#### [V2 OAuth 2.0 Flow](https://docs.slack.dev/authentication/installing-with-oauth) (default)

|-|-|
|Authorization URL|`https://slack.com/oauth/v2/authorize`|
|Web API to issue access tokens|[`oauth.v2.access`](https://api.slack.com/methods/oauth.v2.access) ([Response](https://github.com/slackapi/java-slack-sdk/blob/main/slack-api-client/src/main/java/com/slack/api/methods/response/oauth/OAuthV2AccessResponse.java))|
|Web API to issue access tokens|[`oauth.v2.access`](https://docs.slack.dev/reference/methods/oauth.v2.access) ([Response](https://github.com/slackapi/java-slack-sdk/blob/main/slack-api-client/src/main/java/com/slack/api/methods/response/oauth/OAuthV2AccessResponse.java))|

#### [Classic OAuth Flow](https://api.slack.com/docs/oauth)
#### [Classic OAuth Flow](https://docs.slack.dev/authentication/installing-with-oauth)

|-|-|
|Authorization URL|`https://slack.com/oauth/authorize`|
|Web API to issue access tokens|[`oauth.access`](https://api.slack.com/methods/oauth.access) ([Response](https://github.com/slackapi/java-slack-sdk/blob/main/slack-api-client/src/main/java/com/slack/api/methods/response/oauth/OAuthAccessResponse.java))|
|Web API to issue access tokens|[`oauth.access`](https://docs.slack.dev/reference/methods/oauth.access) ([Response](https://github.com/slackapi/java-slack-sdk/blob/main/slack-api-client/src/main/java/com/slack/api/methods/response/oauth/OAuthAccessResponse.java))|

By default, Bolt enables the V2 OAuth Flow over the classic one. It's configurable by **AppConfig**'s the setter method for `classicAppPermissionsEnabled`. The value is set to `false` by default. Change the flag to `true` to authorize your classic OAuth apps.

Expand Down Expand Up @@ -258,7 +258,7 @@ public class SlackApp {

#### Use the Built-in tokens_revoked / app_uninstalled Event Handlers

For secure data management for your customers and end-users, properly handling [tokens_revoked](https://api.slack.com/events/tokens_revoked) and [app_uninstalled](https://api.slack.com/events/app_uninstalled) events is crucial. Bolt for Java provides the built-in event handlers for these events, which seamlessly integrated with your `InstallationService`'s deletion methods.
For secure data management for your customers and end-users, properly handling [tokens_revoked](https://docs.slack.dev/reference/events/tokens_revoked) and [app_uninstalled](https://docs.slack.dev/reference/events/app_uninstalled) events is crucial. Bolt for Java provides the built-in event handlers for these events, which seamlessly integrated with your `InstallationService`'s deletion methods.

```java
App app = new App();
Expand Down
12 changes: 6 additions & 6 deletions docs/content/guides/app-home.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ lang: en

# App Home

An [App Home](https://api.slack.com/surfaces/tabs/events) is a private, one-to-one space in Slack shared by a user and an app. Each App Home contains a number of tabbed surfaces, including a Messages tab for app-user conversation, and a Home tab that can be fully customized by the app.
An [App Home](https://docs.slack.dev/surfaces/app-home) is a private, one-to-one space in Slack shared by a user and an app. Each App Home contains a number of tabbed surfaces, including a Messages tab for app-user conversation, and a Home tab that can be fully customized by the app.

### Slack App Configuration

Expand All @@ -24,10 +24,10 @@ To enable Events API, go to **Features** > **Event Subscriptions** on the left p

All your app needs to do to provide Home tabs to your app users are:

1. Call the [**views.publish**](https://api.slack.com/methods/views.publish) method to update the Home tab on a per-user basis
1. Call the [**views.publish**](https://docs.slack.dev/reference/methods/views.publish) method to update the Home tab on a per-user basis
2. Handle any user interactions in Home tab (`"block_actions"`, `"block_suggestion"`)

Most commonly, [`"app_home_opened"`](https://api.slack.com/events/app_home_opened) events would be used as the trigger to call the [**views.publish**](https://api.slack.com/methods/views.publish) method. Subscribing this event type is useful particularly for the initial Home tab creation. But it's also fine to publish Home tabs by any other means.
Most commonly, [`"app_home_opened"`](https://docs.slack.dev/reference/events/app_home_opened) events would be used as the trigger to call the [**views.publish**](https://docs.slack.dev/reference/methods/views.publish) method. Subscribing this event type is useful particularly for the initial Home tab creation. But it's also fine to publish Home tabs by any other means.

---
## Examples
Expand All @@ -38,7 +38,7 @@ If you're a beginner to using Bolt for Slack App development, consult [Getting S

:::

The following code calls [**views.publish**](https://api.slack.com/methods/views.publish) method when receiving an [`"app_home_opened"` events](https://api.slack.com/events/app_home_opened) for the user that triggered the event. The user will see the updated Home tab immediately after the [**views.publish**](https://api.slack.com/methods/views.publish) call has been successfully completed.
The following code calls [**views.publish**](https://docs.slack.dev/reference/methods/views.publish) method when receiving an [`"app_home_opened"` events](https://docs.slack.dev/reference/events/app_home_opened) for the user that triggered the event. The user will see the updated Home tab immediately after the [**views.publish**](https://docs.slack.dev/reference/methods/views.publish) call has been successfully completed.

```java
import com.slack.api.methods.response.views.ViewsPublishResponse;
Expand All @@ -50,7 +50,7 @@ import static com.slack.api.model.block.Blocks.*;
import static com.slack.api.model.block.composition.BlockCompositions.*;
import static com.slack.api.model.view.Views.*;

// https://api.slack.com/events/app_home_opened
// https://docs.slack.dev/reference/events/app_home_opened
app.event(AppHomeOpenedEvent.class, (payload, ctx) -> {
// Build a Home tab view
ZonedDateTime now = ZonedDateTime.now();
Expand Down Expand Up @@ -89,7 +89,7 @@ import com.slack.api.model.view.Views.*
import com.slack.api.model.event.AppHomeOpenedEvent
import java.time.ZonedDateTime

// https://api.slack.com/events/app_home_opened
// https://docs.slack.dev/reference/events/app_home_opened
app.event(AppHomeOpenedEvent::class.java) { event, ctx ->
// Build a Home tab view
val now = ZonedDateTime.now()
Expand Down
Loading