# Slack > In this tutorial, you'll learn how to bring the power of AI into your Slack workspace using a chatbot called Bolty that uses Anthropic or OpenAI. Here's what we'll do with this sample app: --- # Source: https://docs.slack.dev/tools/bolt-python/tutorial/ai-chatbot # AI Chatbot In this tutorial, you'll learn how to bring the power of AI into your Slack workspace using a chatbot called Bolty that uses Anthropic or OpenAI. Here's what we'll do with this sample app: 1. Create your app from an app manifest and clone a starter template 2. Set up and run your local project 3. Create a workflow using Workflow Builder to summarize messages in conversations 4. Select your preferred API and model to customize Bolty's responses 5. Interact with Bolty via direct message, the `/ask-bolty` slash command, or by mentioning the app in conversations ## Prerequisites Before getting started, you will need the following: - a development workspace where you have permissions to install apps. If you don’t have a workspace, go ahead and set that up now — you can [go here](https://slack.com/get-started#create) to create one, or you can join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. - a development environment with [Python 3.7](https://www.python.org/downloads/) or later. - an Anthropic or OpenAI account with sufficient credits, and in which you have generated a secret key. **Skip to the code** If you'd rather skip the tutorial and just head straight to the code, you can use our [Bolt for Python AI Chatbot sample](https://github.com/slack-samples/bolt-python-ai-chatbot) as a template. ## Creating your app 1. Navigate to the [app creation page](https://api.slack.com/apps/new) and select **From a manifest**. 2. Select the workspace you want to install the application in. 3. Copy the contents of the [`manifest.json`](https://github.com/slack-samples/bolt-python-ai-chatbot/blob/main/manifest.json) file into the text box that says **Paste your manifest code here** (within the **JSON** tab) and click **Next**. 4. Review the configuration and click **Create**. 5. You're now in your app configuration's **Basic Information** page. Navigate to the **Install App** link in the left nav and click **Install to Workspace**, then **Allow** on the screen that follows. ### Obtaining and storing your environment variables Before you'll be able to successfully run the app, you'll need to first obtain and set some environment variables. #### Slack tokens From your app's page on [app settings](https://api.slack.com/apps) collect an app and bot token: 1. On the **Install App** page, copy your **Bot User OAuth Token**. You will store this in your environment as `SLACK_BOT_TOKEN` (we'll get to that next). 2. Navigate to **Basic Information** and in the **App-Level Tokens** section, click **Generate Token and Scopes**. Add the [`connections:write`](/reference/scopes/connections.write) scope, name the token, and click **Generate**. (For more details, refer to [understanding OAuth scopes for bots](/authentication/tokens#bot)). Copy this token. You will store this in your environment as `SLACK_APP_TOKEN`. To store your tokens and environment variables, run the following commands in the terminal. Replace the placeholder values with your bot and app tokens collected above: **For macOS** ```bash export SLACK_BOT_TOKEN= export SLACK_APP_TOKEN= ``` **For Windows** ```powershell set SLACK_BOT_TOKEN= set SLACK_APP_TOKEN= ``` #### Provider tokens Models from different AI providers are available if the corresponding environment variable is added as shown in the sections below. ##### Anthropic To interact with Anthropic models, navigate to your Anthropic account dashboard to [create an API key](https://console.anthropic.com/settings/keys), then export the key as follows: ```bash export ANTHROPIC_API_KEY= ``` ##### Google Cloud Vertex AI To use Google Cloud Vertex AI, [follow this quick start](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#expandable-1) to create a project for sending requests to the Gemini API, then gather [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) with the strategy to match your development environment. Once your project and credentials are configured, export environment variables to select from Gemini models: ```bash export VERTEX_AI_PROJECT_ID= export VERTEX_AI_LOCATION= ``` The project location can be located under the **Region** on the [Vertex AI](https://console.cloud.google.com/vertex-ai) dashboard, as well as more details about available Gemini models. ##### OpenAI Unlock the OpenAI models from your OpenAI account dashboard by clicking [create a new secret key](https://platform.openai.com/api-keys), then export the key like so: ```bash export OPENAI_API_KEY= ``` ## Setting up and running your local project Clone the starter template onto your machine by running the following command: ```bash git clone https://github.com/slack-samples/bolt-python-ai-chatbot.git ``` Change into the new project directory: ```bash cd bolt-python-ai-chatbot ``` Start your Python virtual environment: **For macOS** ```bash python3 -m venv .venv source .venv/bin/activate ``` **For Windows** ```bash py -m venv .venv .venv\Scripts\activate ``` Install the required dependencies: ```bash pip install -r requirements.txt ``` Start your local server: ```bash python app.py ``` If your app is up and running, you'll see a message that says "⚡️ Bolt app is running!" ## Choosing your provider Navigate to the Bolty **App Home** and select a provider from the drop-down menu. The options listed will be dependent on which secret keys you added when setting your environment variables. If you don't see Bolty listed under **Apps** in your workspace right away, never fear! You can mention **@Bolty** in a public channel to add the app, then navigate to your **App Home**. ![Choose your AI provider](https://docs.slack.dev/assets/images/6-90ef0d4d041ca7d3607699b802eca6ba.png) ## Setting up your workflow Within your development workspace, open Workflow Builder by clicking on your workspace name and then **Tools > Workflow Builder**. Select **New Workflow** > **Build Workflow**. Click **Untitled Workflow** at the top to rename your workflow. For this tutorial, we'll call the workflow **Welcome to the channel**. Enter a description, such as _Summarizes channels for new members_, and click **Save**. ![Setting up a new workflow](https://docs.slack.dev/assets/images/1-f9c24f965e8474d3c7e673ce05673ffd.png) Select **Choose an event** under **Start the workflow...**, and then choose **When a person joins a channel**. Select the channel name from the drop-down menu and click **Save**. ![Start the workflow](https://docs.slack.dev/assets/images/2-f28431ae65be1c00553a7b2aec61bc10.png) Under **Then, do these things**, click **Add steps** and complete the following: 1. Select **Messages** > **Send a message to a person**. 2. Under **Select a member**, choose **The user who joined the channel** from the drop-down menu. 3. Under **Add a message**, enter a short message, such as _Hi! Welcome to `{The channel that the user joined}`. Would you like a summary of the recent conversation?_ Note that the _`{The channel that the user joined`}_ is a variable; you can insert it by selecting **Insert a variable** at the bottom of the message text box. 4. Select the **Add Button** button, and name the button _Yes, give me a summary_. Click **Done**. ![Send a message](https://docs.slack.dev/assets/images/3-905316d2b75f243f2a05ed06eaf32cd0.png) We'll add two more steps under the **Then, do these things** section. First, scroll to the bottom of the list of steps and choose **Custom**, then choose **Bolty** and **Bolty Custom Function**. In the **Channel** drop-down menu, select **Channel that the user joined**. Click **Save**. ![Bolty custom function](https://docs.slack.dev/assets/images/4-dc916f899491971827db1a6ebe7a16aa.png) For the final step, complete the following: 1. Choose **Messages** and then **Send a message to a person**. Under **Select a member**, choose **Person who clicked the button** from the drop-down menu. 2. Under **Add a message**, click **Insert a variable** and choose **`{Summary}`** under the **Bolty Custom Function** section in the list that appears. Click **Save**. ![Summary](https://docs.slack.dev/assets/images/5-51cb5fc9c8350067939001cee6315f8f.png) When finished, click **Finish Up**, then click **Publish** to make the workflow available in your workspace. ## Interacting with Bolty ### Summarizing recent conversations In order for Bolty to provide summaries of recent conversation in a channel, Bolty _must_ be a member of that channel. 1. Invite Bolty to a channel that you are able to leave and rejoin (for example, not the **#general** channel or a private channel someone else created) by mentioning the app in the channel — i.e., tagging **@Bolty** in the channel and sending your message. 2. Slackbot will prompt you to either invite Bolty to the channel, or do nothing. Click **Invite Them**. Now when new users join the channel, the workflow you just created will be kicked off. To test this, leave the channel you just invited Bolty to and rejoin it. This will kick off your workflow and you'll receive a direct message from **Welcome to the channel**. Click the **Yes, give me a summary** button, and Bolty will summarize the recent conversations in the channel you joined. ![Channel summary](https://docs.slack.dev/assets/images/7-a94698b85daeed62f48e11366cae7cba.png) The central part of this functionality is shown in the following code snippet. Note the use of the [`user_context`](https://docs.slack.dev/tools/deno-slack-sdk/reference/slack-types#usercontext) object, a Slack type that represents the user who is interacting with our workflow, as well as the `history` of the channel that will be summarized, which includes the ten most recent messages. ```python from ai.providers import get_provider_response from logging import Logger from slack_bolt import Complete, Fail, Ack from slack_sdk import WebClient from ...listener_utils.listener_constants import SUMMARIZE_CHANNEL_WORKFLOW from ...listener_utils.parse_conversation import parse_conversation """ Handles the event to summarize a Slack channel's conversation history. It retrieves the conversation history, parses it, generates a summary using an AI response, and completes the workflow with the summary or fails if an error occurs. """ def handle_summary_function_callback( ack: Ack, inputs: dict, fail: Fail, logger: Logger, client: WebClient, complete: Complete ): ack() try: user_context = inputs["user_context"] channel_id = inputs["channel_id"] history = client.conversations_history(channel=channel_id, limit=10)["messages"] conversation = parse_conversation(history) summary = get_provider_response(user_context["id"], SUMMARIZE_CHANNEL_WORKFLOW, conversation) complete({"user_context": user_context, "response": summary}) except Exception as e: logger.exception(e) fail(e) ``` ### Asking Bolty a question To ask Bolty a question, you can chat with Bolty in any channel the app is in. Use the `\ask-bolty` slash command to provide a prompt for Bolty to answer. Note that Bolty is currently not supported in threads. You can also navigate to **Bolty** in your **Apps** list and select the **Messages** tab to chat with Bolty directly. ![Ask Bolty](https://docs.slack.dev/assets/images/8-5942a49b49344e9477dbbb5605f92567.png) ## Next steps Congratulations! You've successfully integrated the power of AI into your workspace. Check out these links to take the next steps in your Bolt for Python journey. - To learn more about Bolt for Python, refer to the [Getting started](https://docs.slack.dev/tools/bolt-python/getting-started) documentation. - For more details about creating workflow steps using the Bolt SDK, refer to the [workflow steps for Bolt](https://docs.slack.dev/workflows/workflow-steps) guide. - To use the Bolt for Python SDK to develop on the automations platform, refer to the [tutorial](https://docs.slack.dev/tools/bolt-python/tutorial/custom-steps-workflow-builder-new/Create%20a%20workflow%20step%20for%20Workflow%20Builder:%20Bolt%20for%20Python) to create a workflow step for Workflow Builder. --- # The Events API The Events API is a streamlined way to build apps and bots that respond to activities in Slack. When you use the Events API, _Slack_ calls _you_. You have two options: you can either use [Socket Mode](/apis/events-api/using-socket-mode) or you can designate a public [HTTP endpoint](/apis/events-api/using-http-request-urls) that your app listens on, choose what events to subscribe to, and _voilà_: Slack sends the appropriate events to you. Learn more about the differences between Socket Mode and HTTP [here](/apis/events-api/comparing-http-socket-mode). All you need is a Slack app and a secure place for us to send your [events](/reference/events). With the Events API, you can do the following: - Tell Slack where to send your [event types](/reference/events) and we'll deliver them with grace, security, and respect. We'll even retry when things don't work out. The [event types](/reference/events) sent to you are directly tied to the [OAuth permission scopes](/authentication/installing-with-oauth) awarded as users install your Slack app. - Subscribe to only the [event types](/reference/events) you want; don't worry about the ones you don't need. - Subscribe your Slack apps to events related to channels and direct messages they are party to. Build bots without a bothersome bevy of [Real Time Messaging (RTM) API](/legacy/legacy-rtm-api) WebSockets. ## Overview Many apps built using the Events API will follow the same abstract event-driven sequence: 1. A user creates a circumstance that triggers an event subscription to your application. 2. Your server receives a payload of JSON describing that event. 3. Your server acknowledges receipt of the event. 4. Your business logic decides what to do about that event. 5. Your server carries out that decision. If your app is a bot listening to messages with specific trigger phrases, that event loop may play out something like the following: 1. Members send messages in a channel the bot belongs to—the #random channel. The messages are about lots of things, but some of them contain today's secret word. 2. Your server receives a [`message.channels`](/reference/events/message.channels) event, as per its bot subscription and membership in the #random channel. 3. Your server responds with a swift and confident HTTP 200 OK. 4. Your bot is trained to listen for today's secret word, and having found it, decides to send a message to the channel, encouraging everyone to keep that word secret. 5. Your server uses [`chat.postMessage`](/reference/methods/chat.postMessage) from the Web API to post that message to #random. Using the Web API with the Events API empowers your app or bot to do much more than just listen and reply to messages. Let's get started! --- ## Preparing your app to use the Events API The Events API is recommended over the [RTM API](/legacy/legacy-rtm-api) for most use cases. If you're already familiar with HTTP and are comfortable maintaining your own server, handling the request and response cycle of the Events API should be familiar. If the world of web APIs is new to you, the Events API is a great next step after mastering [incoming webhooks](/messaging/sending-messages-using-incoming-webhooks) or the [Web API](/apis/web-api/). ### Is the Events API right for your app? Before starting, you may want to make a few early decisions about your application architecture and approach to consuming events. The Events API is best used in conjunction with other platform features. One way to use the Events API is as an alternative to opening WebSocket connections to the [RTM API](/legacy/legacy-rtm-api). Why choose the Events API over the legacy RTM API? Instead of maintaining one or more long-lived connections for each workspace an application is connected to, you can set up one or more endpoints on your own servers to receive events atomically in near real-time. Some developers may want to use the Events API as a kind of redundancy for their existing WebSocket connections. Other developers will use the Events API to receive information around the workspaces and users they are acting on behalf, to improve their [slash commands](/interactivity/implementing-slash-commands), bot users, [notifications](/messaging), or other capabilities. With [app events](#app_events), you can track app uninstallation, token revocation, Enterprise org migration, and more. Handle anything else your app does by using [incoming webhooks](/messaging/sending-messages-using-incoming-webhooks) and other write-based [web API methods](/reference/methods). ### Permission model The Events API leverages Slack's existing [object-driven OAuth scope system](/authentication/installing-with-oauth) to control access to events. For example, if your app has access to files through the `files:read` scope, you can choose to subscribe to any or none of the file-related events such as [`file_created`](/reference/events/file_created) and [`file_deleted`](/reference/events/file_deleted). You will only receive events that users who have authorized your app can "see" on their workspace (that is, if a user authorizes access to private channel history, you'll only see the activity in private channels they are a member of, not all private channels across the workspace). [Bot users](/authentication/tokens#bot) may also subscribe to events on their own behalf. The `bot` scope requested when workspaces install your bot covers events access for both the Events API and the [Real Time Messaging API](/legacy/legacy-rtm-api). ## Subscribing to event types To begin working with the Events API, you'll need to create a Slack app if you haven't already. While managing your application, find the **Event Subscriptions** setting and use the toggle to turn it on. ![The on switch for the Events API](/assets/images/event_subscriptions-f8d89f09c291f496bcf5646213f50c8a.png) After a little more configuration, you'll be able to select all the [event types](/reference/events) you want to subscribe to. Before continuing on to choosing event subscriptions, you will need to choose to use either Socket Mode or an HTTP request URL. For more information on the differences between them, refer to [Exploring HTTP vs Socket Mode](/apis/events-api/comparing-http-socket-mode). To set up your app to use Socket Mode, refer to the [Socket Mode](/apis/events-api/using-socket-mode) guide. To set up your app to use HTTP request URLs, refer to the [HTTP](/apis/events-api/using-http-request-urls) guide. ### Choosing event subscriptions After configuring and validating either Socket Mode or your request URL, it's time to subscribe to the [event types](/reference/events) you find fascinating, useful, or necessary. ![The event subscription configuration process](/assets/images/event_subscriptions-f8d89f09c291f496bcf5646213f50c8a.png) The subscription manager is split into two sections: - Team Events: these are the events that require a corresponding OAuth scope, and are perspectival to a member installing your application. - Bot Events: subscribe to events on behalf of your application's [bot user](/authentication/tokens#bot), no additional scopes beyond `bot` required. As with workspace events, you'll only receive events perspectival to your bot user. Some event types are not available in bot user subscriptions. ### Activating subscriptions The Events API is backed by the same [OAuth permission scoping system](/authentication/installing-with-oauth) powering your Slack app. If workspaces have already installed your application, your request URL will soon begin receiving your configured event subscriptions. For any workspaces that have yet to install your application, you'll need to request the specific OAuth scopes corresponding to the [event types](/reference/events) you're subscribing to. If you're working on behalf of a [bot user](/authentication/tokens#bot), you'll need your bot installed the typical way, using the `bot` OAuth scope. Authorize users for your Event Consumer app through the standard [OAuth flow](/authentication). Be sure to include all of the necessary scopes for the events your app wants to receive. Consult our index of the [available event types with corresponding OAuth scopes](/reference/events). With all this due preparation out of the way, it's time to receive and handle all those event subscriptions. ## Receiving events Your Request URL will receive a request for each event matching your subscriptions. One request, one event. You may want to consider the number of workspaces you serve, the number of users on those workspaces, their volume of messages, and other activity to evaluate how many requests your Request URL may receive and scale accordingly. ### Events dispatched as JSON When an event in your subscription occurs in an authorized user's account, we'll send an HTTP POST request to your Request URL. The event will be in the `Content-Type: application/json` format: ```json { "type": "event_callback", "token": "XXYYZZ", "team_id": "T123ABC456", "api_app_id": "A123ABC456", "event": { "type": "name_of_event", "event_ts": "1234567890.123456", "user": "U123ABC456", ... }, "event_context": "EC123ABC456", "event_id": "Ev123ABC456", "event_id": "Ev123ABC456" } --- # Slack Web API The Slack Web API is an interface for querying information _from_ and enacting change _in_ a Slack workspace. Use it for individual queries, or as part of a more complex tapestry of platform features in a Slack app. [Web API methods](/reference/methods) --- ## Basic overview - The Web API is a collection of [HTTP RPC-style methods](/reference/methods), all with URLs in the form `https://slack.com/api/METHOD_FAMILY.method`. - While it's not a REST API, those familiar with REST should be at home with its foundations in HTTP. - Use HTTPS, SSL, and TLS v1.2 or above when calling all methods. [Learn more about our SSL and TLS requirements](#ssl). - Each method has a series of arguments informing the execution of your intentions. - Pass arguments as: - GET querystring parameters, - POST parameters presented as `application/x-www-form-urlencoded`, or - a mix of both GET and POST parameters - [Most write methods](#methods_supporting_json) allow arguments with `application/json` attributes. - Some methods, such as [`chat.postMessage`](/reference/methods/chat.postMessage) and [`dialog.open`](/reference/methods/dialog.open), feature arguments that accept an associative JSON array. However, these methods can be difficult to properly construct when using a `application/x-www-form-urlencoded` Content-type, so we strongly recommend using [JSON-encoded bodies](#posting_json) instead. ### POST bodies When sending a HTTP POST, you may present your arguments as either standard POST parameters, or you may use JSON instead. #### URL-encoded bodies When sending URL-encoded data, set your HTTP `Content-type` header to `application/x-www-form-urlencoded` and present your key/value pairs according to [RFC-3986](https://tools.ietf.org/html/rfc3986). For example, a POST request to the [`conversations.create`](/reference/methods/conversations.create) method might look something like this: ```http POST /api/conversations.create Content-type: application/x-www-form-urlencoded token=xoxp-xxxxxxxxx-xxxx&name=something-urgent ``` #### JSON-encoded bodies For [write methods that support JSON](#methods_supporting_json), you may alternatively send your HTTP POST data as `Content-type: application/json`. There are some ground rules: - You must explicitly set the `Content-type` HTTP header to `application/json`. We won't interpret your POST body as such without it. - You must transmit your `token` as a bearer token in the `Authorization` HTTP header. - You cannot send your token as part of the query string or as an attribute in your posted JSON. - Do not mix arguments between query string, URL-encoded POST body, and JSON attributes. Choose one approach per request. - Providing an explicitly `null` value for an attribute will result in whichever default behavior is assigned to it. For example, to send the same request above to the `conversations.create` method with a JSON POST body, send something like this: ```http POST /api/conversations.create Content-type: application/json Authorization: Bearer xoxp-xxxxxxxxx-xxxx {"name":"something-urgent"} ``` Note how we present the token with the string `Bearer ` pre-pended to it, indicating the [OAuth 2.0](/authentication) authentication scheme. Consult your favorite HTTP tool or library's manual for further detail on setting HTTP headers. Here's a more complicated example — posting a message with [menus](/legacy/legacy-messaging/legacy-adding-menus-to-messages) using [`chat.postMessage`](/reference/methods/chat.postMessage): ```http POST /api/chat.postMessage Content-type: application/json Authorization: Bearer xoxp-xxxxxxxxx-xxxx {"channel":"C123ABC456","text":"I hope the tour went well, Mr. Wonka.","attachments": [{"text":"Who wins the lifetime supply of chocolate?","fallback":"You could be telling the computer exactly what it can do with a lifetime supply of chocolate.","color":"#3AA3E3","attachment_type":"default","callback_id":"select_simple_1234","actions":[{"name":"winners_list","text":"Who should win?","type":"select","data_source":"users"}]}]} ``` The `attachments` argument is sent a straightforward JSON array. Here's how to do that with [cURL](https://curl.haxx.se/): ```bash curl -X POST -H 'Authorization: Bearer xoxb-1234-56789abcdefghijklmnop' \ -H 'Content-type: application/json' \ --data '{"channel":"C123ABC456","text":"I hope the tour went well, Mr. Wonka.","attachments": [{"text":"Who wins the lifetime supply of chocolate?","fallback":"You could be telling the computer exactly what it can do with a lifetime supply of chocolate.","color":"#3AA3E3","attachment_type":"default","callback_id":"select_simple_1234","actions":[{"name":"winners_list","text":"Who should win?","type":"select","data_source":"users"}]}]}' \ https://slack.com/api/chat.postMessage< ``` #### Errors specific to passing JSON If the posted JSON is invalid, you'll receive one of the following errors in response: - `invalid_json`: The JSON you've included in your POST body cannot be parsed. This might be because it's actually not JSON, or perhaps you did not correctly set your HTTP `Content-type` header. Ensure your JSON attribute keys are strings wrapped with double-quote (`"`) characters. - `json_not_object`: We could understand that your code was JSON-like enough to parse it, but it's not actually a JSON hash of attribute key/value pairs. Perhaps you sent us an array, or just a string or a number. In both cases, you'll need to revise your JSON or how you're transmitting your data to resolve the error condition. --- ## Evaluating responses All Web API responses contain a JSON object, which will always contain a top-level boolean property `ok` that indicates success or failure. For failure results, the `error` property will contain a short machine-readable error code. In the case of problematic calls that could still be completed successfully, `ok` will be `true` and the `warning` property will contain a short machine-readable warning code (or comma-separated list of them, in the case of multiple warnings). See the following examples: ```json { "ok": true, "stuff": "This is good" } ``` ```json { "ok": false, "error": "something_bad" } ``` ```json { "ok": true, "warning": "something_problematic", "stuff": "Your requested information" } ``` Other properties are defined in the documentation for each relevant method. There's a lot of "stuff" to unpack, including [these types](/reference/objects) and other method or domain-specific curiosities. --- ## Authentication Authenticate your Web API requests by providing a [bearer token](/authentication/tokens), which identifies a single user or bot user relationship. [Register your application](https://api.slack.com/apps) with Slack to obtain credentials for use with our [OAuth 2.0](/authentication/installing-with-oauth) implementation, which allows you to negotiate tokens on behalf of users and workspaces. We prefer tokens to be sent in the `Authorization` HTTP header of your outbound requests. However, you may also pass tokens in all Web API calls as a POST body parameter called `token`. Tokens cannot be sent as a query parameter. > Treat tokens with care > > Never share tokens with other users or applications. Do not publish tokens in public code repositories. [Review token safety tips](/security). --- ## HTTPS, SSL, and TLS Slack requires HTTPS, SSL, and TLS v1.2 or above. The platform and the Web API are governed by the same rules. [Learn more about our deprecation of early TLS versions](/changelog/2019-07-deprecate-early-tls-versions). Stay safe and secure. All TLS connections must use the [SNI extension](https://en.wikipedia.org/wiki/Server_Name_Indication). Lastly, TLS connections must support at least one of the following cipher suites: TLS 1.2: - `ECDHE-RSA-AES128-GCM-SHA256` - `ECDHE-RSA-CHACHA20-POLY1305` - `ECDHE-RSA-AES256-GCM-SHA384` TLS 1.3: - `TLS_AES_128_GCM_SHA256` - `TLS_AES_256_GCM_SHA384` - `TLS_CHACHA20_POLY1305_SHA256` --- ## Methods With over 200 methods, surely there's one right for you. You can find them all in the [reference](/reference/methods), where you can filter by method family. --- # Using token rotation This guide covers [token rotation](https://datatracker.ietf.org/doc/html/rfc6819#section-5.2.2.3) for Slack apps, which use [granular permissions](/authentication/installing-with-oauth). You'll learn how to exchange your access token for a refresh token and an expiring access token. With token rotation, you'll provide an extra layer of security for your access tokens. ## Overview An [access token](/authentication/tokens) represents an installation of your Slack app. Without token rotation, the access token never expires. With token rotation, it expires every 12 hours. An OAuth flow with token rotation involves exchanging one expiring access token for a new one, using an additional token: the refresh token. The refresh token is then revoked, and a new refresh token is used to exchange the new expiring access token when it expires. New access and refresh tokens need to be _rotated_ in throughout the lifespan of the app for it to continue to function. ### Access token types | Framework | Setup with token supported version | | --- | --- | | Bolt for Java | `implementation("com.slack.api:bolt-jetty:1.9.+")` | | Bolt for JavaScript | `npm i @slack/bolt@3.5` | | Bolt for Python | `pip install "slack-bolt>=1.7"` | Whether you're using an SDK or not, continue to turn on token rotation. ## Before you begin If you don't have a Slack app already, that's okay! Click on the button below to begin the process of creating one: [Create an app](https://api.slack.com/apps?new_app=1) Fill out your **App Name** and select the Development Workspace where you'll play around and build your app. Don't fuss too much over either field—no matter what workspace you select, you'll still be able to [distribute your app](/app-management/distribution) to other workspaces if you choose. If you've just made your app, or if your Slack app isn't set up with our new OAuth V2, head over to our guide on [Installing with OAuth](/authentication/installing-with-oauth). We'll wait right here for you. ### Consider the Bolt framework If you use [Bolt](/tools#bolt) to develop your app, your job will be a whole lot easier. Token rotation is automatically handled in the Bolt framework for building Slack apps. All flavors of Bolt have versions that support token rotation. | Framework | Setup with token supported version | | --- | --- | | Bolt for Java | `implementation("com.slack.api:bolt-jetty:1.9.+")` | | Bolt for JavaScript | `npm i @slack/bolt@3.5` | | Bolt for Python | `pip install "slack-bolt>=1.7"` | Whether you're using an SDK or not, continue to turn on token rotation. ## Turn on token rotation Token rotation may not be turned off once it's turned on. Before you turn on token rotation, consider how you're going to test your implementation. You don't want all your access tokens to expire before you've successfully figured out how to refresh them. If your app _is not_ published in the Slack Marketplace, token rotation is enabled via the **OAuth & Permissions** section of your [app settings](https://api.slack.com/apps). If your app _is_ published in the Slack Marketplace, now is a good time to follow the advice in our [guide to testing Slack Marketplace apps](/slack-marketplace/slack-marketplace-app-guidelines-and-requirements). Apps published in the Slack Marketplace can have token rotation enabled via the **Published App Settings** section of your [app settings](https://api.slack.com/apps). And if you're using a Bolt app, this is your stop! You're all good to go. If not, keep reading. The [next section](#exchange) is just for you. ## Exchange the long-lived access token A Slack app implemented with OAuth will already have a long-lived access token. You need to call the [`oauth.v2.exchange`](/reference/methods/oauth.v2.exchange) method to exchange that long-lived access token for a refresh token and an expiring access token. You'll need your app's `client_id` and `client_secret` as well, which can be found under "App Credentials" within the specific app's "Basic Information" [page](https://api.slack.com/apps). Here's a sample call: ```http POST /api/oauth.v2.exchange HOST slack.com Content-Type: application/x-www-form-urlencoded client_id=60503450.61416 client_secret=8bc5fc53901afc11c token=xoxb-1234-... ``` Either a granular [bot token](/authentication/tokens#user) or [user token](/authentication/tokens#user) may be exchanged for a refresh token and expiring access token. You won't be able to exchange the same access token for a refresh token more than once. After you refresh your short-lived credentials for the first time, we'll expire your original long-lived access token. Please don't try to revoke it yourself using [`auth.revoke`](/reference/methods/auth.revoke), or you'll end up making the user redo the whole OAuth installation process (_yikes!_). Instead, just call [`auth.test`](/reference/methods/auth.test) to make sure the original token won't work anymore. Keep in mind that this applies to **both user** and **bot** tokens, so make sure to repeat the OAuth process to get your hands on fresh credentials. Here's a sample response from `oauth.v2.exchange` when exchanging a bot token: ```json { "ok": true, "access_token": "xoxe.xoxb-1-...", "expires_in": 43200, "refresh_token": "xoxe-1-...", "token_type": "bot", "scope": "commands,incoming-webhook", "bot_user_id": "U123456", "app_id": "A123456", "team": { "name": "Slack Softball Team", "id": "T123456" }, "enterprise": { "name": "slack-sports", "id": "E12345678" } } ``` Notice that your `access_token` now has a new `xoxe.` prefix. The access token's lifespan is based on the `expires_in` field. This field defines the number of seconds until the access token you've received expires. It will always expire in 43,200 seconds, which is 12 hours. The response will also have a `refresh_token`. You now have your first set of rotatable tokens! ## Refresh a token Any time you implement OAuth with your Slack app, whether token rotation is enabled or not, the last step of the flow requires you to call the [`oauth.v2.access`](/reference/methods/oauth.v2.access) method. The only difference with token rotation is that you'll be calling the method throughout your app's life to get new tokens. In order to refresh a token, make a call to `oauth.v2.access`, setting the new `grant_type` parameter to your refresh token: ```http POST /api/oauth.v2.access HOST slack.com Content-Type: application/x-www-form-urlencoded client_id=60503450.61416 client_secret=8bc5fc53901afc11c grant_type=refresh_token refresh_token=xoxe-1-... ``` Note that `client_id` and `client_secret` are still required for this call as well. When you have turned on the token rotation toggle, your app will receive additional data from `oauth.v2.access`. Expect a response that contains the following new fields [mentioned earlier](#exchange): ```json { ... "expires_in": 43200, // 12 hours "refresh_token": "xoxe-1-...", ... } ``` You can receive refresh tokens for both user tokens and bot tokens in the same `oauth.v2.access` response (only applies to the initial `oauth.v2.access` response **before** token rotation is enabled). If you make use of a [user token](/authentication/tokens#user), expect those two new fields along with your access token in the `authed_user` object of the response: ```json "authed_user": { "id": "U1234", "scope": "chat:write", "access_token": "xoxe.xoxp-1-1234-...", "expires_in": 43200, // 12 hours "refresh_token": "xoxe-1-..." "token_type": "user" } ``` Use the new `refresh_token` when you need to refresh the tokens once again. Schedule a task to refresh your access token _before_ the `expires_in` time. If you don't refresh your access token in time, you'll receive an error when you make an API call with the expired access token. Store the refresh token as you would an access token, in a database or secure datastore (not in code). Refresh tokens are designed to be used once. After calling `oauth.v2.access`, the refresh token you used is revoked after a short grace period. Calling `oauth.v2.access` will not immediately invalidate your existing access token. If you need to immediately revoke an access token, you can call [`auth.revoke`](/reference/methods/auth.revoke). 2 active token limit If you refresh your credentials repeatedly before expiration (e.g. by calling `oauth.v2.access` multiple times for the same token within a 12 hour period), we will enforce a limit of 2 active tokens. If more than 2 tokens exist after the refresh, the oldest additional token will be revoked. Once you've successfully refreshed an access token, congratulations! You're now developing with a more secure app that makes use of token rotation. --- ## App manifests and token rotation You may **also** create a new app that makes use of token rotation using [app manifests](/app-manifests/configuring-apps-with-app-manifests). Add the following to your app manifest YAML to enable token rotation: ```yaml settings: token_rotation_enabled: true ``` --- ## Uninstalling apps Slack APIs provide multiple ways to undo Slack installations. With [`apps.uninstall`](/reference/methods/apps.uninstall), behavior is the same regardless of whether the app uses token rotation. The app is uninstalled and all tokens associated with the installation are revoked. [`auth.revoke`](/reference/methods/auth.revoke) is used to revoke a single token of an installation. When used on an app **without** token rotation, it usually revokes the authorization associated with it, meaning that the user or team that had the app installed needs to reinstall it. For apps _with_ token rotation, `auth.revoke` will revoke a single token (a refresh token, a bot access token that expires, or a user access token that expires) without changing the underlying installation. Events will still be delivered and new tokens may still be generated in the UI. --- # Authentication overview Authentication is a critical part of the development process, but it doesn’t have to be daunting. With the right tools and best practices, you’ll have a secure, smooth authentication flow. Whether you’re handling [OAuth 2.0](/authentication/installing-with-oauth), [verifying requests](/authentication/verifying-requests-from-slack), or setting up [Sign in with Slack](/authentication/sign-in-with-slack/), we’ve got you covered. ## Authentication basics Before your app can access Slack data or interact with Slack workspaces, it must go through an authentication process. This involves obtaining the necessary tokens and permissions for your app to function properly. Slack apps use OAuth [scopes](/reference/scopes) to govern what they can access. These are added in the app settings when building an app. You will attach these scopes to your tokens. Check out [tokens](/authentication/tokens) to learn more. You can rotate those tokens too! Find out how on the [Using token rotation](/authentication/using-token-rotation) page. ## Key concepts - [**OAuth 2.0**](/authentication/installing-with-oauth): Learn how to use OAuth 2.0 to securely authenticate users and request access tokens. - [**Tokens**](/authentication/tokens): Understand the different types of tokens your app can use (user tokens, bot tokens, and app tokens) and how to manage them, as well as employ token rotation and expiry to keep things fresh. - [**Security best practices**](/security): Learn about security practices for managing authentication, such as validating tokens, handling sensitive data, and protecting your app from unauthorized access. ## Reference - [**Scopes and Permissions**](/reference/scopes): Find the right permissions for your app to ensure access is limited to only the necessary data. --- # Block Kit The Block Kit UI framework is built with _blocks_, _block elements_, and _composition objects_. ![Image 1](https://docs.slack.dev/assets/images/bk_landing_bkb-e64c290c97543b50e0b09c0b291c7c78.png) Blocks are visual components that can be arranged to create app layouts. Apps can add blocks to _surfaces_ like [the Home tab](https://docs.slack.dev/surfaces/app-home), [messages](https://docs.slack.dev/messaging), and [modals](https://docs.slack.dev/surfaces/modals). You can include up to 50 blocks in each message, and 100 blocks in modals or Home tabs. Blocks may also contain _block elements_. Block elements are usually interactive components, such as buttons and menus. Blocks and block elements are built with _composition objects_. Composition objects define text, options, or other interactive features within certain blocks and block elements. Whether you're composing layouts for modals, messages, or tabs, the Block Kit building experience is the same — your app will be sculpting specially-structured JSON to express itself. The result is clear, interactive communication between your app and its users. Eager to see Block Kit in action? [Take a peek in Block Kit Builder.](https://api.slack.com/tools/block-kit-builder?blocks=%5B%7B%22type%22%3A%22section%22%2C%22text%22%3A%7B%22type%22%3A%22mrkdwn%22%2C%22text%22%3A%22Hey%20there%20%F0%9F%91%8B%20I%27m%20TaskBot.%20I%27m%20here%20to%20help%20you%20create%20and%20manage%20tasks%20in%20Slack.%5CnThere%20are%20two%20ways%20to%20quickly%20create%20tasks%3A%22%7D%7D%2C%7B%22type%22%3A%22section%22%2C%22text%22%3A%7B%22type%22%3A%22mrkdwn%22%2C%22text%22%3A%22*1%EF%B8%8F%E2%83%A3%20Use%20the%20%60%2Ftask%60%20command*.%20Type%20%60%2Ftask%60%20followed%20by%20a%20short%20description%20of%20your%20tasks%20and%20I%27ll%20ask%20for%20a%20due%20date%20(if%20applicable).%22%7D%7D%2C%7B%22type%22%3A%22section%22%2C%22text%22%3A%7B%22type%22%3A%22mrkdwn%22%2C%22text%22%3A%22*2%EF%B8%8F%E2%83%A3%20Use%20the%20_Create%20a%20Task_%20action.*%20If%20you%20want%20to%20create%20a%20task%20from%20a%20message%2C%20select%20%60Create%20a%20Task%60%20in%20a%20message%27s%20context%20menu.%20Try%20it%20out%20by%20selecting%20the%20_Create%20a%20Task_%20action%20for%20this%20message%20(shown%20below).%22%7D%7D%2C%7B%22type%22%3A%22image%22%2C%22title%22%3A%7B%22type%22%3A%22plain_text%22%2C%22text%22%3A%22image1%22%2C%22emoji%22%3Atrue%7D%2C%22image_url%22%3A%22https%3A%2F%2Fapi.slack.com%2Fimg%2Fblocks%2Fbkb_template_images%2FonboardingComplex.jpg%22%2C%22alt_text%22%3A%22image1%22%7D%2C%7B%22type%22%3A%22section%22%2C%22text%22%3A%7B%22type%22%3A%22mrkdwn%22%2C%22text%22%3A%22%E2%9E%95%20To%20start%20tracking%20your%20team%27s%20tasks%2C%20*add%20me%20to%20a%20channel*%20and%20I%27ll%20introduce%20myself.%20I%27m%20usually%20added%20to%20a%20team%20or%20project%20channel.%20Type%20%60%2Finvite%20%40TaskBot%60%20from%20the%20channel%20or%20pick%20a%20channel%20on%20the%20right.%22%7D%2C%22accessory%22%3A%7B%22type%22%3A%22conversations_select%22%2C%22placeholder%22%3A%7B%22type%22%3A%22plain_text%22%2C%22text%22%3A%22Select%20a%20channel...%22%2C%22emoji%22%3Atrue%7D%7D%7D%2C%7B%22type%22%3A%22divider%22%7D%2C%7B%22type%22%3A%22context%22%2C%22elements%22%3A%5B%7B%22type%22%3A%22mrkdwn%22%2C%22text%22%3A%22%F0%9F%91%80%20View%20all%20tasks%20with%20%60%2Ftask%20list%60%5Cn%E2%9D%93Get%20help%20at%20any%20time%20with%20%60%2Ftask%20help%60%20or%20type%20*help*%20in%20a%20DM%20with%20me%22%7D%5D%7D%5D) ## Some blocks can only be used in particular app surfaces. Read the [Block Kit reference guides](https://docs.slack.dev/reference/block-kit/blocks) to check if a block is compatible with your app's surfaces. ## Building blocks There's no special setup needed to start using blocks in [app surfaces](https://docs.slack.dev/surfaces). However, just as when you open a pack of generic, colorful, interlocking plastic bricks, you should read the instructions first. ### Defining a single block Each block is represented in our APIs as a JSON object. Here's an example of a [`section`](https://docs.slack.dev/reference/block-kit/blocks/section-block) block: ```json { "type": "section", "text": { "type": "mrkdwn", "text": "New Paid Time Off request from \n\n" } } ``` [Preview in Block Kit Builder](https://api.slack.com/tools/block-kit-builder/#%7B%22blocks%22:%5B%7B%22type%22:%22section%22,%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22New%20Paid%20Time%20Off%20request%20from%20%3Cexample.com%7CFred%20Enriquez%3E%5Cn%5Cn%3Chttps://example.com%7CView%20request%3E%22%7D%7D%5D%7D) Every block contains a `type` field — specifying which of the [available blocks](https://docs.slack.dev/reference/block-kit/blocks) to use — along with other fields that describe the content of the block. [Block Kit Builder](https://api.slack.com/tools/block-kit-builder/) is a visual prototyping sandbox that will let you choose from, configure, and preview all the available blocks. If you want to skip the builder, the [block reference guide](https://docs.slack.dev/reference/block-kit/blocks) contains the specifications of every block, and the JSON fields required for each of them. ### Stacking multiple blocks Individual blocks can be stacked together to create complex visual layouts. When you've chosen each of the blocks you want in your layout, place each of them in an array, in visual order, like this: ```json [ { "type": "header", "text": { "type": "plain_text", "text": "New request" } }, { "type": "section", "fields": [ { "type": "mrkdwn", "text": "*Type:*\nPaid Time Off" }, { "type": "mrkdwn", "text": "*Created by:*\n" } ] }, { "type": "section", "fields": [ { "type": "mrkdwn", "text": "*When:*\nAug 10 - Aug 13" } ] }, { "type": "section", "text": { "type": "mrkdwn", "text": "" } } ] ``` [Preview in Block Kit Builder](https://api.slack.com/tools/block-kit-builder/#%7B%22blocks%22:%5B%7B%22type%22:%22header%22,%22text%22:%7B%22type%22:%22plain_text%22,%22text%22:%22New%20request%22,%22emoji%22:true%7D%7D,%7B%22type%22:%22section%22,%22fields%22:%5B%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Type:*%5CnPaid%20Time%20Off%22%7D,%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Created%20by:*%5Cn%3Cexample.com%7CFred%20Enriquez%3E%22%7D%5D%7D,%7B%22type%22:%22section%22,%22fields%22:%5B%7B%22type%22:%22mrkdwn%22,%22text%22:%22*When:*%5CnAug%2010%20-%20Aug%2013%22%7D,%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Type:*%5CnPaid%20time%20off%22%7D%5D%7D,%7B%22type%22:%22section%22,%22fields%22:%5B%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Hours:*%5Cn16.0%20(2%20days)%22%7D,%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Remaining%20balance:*%5Cn32.0%20hours%20(4%20days)%22%7D%5D%7D,%7B%22type%22:%22section%22,%22text%22:%7B%22type%22:%22mrkdwn%22,%22text%22:%22%3Chttps://example.com%7CView%20request%3E%22%7D%7D%5D) --- # Source: https://docs.slack.dev/tools/bolt-js/ # Bolt for JavaScript Bolt for JavaScript is a JavaScript framework to build Slack apps with the latest Slack platform features. Read the [Quickstart Guide](/tools/bolt-js/getting-started) to set up and run your first Bolt app. Then, explore the rest of the pages within the Guides section. The documentation there will help you build a Bolt app for whatever use case you may have. ## Getting help These docs have lots of information on Bolt for JavaScript. There's also an in-depth Reference section. Please explore! If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/bolt-js/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. ## Contributing These docs live within the [Bolt-JS](https://github.com/slackapi/bolt-js/) repository and are open source. We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/bolt-js/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way. --- # Source: https://docs.slack.dev/tools/bolt-python/ # Bolt for Python Bolt for Python is a Python framework to build Slack apps with the latest Slack platform features. Read the [Getting Started Guide](/tools/bolt-python/getting-started) to set up and run your first Bolt app. Then, explore the rest of the pages within the Guides section. The documentation there will help you build a Bolt app for whatever use case you may have. ## Getting help These docs have lots of information on Bolt for Python. There's also an in-depth Reference section. Please explore! If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/bolt-python/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for Python. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. ## Contributing These docs live within the [Bolt-Python](https://github.com/slackapi/bolt-python/) repository and are open source. We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/bolt-python/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way. --- # Source: https://docs.slack.dev/tools/deno-slack-sdk/guides/creating-functions # Creating functions ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. Functions are one of the three building blocks that make up workflow apps. You will encounter all three as you navigate the path of building your app: 1. Functions define the actions of your app. (⬅️ you are here) 2. Workflows are a combination of functions, executed in order. 3. Triggers execute workflows. There are three types of functions: - **[Slack functions](/tools/deno-slack-sdk/guides/creating-slack-functions)** enable Slack-native actions, like creating a channel or sending a message. - **[Connector functions](/tools/deno-slack-sdk/guides/creating-connector-functions)** enable actions native to services outside of Slack. Google Sheets, Dropbox and Microsoft Excel are just a few of the services with available connector functions. Connector functions cannot be used in a workflow intended for use in a Slack Connect channel. - **[Custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions)** enable developer-specific actions. Pass in any desired inputs, perform any actions you can code up, and pass on outputs to other parts of your workflows. Custom functions also allow your app to create and process workflow steps that users can add in Workflow Builder. See the [Workflow Builder custom step tutorial](/tools/deno-slack-sdk/tutorials/workflow-builder-custom-step/) for instruction. --- ### Previous [Using the app manifest](/tools/deno-slack-sdk/guides/using-the-app-manifest) ### Next [Creating Slack functions](/tools/deno-slack-sdk/guides/creating-slack-functions) --- # Source: https://docs.slack.dev/tools/deno-slack-sdk/ # Deno Slack SDK ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. You can create Slack-hosted workflows written in TypeScript using the [Deno Slack SDK](https://github.com/slackapi/deno-slack-sdk). Workflows are a combination of functions, executed in order. There are three types of functions: - **Slack functions** enable Slack-native actions, like creating a channel or sending a message. - **Connector functions** enable actions native to services _outside_ of Slack. Google Sheets, Dropbox, and Microsoft Excel are a few of the services with available connector functions. - **Custom functions** enable developer-specific actions. Pass in any desired inputs, perform any actions you can code up, and pass on outputs to other parts of your workflows. Workflows are invoked via triggers. You can invoke workflows: - via a link within Slack, - on a schedule, - when specified events occur, - or via webhooks. Workflows make use of specifically designed features of the Slack platform such as [datastores](/tools/deno-slack-sdk/guides/using-datastores), a Slack-hosted way to store data. While in development, you can keep your project mostly to yourself, or share it with a close collaborator. If your Slack admin requires approval of app installations, they’ll need to approve what you’re creating first. ### The app management UI on `api.slack.com/apps` doesn't support configuring workflow apps. Workflow apps are also currently not eligible for listing in the Slack Marketplace. ## Getting help These docs have lots of information on the Deno Slack SDK. Please explore! If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/deno-slack-sdk/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. --- # Slack developer FAQ We know there's a lot to learn and read about all the integration points of the Slack platform. Here is a little more information you might find helpful! ## General ### How do I build a bot using Slack APIs? We have a [quickstart](/quickstart) guide that will walk you through the process! ### How do I set up a developer environment to build a Slack app? You can provision sandbox environments by joining the [Slack Developer Program](https://api.slack.com/developer-program). Once you're ready to deploy your app, distributing the app will allow you to install it in other workspaces. Start by [building a Slack app](/app-management/quickstart-app-settings) to contain all of your work—by default, it can only be installed on your own workspace. Follow the instructions in the UI to add features—most require that you provide a HTTP server Slack can reach. Have more questions? Check out our [developer sandbox FAQs](/tools/developer-sandboxes#faqs)! Are you a partner with us? The [Slack Partner Developer Program](https://api.slack.com/developer-program/partners) offers [partner sandboxes](/tools/partner-sandboxes). ### Is Slack down? Of course we want Slack to be fully functional for users and developers at all times. Here are some tips in the unfortunate event you're having trouble and need to determine the cause of a Slack-related issue. When possible, we report current status promptly on [status.slack.com](https://status.slack.com/) with any service disruption advisories, but you can also use the following methods: - Use the [Slack Status API](/reference/slack-status-api). - Send a HTTP GET request to the [`https://slack.com/api/api.test`](/reference/methods/api.test) API method. A HTTP 200 `application/json` response of `{"ok":true}` indicates at least part of the Slack [Web API](/apis/web-api/) is available. - Send a more complex, [authenticated](/authentication) request to [`https://slack.com/api/auth.test`](/reference/methods/auth.test) using a bot, user, or legacy [token](/authentication/tokens). Using this method exercises the authorization and API layer further than `api.test` and may grant you the serenity of greater confidence in Slack availability. - If using the legacy [Real Time Messaging (RTM) API](/legacy/legacy-rtm-api), try using [`rtm.connect`](/reference/methods/rtm.connect) to generate a WebSocket URL using a token with the proper permissions, then open the socket using a tool like [this browser-based WebSocket client for Google Chrome](https://chrome.google.com/webstore/detail/simple-websocket-client/pfdhoblngboilpfeibdedpjgfnlcodoo?hl=en). Still unsure if Slack is down? Contact our enthusiastic [support team](https://my.slack.com/help/requests/new). ### How do I integrate a third-party service with Slack? Check whether there is an app for a third-party service in the Slack Marketplace. If all else fails, you'll need to [code one for yourself](/quickstart). You can also add [connector functions](/tools/deno-slack-sdk/reference/connector-functions) to your automations workflows. A growing library of third-party services are available. ### Apps vs. workflows Building a Slack app? Start [here](/quickstart). Building a workflow? Start [here](/workflows). For more about workflows and custom workflow steps, jump to [this section](#automations-workflow-apps). ## Authentication ### How do I authenticate my requests to Slack? #### By token When working with Slack apps or the [Web API](/apis/web-api/), you'll often need to send access tokens, also known as bearer tokens, along with inbound requests within the authorization header. When creating an app for the first time, you'll be given your own user and bot token while going through the app creation process. In order to obtain other users' tokens, you'll need to send users through the [OAuth 2.0 authentication flow](/authentication). When you're working with Slack apps, you'll be awarded access tokens after a user approves your application. #### By private URL Your [incoming webhook](/messaging/sending-messages-using-incoming-webhooks) URLs are unique to your integration or application and do not require token-based authentication. [Slash command response URLs](/interactivity/implementing-slash-commands#responding_to_a_command) also already encode your integration's or application's identity. ### How do I authenticate requests from Slack to me? Use the [signing secret](/authentication/verifying-requests-from-slack) to compute a signature, and verify that the signature on the request matches. This process is _strongly_ preferred over the use of deprecated verification tokens. You can also use [Mutual TLS](/authentication/verifying-requests-from-slack#mutual_tls). Mutual TLS verifies the identity of Slack in a TLS-terminating server, before a request reaches your application code. ### How does Slack authenticate its requests to my servers? When you configure [Slash commands](/interactivity/implementing-slash-commands), you specify a URL for Slack to send requests to when qualifying conditions are met. Slack also provides you a token related to that integration. Slack sends that URL a JSON payload containing a `token` field. Compare that field to values you've received from Slack. Refer to [validating slash commands](/interactivity/implementing-slash-commands#validating_the_command) for more information. ### When do authorization codes expire? Authorization codes must be exchanged for an access token within 10 minutes by calling the [oauth.access](/reference/methods/oauth.access) API method as part of the [authorization flow](/authentication). Otherwise, the authorization code will expire, and you'll need to ask the user to go through the OAuth flow again. ### How do I revoke a token? Use the [`apps.uninstall`](/reference/methods/apps.uninstall) API method to uninstall an app completely, revoking all tokens. If you want to dispose of a single OAuth access token, use the [`auth.revoke`](/reference/methods/auth.revoke) API method; it works with tokens from [Sign in with Slack](/authentication/sign-in-with-slack/) as well as from [legacy](/legacy/legacy-slack-button/Add-to-Slack). For classic apps, revoking the last token associated between your application and a workspace effectively uninstalls the app for that workspace. Members and administrators can remove your app through their [workspace administration interface](https://my.slack.com/apps/manage). Though it's somewhat of a nuclear option, you also have the ability to revoke all tokens from your [developer dashboard](https://api.slack.com/apps) by selecting your application and clicking **Revoke all tokens**. ### How do I reset my client secret? To reset your client secret, go to your [developer dashboard](https://api.slack.com/apps), select the application, and click the **Change secret** button. Don't forget to use your new secret when exchanging authorization codes for access tokens while authorizing users and workspaces with [OAuth 2.0](/authentication). ## Slash commands ### Why does Slack never reach my slash command URL? Typically, if Slack cannot reach your slash command URL it's because it's inaccessible, does not have a valid or verifiable SSL certificate, or our request is timing out for some reason. Slack invokes slash command URLs from its servers rather than from a Slack client app like Slack for Mac. This means that the URL we're trying to reach must be accessible to Slack's servers. To determine whether your certificate is valid, consider using [this tool](https://www.ssllabs.com/ssltest/index.html) provided by SSL Labs. ### How do I validate a slash command's origin? Keep track of the validation tokens and team IDs Slack gives you when commands are created and teams approve your app. Always validate that the `token` field in an incoming slash command request has been issued to you by Slack, and scope your data for that workspace. ## Incoming webhooks ### Why can't I override the channel, icon, or user name of my incoming webhook? You won't be able to override any of these fields when using an [incoming webhook](/messaging/sending-messages-using-incoming-webhooks) attached to a Slack app. Instead, those values will be provided from your Slack app configuration and any configuration provided by the team. ## Interactive messages ### Can I use a self-signed certificate for my action URL? No, SSL certificates must be signed by a reputable certificate authority. You may want to consider using one of the following low-cost providers: - [Let's Encrypt](https://letsencrypt.org/) - [CloudFlare](https://www.cloudflare.com/ssl/) ## Web API ### Can I send JSON when using HTTP POST? Yes, the [Web API](/apis/web-api/) accepts both `application/x-www-form-urlencoded` POSTs as well as `application/json`. Refer to [POST bodies](/apis/web-api/#post_bodies) for more information. ### How is the Web API rate limited? Refer to our [rate limiting guide](/apis/web-api/rate-limits) for specific information on rate limits. ### How do I work with files? Refer to our [working with files guide](/messaging/working-with-files) for specific information on working with files. ### How do I find a channel's ID if I only have its #name? There are currently no methods to directly look up channels by name. Use the [`conversations.list`](/reference/methods/conversations.list) API method to retrieve a list of channels. The list includes each channel's `name` and `id` fields. Many developers keep the list of channels in memory for swifter lookups. Poll the method occasionally to refresh your inventory or keep it updated with the [Events API](/apis/events-api/). ### How do I find a channel's name if I only have its ID? You can use similar instructions to the question above, or you can use the [`conversations.info`](/reference/methods/conversations.info) API method to obtain a specific channel's information, including its `name`. ### Do channel IDs stay the same when the name of the channel changes? Channel IDs remain the same, even when names are changed. ### Do channel IDs stay the same when moving between public and private? As of [September 2018](https://docs.slack.dev/changelog/2018/09/01/more-reasons-to-be-a-conversations-api-convert), channel IDs remain static even when a channel is converted between public and private. Use the [Conversations API](/apis/web-api/using-the-conversations-api) to safely work with channels that have transitioned between public and private. ### How do I retrieve a single message? Use the [`conversations.history`](/reference/methods/conversations.history) API method and a token with the [`channels:history`](/reference/scopes/channels.history) scope to retrieve a specific message in a public channel. [Learn more about this approach](/messaging/retrieving-messages#individual_messages). ## Events API ### How do I re-enable event subscriptions for my app? If your app's subscriptions are disabled due to exceeding the Events API [failure limits](/apis/events-api/#failure_limits), manually re-enable them by visiting your [application's settings](https://api.slack.com/apps). If your app is part of the Slack Marketplace, use your **Live App Settings** instead of your development app. ### When should I use the Events API and when should I use Socket Mode or the legacy RTM API? Choose the [Events API](/apis/events-api/) if: 1. You want to precisely [scope](/reference/scopes) the data you receive to just what your app needs. 2. You prefer or must use an inbound request model due to one of the following: a) your hosting service is not able to maintain an outbound WebSocket connection, or b) you prefer to scale your application on an inbound request model instead of maintaining multiple long-lived WebSocket connections. 3. You're converting an [outgoing webhook](/legacy/legacy-custom-integrations/legacy-custom-integrations-outgoing-webhooks) integration into something installable as a Slack app. 4. You find the [retry behavior](/apis/events-api/#errors) reassuring for redundancy reasons. Choose [Socket Mode](/apis/events-api/using-socket-mode) if: 1. You're building an on-premise integration or have no ability to receive external HTTP requests. 2. You're working on a distributed or mobile application without a server backend. 3. You just prefer working with WebSockets. That's cool. 4. You want data feed redundancy by opening additional WebSocket connections. 5. You want messages to be delivered to you in real time. Finally, choose the legacy [RTM API](/legacy/legacy-rtm-api) _only_ if: 1. You have very specific needs that only the RTM API solves. 2. You already have a classic app, as they can longer be created. 3. You are okay with your app not working in the somewhat-near future, [as classic apps are slated to be deprecated.](/changelog/2024-09-legacy-custom-bots-classic-apps-deprecation) ### How do I make my bot appear active and present? The answer depends on whether you're using the Events API with or without the legacy RTM API: - With the Events API, you must toggle your presence by [managing your app](https://api.slack.com/apps)'s bot user config. - With the legacy RTM API, your bot is marked `active` while connected to a WebSocket. Therefore, the presence of the bot depends on whether you are using the legacy RTM API (the bot is online when it's connected through the WebSocket), or it's always online when you turn this setting on. Refer to [bot presence](/apis/web-api/user-presence-and-status#bot_presence) for more information. ## Socket Mode [Socket Mode](/apis/events-api/using-socket-mode) allows you to use the [Events API](/apis/events-api/) and [interactive features of the platform](/interactivity), without exposing a static HTTP endpoint to receive payloads. Instead, you use the WebSocket protocol and generate a URL at runtime. The legacy [RTM API](/legacy/legacy-rtm-api) is another way of connecting your application to Slack. For most applications that can't use a static HTTP endpoint, [Socket Mode](/apis/events-api/using-socket-mode) is preferred over RTM. ## Legacy RTM API ### Can I start using the RTM API? Most likely not. Classic apps can no longer be created, and the newer, granular permissions apps cannot access the RTM API. Try the [Events API](/apis/events-api/)! ### Can I keep using the RTM API? You can! But not forever. [Legacy classic apps are set to be deprecated November 2026](/changelog/2024-09-legacy-custom-bots-classic-apps-deprecation). Without those legacy apps, there will be no way to access the RTM API. Try the [Events API](/apis/events-api/) instead! ## App approvals ### How does my app get approved for the Slack Marketplace? Refer to the following guide: [Slack Marketplace review guide](/slack-marketplace/slack-marketplace-review-guide). ### What happens if I make changes to an application that has been approved for the Slack Marketplace? If you need to update your approved app to request new [OAuth scopes](/authentication/installing-with-oauth#asking) or to include new features, find your application's settings page at [https://api.slack.com/apps](https://api.slack.com/apps). Any changes you make here will not affect the published app. Once you're ready to apply these changes to the published app, you'll need to [resubmit it for review](/slack-marketplace/slack-marketplace-review-guide). ### What kind of changes to my app will require being reviewed again? If you've submitted your app to the Slack Marketplace but need to make changes to how your app or bot is described, to the integration types packed into your app, or to request additional permissions, you'll need your app to be reviewed again. ## App approvals ### How does my app get approved for the Slack Marketplace? Refer to the following guide: [Slack Marketplace review guide](/slack-marketplace/slack-marketplace-review-guide). ### What happens if I make changes to an application that has been approved for the Slack Marketplace? If you need to update your approved app to request new [OAuth scopes](/authentication/installing-with-oauth#asking) or to include new features, find your application's settings page at [https://api.slack.com/apps](https://api.slack.com/apps). Any changes you make here will not affect the published app. Once you're ready to apply these changes to the published app, you'll need to [resubmit it for review](/slack-marketplace/slack-marketplace-review-guide). ### What kind of changes to my app will require being reviewed again? If you've submitted your app to the Slack Marketplace but need to make changes to how your app or bot is described, to the integration types packed into your app, or to request additional permissions, you'll need your app to be reviewed again. --- # Source: https://docs.slack.dev/tools/deno-slack-sdk/guides/following-security-best-practices # Following security best practices ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. Keeping your apps and functions secure is an important part of developing on the Slack platform. Slack’s managed hosted environment is built on the [Deno](https://deno.land/) runtime, a secure JavaScript runtime. Learn more about Deno’s [permissions model](https://deno.land/manual@v1.32.1/basics/permissions). Here are some best practices to keep in mind when developing [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions), [workflows](/tools/deno-slack-sdk/guides/creating-workflows), and [triggers](/tools/deno-slack-sdk/guides/using-triggers) for Slack automations. ## Set appropriate access control levels (ACLs) - [Limit access](/tools/deno-slack-sdk/guides/managing-triggers#manage) to your [functions](/tools/deno-slack-sdk/guides/creating-custom-functions) and [triggers](/tools/deno-slack-sdk/guides/using-triggers) to only the intended audience. Use the `slack function access` or `slack trigger access` commands to control who can use your functions or trip your triggers. - Your app collaborators can deploy your functions and manage your workflows and triggers. Only add collaborators to your app that you trust. ## Validate input - It’s always important to validate inputs to your functions. If you’ve changed the distribution of your function, keep in mind it may be used in other workflows in ways you may not anticipate. Your app collaborators may also create or update triggers to start your workflows. - When using Slack [datastores](/tools/deno-slack-sdk/guides/using-datastores), avoid [injection attacks](https://owasp.org/Top10/A03_2021-Injection/) by properly sanitizing user input when building queries, and use the `expression_values` and `expression_attributes` fields when querying for data. Also ensure that the user has read access to data from the datastore before processing it. - Always confirm the user has access to perform whatever operation your function is being asked to perform. In complex workflows, several users may participate in the various steps, so ensure you’re checking the correct user’s permissions. For example, in a contract approval workflow, anyone may be able to request an approval, but only certain approvers may actually provide an approval. - When listening to [message metadata events](/tools/deno-slack-sdk/guides/integrating-message-metadata-events), keep in mind that many apps may be posting messages with the same event types. If you’d like to listen to messages from only specific apps, use a filter on the `app_id` in the event trigger definition. ## Handle sensitive data - Secrets needed by your custom functions running on Slack-managed infrastructure should be shared with Slack using the `slack env add` command and never hard-coded in your functions. Examples are API keys, OAuth client IDs and secrets, certificates, and cryptography keys. If possible, use Slack’s [third party auth support](https://docs.slack.dev/faq#third-party) to manage OAuth-based credentials. - For local apps using `slack run`, ensure that the `.env` file containing local secrets does not end up in your source control system. - When using `slack env add`, ensure the secret does not end up in your shell’s history. This can be done using shell environment variables, or by running `slack env add` without any parameters. With no parameters, `slack env add` will prompt you for the secret’s name and value in the console, using a password display. - Be careful about collecting or logging sensitive information in workflows from users, especially passwords or personally identifiable information (PII). Data may be exposed to later workflow steps, in data exports, or in activity logs. ## Secure credentials - The Slack CLI stores credentials in the `credentials.json` file in the `.slack` folder in your home directory. Slack will never ask you share the tokens contained in that file. - While these credentials expire and are regularly rotated, access to this file should be limited to only you. - Never share the tokens or challenge strings generated by the `slack login` flow. - Never paste a `/slackauthticket` command given to you by another user into Slack. ## Use secure libraries - It is your responsibility to monitor and respond to security vulnerabilities in your custom function’s code and dependencies, and to deploy new versions to Slack-managed infrastructure as needed. - Keep your Slack CLI and SDKs up to date by upgrading when prompted. - Only use a Slack CLI download by following instructions found within the [Slack CLI docs](/tools/slack-cli/). ## Handle network egress - Slack’s `outgoingDomains` configuration limits which domains your custom function code can use when making external network requests. Only list `outgoingDomains` if the domains are required by your functions. ## Make scopes and tokens - Functions are given a short-lived token that can be used to make [Slack API](/tools/deno-slack-sdk/guides/calling-slack-api-methods) calls, which use the scopes requested in the app’s manifest. We recommend only sending these tokens to Slack API endpoints, and not logging them or sending them to external systems. - Only request the scopes your functions need to do their job. Following these guidelines will get you on your way to building secure workflow apps. --- # Source: https://docs.slack.dev/tools/deno-slack-sdk/guides/getting-started # Source: https://docs.slack.dev/tools/bolt-python/getting-started # Source: https://docs.slack.dev/tools/bolt-js/getting-started # Quickstart with Bolt for JavaScript This quickstart guide aims to help you get a Slack app using Bolt for JavaScript up and running as soon as possible! When complete, you'll have a local environment configured with a customized [app](https://github.com/slack-samples/bolt-js-getting-started-app) running that responds to a simple greeting. ## Prerequisites A few tools are needed for the following steps. We recommend using the [**Slack CLI**](https://docs.slack.dev/tools/slack-cli/) for the smoothest experience, but other options remain available. ### Slack CLI Install the latest version of the Slack CLI to get started: - [Slack CLI for macOS & Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) - [Slack CLI for Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) Then confirm a successful installation with the following command: ```sh $ slack version ``` An authenticated login is also required if this hasn't been done before: ```sh $ slack login ``` ### Tooling for the Terminal - [Git](https://git-scm.com/downloads) - [Node.js](https://nodejs.org/en/download) Once installed, make sure recent versions are being used: ```sh $ git --version $ node --version ``` ### A Place to Belong A workspace where development can happen is also needed. We recommend using [developer sandboxes](/tools/developer-sandboxes) to avoid disruptions where real work gets done. ## Creating a Project With the toolchain configured, it's time to set up a new Bolt project. This contains the code that handles logic for your app. If you don’t already have a project, let’s create a new one! ### Slack CLI A starter template can be used to start with project scaffolding: ```sh $ slack create first-bolt-app --template slack-samples/bolt-js-getting-started-app $ cd first-bolt-app ``` After a project is created you'll have a `package.json` file for app dependencies and a `.slack` directory for Slack CLI configuration. A few other files exist too, but we'll visit these later. ### Terminal A starter template can be cloned to start with project scaffolding: ```sh $ git clone https://github.com/slack-samples/bolt-js-getting-started-app first-bolt-app $ cd first-bolt-app $ npm install ``` Outlines of a project are taking shape, so we can move on to running the app! ## Running the App Before you can start developing with Bolt, you will want a running Slack app. ### Slack CLI The getting started app template contains a `manifest.json` file with details about an app that we will use to get started. Use the following command and select "Create a new app" to install the app to the team of choice: ```sh $ slack run ... [INFO] bolt-app ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@first-bolt-app (local)` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ### Browser Navigate to your list of apps and [create a new Slack app](https://api.slack.com/apps/new) using the "from a manifest" option: 1. Select the workspace to develop your app in. 2. Copy and paste the `manifest.json` file contents to create your app. 3. Confirm the app features and click "Create". You'll then land on your app's **Basic Information** page, which is an overview of your app and which contains important credentials: ![Basic Information page](/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) To listen for events happening in Slack (such as a new posted message) without opening a port or exposing an endpoint, we will use [Socket Mode](/tools/bolt-js/concepts/socket-mode). This connection requires a specific app token: 1. On the **Basic Information** page, scroll to the **App-Level Tokens** section and click **Generate Token and Scopes**. 2. Name the token "Development" or something similar and add the `connections:write` scope, then click **Generate**. 3. Save the generated `xapp` token as an environment variable within your project: ```sh $ export SLACK_APP_TOKEN=xapp-1-A0123456789-example ``` The above command works on Linux and macOS but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). **Keep it secret. Keep it safe** Treat your tokens like a password and [keep it safe](/security). Your app uses these to retrieve and send information to Slack. A bot token is also needed to interact with the Web API methods as your app's bot user. We can gather this as follows: 1. Navigate to the **OAuth & Permissions** on the left sidebar and install your app to your workspace to generate a token. 2. After authorizing the installation, you'll return to the **OAuth & Permissions** page and find a **Bot User OAuth Token**: ![OAuth Tokens](/assets/images/bot-token-3d6c761238c7a66557fd08d00a2a1b0c.png) 3. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable: ```sh $ export SLACK_BOT_TOKEN=xoxb-example ``` After saving tokens for the app you created, it is time to run it: ```sh $ npm run start ... [INFO] bolt-app ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@BoltApp` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ## Updating the App At this point, you've successfully run the getting started Bolt for JavaScript [app](https://github.com/slack-samples/bolt-js-getting-started-app)! The defaults included leave opportunities abound, so to personalize this app let's now edit the code to respond with a kind farewell. ### Responding to a Farewell Chat is a common thing apps do and responding to various types of messages can make conversations more interesting. Using an editor of choice, open the `app.js` file and add the following message listener after the "hello" handler: ```js app.message('goodbye', async ({ say }) => { const responses = ['Adios', 'Au revoir', 'Farewell']; const parting = responses[Math.floor(Math.random() * responses.length)]; await say(`/${parting}!`); }); ``` Once the file is updated, save the changes and then we'll make sure those changes are being used. ### Slack CLI Run the following command and select the app created earlier to start, or restart, your app with the latest changes: ```sh $ slack run ... [INFO] bolt-app ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Terminal Run the following command to start, or restart, your app with the latest changes: ```sh $ npm run start ... [INFO] bolt-app ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Customizing App Settings The created app will have some placeholder values and a small set of [scopes](/reference/scopes) to start, but we recommend exploring the customizations possible on app settings. Open app settings for your app with the following command: ```sh $ slack app settings ``` This will open the following page in a web browser: ![Basic Information page](/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) Browse to [https://api.slack.com/apps](https://api.slack.com/apps) and select your app "Getting Started Bolt App" from the list. This will open the following page: ![Basic Information page](/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app! ## Adding AI Features Now that you're familiar with a basic app setup, try it out again, this time using the AI agent template! Get started with the agent template: ```sh $ slack create ai-app --template slack-samples/bolt-js-assistant-template $ cd ai-app ``` ### Terminal Get started with the agent template: ```sh $ git clone https://github.com/slack-samples/bolt-js-assistant-template ai-app $ cd ai-app $ npm install ``` Using this method, be sure to set the app and bot tokens as we did in the [Running the app](#running-the-app) section above. Once the project is created, update the `.env.sample` file by setting the `OPENAI_API_KEY` with the value of your key and removing the `.sample` from the file name. In the `ai` folder of this app, you'll find default instructions for the LLM and an OpenAI client setup. The `listeners` include utilities intended for messaging with an LLM. Those are outlined in detail in the guide to [Using AI in apps](/tools/bolt-js/concepts/ai-apps) and [Sending messages](/tools/bolt-js/concepts/message-sending). ## Next Steps Congrats once more on getting up and running with this quick start. ### Dive Deeper Follow along with the steps that went into making this app on the [building an app](/tools/bolt-js/building-an-app) guide for an educational overview. You can now continue customizing your app with various features to make it right for whatever job's at hand. Here are some ideas about what to explore next: - Explore the different events your bot can listen to with the [`event`](/tools/bolt-js/concepts/event-listening) method. See the full events reference documentation [here](/reference/events). - Bolt allows you to call [Web API](/tools/bolt-js/concepts/web-api) methods with the client attached to your app. There are [over 200 methods](/reference/methods) available. - Learn more about the different [token types](/authentication/tokens) and [authentication setups](/tools/bolt-js/concepts/authenticating-oauth). Your app might need different tokens depending on the actions you want to perform or for installations to multiple workspaces. - Receive events using HTTP for various deployment methods, such as deploying to [Heroku](/tools/bolt-js/deployments/heroku) or [AWS Lambda](/tools/bolt-js/deployments/aws-lambda). - Read up on [app design](/surfaces/app-design) and compose fancy messages with blocks using [Block Kit Builder](https://app.slack.com/block-kit-builder) to prototype messages. --- # Manage app approval for your workspace Apps connect third-party services to Slack, and by default, members can install them without approval from a Workspace Owner. If they'd like, Workspace Owners can [enable app approval](#h_01F29Z6B2ZN8PEXHG9N1GYDV6N) to pre-approve or restrict certain apps for their workspace. With app approval enabled, Workspace Owners can manage the following settings: - Allow members to [request apps](#h_01F29Z6B2ZN8PEXHG9N1GYDV6N) and [Workflow Builder connector steps](https://slack.com/help/articles/16749280664595-Manage-access-to-Slack-Workflow-Builder-connectors) that have not been pre-approved - Create custom rules to automate app requests - [Grant members permission](#h_01F29Z6HFHN7ARSCM4ABVF99C9) to manage app requests - Decide whether members can [sign in to other services](#h_01F29XF1TKT2JQJP2CJ19M4GJM) with their Slack accounts **Note:** Workspace Owners can also [set other permissions](https://slack.com/help/articles/1500009181142-Manage-app-settings-and-permissions) to manage how apps work in Slack, whether app approval is enabled or not. ## Manage app approval Workspace Owners can enable app approval to pre-approve and restrict certain apps for their workspace: 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **App Management Settings** in the left sidebar. 4. Click **Edit** next to **Require approved apps**. 5. Check the box next to **Only allow pre-approved apps**, then click **Save**. **Note:** If you're a Workspace Owner in an Enterprise organization, app approval will automatically be enabled for your workspace if an Org Owner has set an [app management policy](https://slack.com/help/articles/360038559694-Set-organization-level-policies-for-apps). ### Pre-approve or restrict apps When app approval is enabled, members can install and start using pre-approved apps right away. They cannot install or [request](#h_01GRSNHBF901Z8KBT5AFA7W01F) any apps you choose to restrict. #### Pre-approve apps 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **Browse** in the top right. 4. Search for and select an app. 5. From the app page, click **Approve**. Members can find pre-approved apps for your workspace from the [Pre-Approved category](https://my.slack.com/marketplace/category/approved) in the Slack Marketplace. #### Restrict apps 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **Browse** in the top right. 4. Search for and select an app. 5. From the app page, click **Restrict**. If an app you restrict has already been installed to your workspace, members can continue using it. You can [uninstall any app](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace) you don't want people to use. **Note:** When approving a request to install an app, you are approving the [scopes](https://api.slack.com/scopes) it will use to take actions in your workspace. An app's steps and workflows use the same scopes and can be added after an [internally developed app](https://api.slack.com/automation/create) is requested and approved. ## Choose how to manage app requests ### Allow members to request apps When app approval is enabled, you can allow members to request apps that haven't been pre-approved (as long as they're not restricted). Here's how: 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **App Management Settings** in the left sidebar. 4. Click **Edit** next to **Require approved apps**. 5. Check the box next to **Allow members to request apps for approval**. You can also require comments along with app requests. ### Create automation rules If you'd like, you can configure rules that automatically review app requests. Requests can be approved, restricted, dismissed, or flagged for human review based on conditions your rules look out for. To learn more about automation rules, [read our guide](https://slack.com/help/articles/9978438318227-Guide-to-automation-rules-for-app-approval), then follow the steps in [Configure automations for app approval](https://slack.com/help/articles/9487088123411-Configure-automations-for-app-approval). ### Select members to help manage app requests By default, any app requests that need review are sent to Workspace Owners via direct messages from Slackbot. If you'd like a larger group to help review app requests, you can appoint other members as app managers: 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **App Management Settings** in the left sidebar. 4. Click **Edit** next to **Require approved apps**. 5. Below **Select App Managers**, choose **Workspace Owners and selected members or groups**. Then, select specific members or [user groups](https://slack.com/help/articles/212906697-Create-a-user-group) from the drop-down menu. **Tip:** If you're using [automation rules](https://slack.com/help/articles/9978438318227-Guide-to-automation-rules-for-app-approval), you can create a rule to send app requests to a channel all of your app managers belong to for review. ## Manage Sign in with Slack permissions Some third-party services offer the option to [sign in to their website or app using your Slack account credentials](https://slack.com/help/articles/218891278-Connect-to-other-services-using-your-Slack-account). By default, members cannot sign up for or sign in to other services with their Slack accounts. To grant this permission, follow the steps below: 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **App Management Settings** in the left sidebar. 4. Click **Edit** next to **Require approved apps**. 5. Below **Sign in with Slack**, check the box to **Allow members to use their Slack account credentials to sign into 3rd party websites.** **Who can use this feature?** - **Workspace Owners** - Available on [**all plans**](https://slack.com/pricing) --- # Manage apps in an Enterprise organization Org Owners, Org Admins, and Integrations Admins can view and manage apps for their Enterprise organization from the **Integrations** section of the admin dashboard. ## How it works - View and install [certain apps](https://slack.com/marketplace/category/At01EB3C3VKK) at the org level, then add them to workspaces. - Approve apps for Workspace Owners to install when they’d like. - Restrict apps so that they cannot be installed to workspaces on your org. **Note:** Apps using the [admin](https://api.slack.com/admins), [Discovery](https://slack.com/help/articles/360002079527-A-guide-to-Slacks-Discovery-APIs), or [SCIM](https://api.slack.com/scim) APIs can access the data they need in an org once they’re installed at the org level. They don’t need to be explicitly added to any workspaces. ## View apps in your org Use the **Integrations** section of the admin dashboard to see apps across workspaces in your org. Select **Installed apps** to see org-level and workspace-level app installations, along with the following information: | **Installed on** | If an app is installed to one workspace, you’ll see the workspace name. If an app is installed to more than one workspace, you’ll see the total number of workspaces. Click on an app’s name to see a full list of workspaces it’s installed to, when it was installed, and who installed it. | | --- | --- | | **Source** | The source tells you where an app originated. Apps can be from the **[Slack Marketplace](https://slack.com/marketplace)**, **Internal** if built by someone in your organization, or **Distributed** if a developer hasn't submitted it to the Slack Marketplace for review. | | **Access level** | An app’s access level tells you how it’s been installed. Apps are installed at either the **Organization** or **Workspace** level. | | **App resolution** | This tells you if an app is available to your org. **Approved** apps can be installed to any workspace, and **Restricted** apps can’t be. Apps with a **Set by workspace** policy can be approved or restricted by individual Workspace Owners. | **Tip:** To export a list of apps installed across your org from the admin dashboard, click **Export CSV** in the top-left corner of the **Installed Apps** section. ## Install an app at the org level ### Step 1: Choose and install an app 1. From your desktop, click your organization name in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Integrations_**. 4. Click **Manage Apps** in the top right, then select **Install an app**. 5. Search for and select the app you’d like to install. 6. Click **Continue**. Depending on the app you’re installing, you may be prompted to complete additional steps before proceeding. 7. Click **Allow** to grant the app access to your org. Slackbot will send a [direct message (DM)](https://slack.com/help/articles/212281468-Understand-direct-messages) to all Org Owners and Org Admins letting them know that the app has been installed. Once you’ve granted the app access to your org, you can return to the admin dashboard to add the app to workspaces. **Note:** If you install an app at the org level that has already been added to workspaces, members of those workspaces can continue using it without interruption. ### Step 2: Add an app to workspaces 1. From the **_Integrations_** section of the admin dashboard, click the **Installed Apps** tab. 2. Find the app you’d like to add to workspaces. 3. Click the **_three dots icon_** to the right of the app. 4. Select **Add to more workspaces**. 5. Check the box next to any workspaces you’d like to add the app to. To automatically add the app to any new workspaces created in your org, check the box next to **Default for future workspaces**. 6. Click **Next**. 7. Check the box next to **I’m ready to add this app**. 8. Click **Add App**. Slackbot will send a DM to all Org Owners and Org Admins when the app has been added to the workspaces you selected. Once an app has been added to workspaces, members can connect their accounts to use it. ## Approve or restrict an app at the org level ### Approve an app for your org 1. From your desktop, click your organization name in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Integrations_**. 4. Click **Manage Apps** in the top right, then select **Approve an app**. 5. Search for and select the app you’d like to approve. 6. Review the app’s scopes, then click **Approve**. **Tip:** To undo this action, click **Resolutions** in the admin dashboard then view the **Approved Apps** tab. Click the **_three dots icon_** to the right of the app and select **Unapprove app**. ### Restrict an app for your org Restricting an app will not remove any existing installations of the app from workspaces in your org. A Workspace Owner or [app manager](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#appoint-app-managers) will need to [remove the app](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace#remove-an-app) from their workspace. 1. From your desktop, click your organization name in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Integrations_**. 4. Click **Manage Apps** in the top right, then select **Restrict an app**. 5. Search for and select the app you’d like to restrict. 6. Click **Restrict**. **Tip:** To undo this action, click **Resolutions** in the admin dashboard then view the **Restricted Apps** tab. Click the **_three dots icon_** to the right of the app and select **Unrestrict app**. ## Manage app requests at the org level If an app’s developer changes the scopes of an app after it was approved or restricted for your org, members may need to request the app again so you can review the new scopes. App requests will be sent to Org Owners and Org Admins in a DM from Slackbot. To review requests, follow the steps below: 1. When you receive a request, open your direct message with Slackbot. 2. Review the request. Select **Approve for Organization** or **Restrict for Organization**. Choosing **Restrict for Organization** will prevent all members from installing the app. ![An app review request in a message from Slackbot.](https://slack.zendesk.com/hc/article_attachments/32814972431251) When a request is approved or denied, Slack will update the original request message so all admins can see the status. If you decide to restrict an app’s new scopes, members can continue using the existing version of the app, but cannot install or use the updated version. **Tip:** Org Owners and Org Admins can view and manage app upgrade requests from the **Requests** tab in the **Integrations** section of the admin dashboard, where you can also configure [automations for app requests](https://slack.com/help/articles/9487088123411-Configure-automations-for-app-approval). ## Remove or uninstall an app There are two options for removing apps installed at the org level: - Remove the app from workspaces that no longer need to use it. - Uninstall the app from your org to remove it from all workspaces. **Note:** Apps that are not installed at the org level cannot be removed from workspaces or uninstalled from the admin dashboard. A Workspace Owner or app manager will need to [remove the app](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace#remove-an-app). ### Remove an app from a workspace 1. From your desktop, click your organization name in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Integrations_**, then select **Installed Apps**. 4. Click the **_three dots icon_** to the right of the app you’d like to remove. 5. Select **Remove from a workspace**. 6. Check the boxes next to any workspaces you’d like to remove the app from. 7. Click **Next**. 8. Check the box next to **I’m ready to remove this app**, then click **Remove App**. Slackbot will send a DM to all Org Owners and Org Admins when the app has been removed from the workspaces you selected. ### Uninstall an app from your org 1. From your desktop, click your organization name in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Integrations_**, then select **Installed Apps**. 4. Click the **_three dots icon_** to the right of the app you’d like to uninstall. 5. Select **Uninstall from your org**. 6. Check the box next to **I want to uninstall this app from my org**, then click **Uninstall**. Slackbot will send a DM to all Org Owners and Org Admins when the app has been uninstalled from your org. **Who can use this feature?** - **Org Owners**, **Org Admins**, and members with the **Integrations Admin** [system role](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack#system-roles) - Available on **Enterprise** plans --- # Manage app requests for your workspace If [app approval](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace) is turned on for a workspace, members have the option to request apps and workflow [connector steps](https://slack.com/help/articles/20155812595219-Slack-connectors-for-Workflow-Builder) they’d like to use in Slack. By default, only Workspace Owners can review app requests, but they can also allow other members to do so by [appointing them as app managers](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#appoint-app-managers). **Tip:** Workspace Owners can use [app approval automations](https://slack.com/help/articles/9487088123411-Configure-automations-for-app-approval) to approve app requests based on a series of pre-determined conditions. ## What to expect - App requests are sent to all Workspace Owners and app managers. Depending on a workspace's settings, requests may be delivered via direct messages from Slackbot or routed to a channel. - Workspace Owners and app managers can approve apps for all members of a workspace to use, or restrict them. - Members may need to request apps already installed to a workspace if the app’s developer changes the scopes. ## Review app requests App requests will include the name of the app, the requester, a list of the [permissions (or scopes)](https://slack.com/help/articles/115003461503-Understand-app-permissions) the app can access in Slack if it’s approved for use, and additional comments if available. To review requests, follow the steps below: 1. When you receive a request, open your direct message with Slackbot, or the channel that requests are sent to. 2. Review the request. Select **Approve for Workspace** or **Restrict for Workspace**. Choosing **Restrict for Workspace** will prevent all members from requesting or installing the app. ![Direct message from Slackbot with an app request, including the app details and buttons for approving or restricting the app for your workspace](https://slack.zendesk.com/hc/article_attachments/32816142481427) When the status of a request is changed, Slack will update the original request message to reflect the action for all app managers to see. **Tip:** Workspace Owners and app managers can also approve, restrict, or cancel any pending requests from the **Requests to install** tab on the [Apps page](https://app.slack.com/apps-manage) in the Slack Marketplace. ## Apps and scopes Scopes are a [set of permissions](https://slack.com/help/articles/115003461503-Understand-app-permissions) that govern what an app can do and access when installed to a Slack workspace. If an app’s developer changes the scopes of an app after it was installed to your workspace, members may need to request the app again so that someone with permission can review the new scopes. If an app manager restricts an app’s new scopes, members can continue using the existing version of the app, but cannot install or use the updated version. **Note:** In an Enterprise organization, [org-level app requests](https://slack.com/help/articles/360000281563-Manage-apps-in-an-Enterprise-organization#manage-app-requests) for apps with scope changes will be sent to Org Owners and Org Admins in a DM from Slackbot. ### Who can use this feature? - **Workspace Owners** and **members** with permission to manage apps - Available on [**all plans**](https://slack.com/pricing) --- # Set organization-level policies for apps By default, members of an Enterprise organization can [install any app](https://slack.com/help/articles/202035138-Add-apps-to-your-Slack-workspace) to workspaces they belong to. Org Owners can set policies that apply to all workspaces in their organization to manage app installation and use. ## What to expect * Setting an app management policy turns on [app approval](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#manage-app-approval) for every workspace in an org. When app approval is enabled, members can only use apps that have been approved for their workspaces. * Org Owners can [approve or restrict apps](https://slack.com/help/articles/360000281563-Manage-apps-in-an-Enterprise-organization) for their entire org, but Workspace Owners and [app managers](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#appoint-app-managers) will be responsible for reviewing app requests for workspaces they manage. * Org Owners can also set org policies to limit members to installing apps from the Slack Marketplace and determine whether Multi-Channel Guests can use [shortcuts](https://slack.com/help/articles/360057554553-Use-shortcuts-to-take-actions-in-Slack). ## Set an app management policy for your org Follow the steps below to turn on app approval for all workspaces in your org: 1. From your desktop, click your **organization name** in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Settings_**, then select **Organization Policies**. 4. Click the **Apps** tab at the top of the page. 5. Next to **App Management**, click **Add Policy**. 6. Check the box next to **Require App Approval**. 7. Select **Save Policy**. Then, click **Create Policy**. **Note:** If you don’t set an app management policy for your org, Workspace Owners can still choose to enable app approval for workspaces they manage. ### Manage Sign in with Slack permissions Some third-party apps offer the option to sign in to their service with Slack account credentials. By default, Workspace Owners can choose whether members can [sign in to other services with their Slack account](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#sign-in-with-slack). If an app management policy has been set, Org Owners can remove Workspace Owners' ability to manage [Sign in with Slack permissions](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#sign-in-with-slack) and decide if apps with the [Sign in with Slack identity scope](https://api.slack.com/docs/sign-in-with-slack) require approval: 1. From your desktop, click your **organization name** in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Settings_**, then select **Organization Policies**. 4. Click the **Apps** tab at the top of the page. 5. Next to App Management, click **Add Policy**. If there’s already an app management policy in place, click the **_pencil icon_** to choose your **Sign in with Slack** permissions. 6. Under **People who can manage Sign in with Slack restrictions**, select **Org Owners** from the drop-down menu. 7. Check or uncheck the box next to **Don’t require pre-approval for Sign in with Slack Apps**. 8. Select **Save Policy**. Then, click **Create Policy**. ## Set other app installation policies Org Owners can also choose to set two other app installation policies, whether app approval has been turned on for all workspaces in their org or not: * **Slack Marketplace installations**: Only allow members to install apps from the [Slack Marketplace](https://slack.com/marketplace). * **Guest app use restrictions**: Allow Multi-Channel Guests to use [slash commands](https://slack.com/help/articles/201259356) and [app shortcuts](https://slack.com/help/articles/360004063011) in channels they belong to. 1. From your desktop, click your **organization name** in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **_Settings_**, then select **Organization Policies**. 4. Click the **Apps** tab at the top of the page. 5. Next to the app policy you’d like to set, click **Add Policy**. 6. Check the box next to the policy description. 7. Select **Save Policy**. Then, click **Create Policy**. **Who can use this feature?** * **Org Owners** and **Org Admins** * Available on **Enterprise** plans --- # Set up and manage Agentforce in Slack Agentforce makes it possible for an organization to build custom agents that handle specific aspects of their work. When you deploy Agentforce in Slack, your team can collaborate with agents right where they’re already getting work done. ## How it works - [Build and customize agents](#build-and-customize-agents) in Salesforce, then [add them to Slack](#add-agents-to-slack) to make them available to your members. - Once they’ve been added to Slack, members can [find and message agents](https://slack.com/help/articles/36218786859667-Use-Agentforce-in-Slack/) they have access to in the **Agentforce** tab or [message them in channels](https://slack.com/help/articles/36218786859667-Use-Agentforce-in-Slack#chat-with-an-agent-in-a-channel). **Learn more about Agentforce:** [Visit our launch guide](https://slack.com/resources/collections/launching-agentforce-in-slack) or [contact your Slack Account Executive](https://slack.com/ai-agents/contact-sales). ## Build an agent in Salesforce Use the guidance below to get started with [creating an agent](https://help.salesforce.com/s/articleView?id=ai.agent_setup_create.htm&type=5) using Agentforce Builder in Salesforce: - Create an agent using [pre-made templates](https://help.salesforce.com/s/articleView?id=ai.agent_employee_agent_setup.htm&type=5) for Slack. - Customize your agent with [topics](https://help.salesforce.com/s/articleView?id=ai.copilot_topics.htm&type=5) and [actions](https://help.salesforce.com/s/articleView?id=ai.copilot_actions.htm&type=5) to define its scope and expertise. - Add the **General Slack Actions** topic to your agent to choose from a set of [Slack actions](https://help.salesforce.com/s/articleView?id=ai.copilot_actions_ref.htm&type=5) like [creating a canvas](https://help.salesforce.com/s/articleView?id=ai.copilot_actions_ref_slack_create_canvas.htm&type=5) (not available on the [free version of Slack](https://slack.com/help/articles/27204752526611-Feature-limitations-on-the-free-version-of-Slack)), [performing a search](https://help.salesforce.com/s/articleView?id=ai.copilot_actions_ref_slack_search.htm&type=5), and more. **Note:** You can only build agents for Slack using the Agentforce [Employee Agent type](https://help.salesforce.com/s/articleView?id=ai.agent_setup_explore_types.htm&type=5). ### Agent templates for Slack Agent templates allow you to quickly create an agent to handle common tasks. When [creating an agent from a template](https://help.salesforce.com/s/articleView?id=ai.agent_employee_agent_setup.htm&type=5), search for **Slack** to view the available templates. There are three agent templates available for Slack: - **Customer Insights Agent** Uses Salesforce data to summarize customer information, find subject matter experts in Slack, and generate customer briefs. - **Employee Help Agent** Resolves internal issues by answering frequently asked questions using internal resources and conversations in Slack. - **Onboarding Agent** Helps onboard new team members by creating onboarding canvases and answering frequently asked questions from custom knowledge bases. ## Connect Salesforce and Slack To set up Agentforce in Slack, connect your Salesforce organization to Slack. You’ll need help from an [admin in Salesforce](https://help.salesforce.com/s/articleView?language=en_US&id=xcloud.basics_understanding_administrator.htm&type=5) to complete this process. ### Step 1: Connect a Salesforce org to Slack 1. Follow the steps in our [Connect Salesforce and Slack](https://slack.com/help/articles/30754346665747-Connect-Salesforce-and-Slack) guide. 2. Once your Salesforce org is connected, you’ll need to manually map users if they haven’t already been granted access to Salesforce in Slack. ### Step 2: Install the Slack connected app 1. From Salesforce, select **Setup**. 2. In the Quick Find box, search for and select **Connected Apps OAuth Usage**. 3. Scroll down to **Slack**, then select **Install** on the right. 4. Click **Install** to finish. **Note:** People in Slack that don’t have a Salesforce account will need a provisional Salesforce license to access Agentforce in Slack. Reach out to your Salesforce Account Executive to learn more. ### Step 3: Map accounts Connect your members’ Salesforce and Slack accounts. When you manually map members in Slack, they’ll be prompted to sign in to Salesforce to connect their accounts. #### Pro and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Workspace settings** from the menu, then click **Salesforce**. 3. Click the **Users** tab. 4. Select **Add individually** and search for the member you’d like to add. To add members in bulk, click **Add by CSV** and follow the prompts. #### Enterprise plans 1. From **Home**, click your organization name in the sidebar. ![Image 1](https://a.slack-edge.com/8e8e4/helpcenter/img/workspace-picker@2x.jpg) 2. Hover over **Tools & settings**, then click **Organization settings**. 3. Click **Salesforce**, then select **Salesforce organizations**. 4. Click the **Users** tab. 5. Select **Add individually** and search for the member you’d like to add. To add members in bulk, click **Add by CSV** and follow the prompts. **Tip:** Members with the [Salesforce admin system role](https://slack.com/help/articles/360018112273-Types-of-roles-in-Slack#system-roles) in Slack can connect Salesforce orgs and map accounts. ## Add an agent to Slack Now that Salesforce and Slack are connected, you’re ready to add agents. Keep in mind that member access for Employee Agents is [assigned automatically based on permissions in Salesforce](https://help.salesforce.com/s/articleView?id=ai.agent_manage_aea_access.htm&type=5). If you're installing an [Agentforce Service Agent](https://help.salesforce.com/s/articleView?id=service.service_agent_overview.htm&type=5), be sure to [assign member access](#assign-member-access) when installation is complete. ### Step 1: Create an agent connection First, establish a connection to Slack for your agent in Salesforce: 1. Sign in to Salesforce, then select **Setup**. 2. In the **Quick Find** box, search for and select **Agents**. 3. Select an agent. 4. Click the **Connections** tab. 5. Click **Add**. 6. Below **Connection**, select **API** from the drop-down menu. 7. Enter a unique **Integration Name**. 8. Below **Connected App**, select **Slack**. 9. Click **Save**. ### Step 2: Install an agent Once you’ve established a connection for your agent, add it to Slack. #### Pro and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Manage Agentforce** from the menu. 3. Next to the agent you'd like to add, click **Review agent**. 4. Review the permissions the agent will have in Slack, then click **Install Agent**. #### Enterprise plans First, install and grant the agent access at the org level. Then, you can add the agent to specific workspaces in your org. 1. From **Home**, click your **organization name** in the sidebar. ![Image 2](https://a.slack-edge.com/8e8e4/helpcenter/img/workspace-picker@2x.jpg) 2. Hover over **Tools & settings**, then click **Organization settings**. 3. Click **Salesforce**, then select **Agentforce**. 4. Next to the agent you’d like to add, click **Review Agent**. 5. Review the permissions the agent will have in Slack, then click **Install Agent**. 6. Check the box next to the workspace(s) the agent should be available in. 7. Click **Add to Workspaces**. ## Manage Agentforce agents in Slack You can manage agents in Slack by editing their profile, assigning member access, and uninstalling them. ### Edit an agent’s profile Owners, admins, Agent Builders, and assigned Agent Managers can edit an agent’s profile right in Slack. To change the profile picture, adjust suggested prompts, or assign additional agent managers, follow the steps below: 1. From your desktop, click **Agentforce** in the sidebar. If you don’t see **Agentforce**, click **More** to find it. 2. Click **Managed by you**. 3. Next to an agent, click the **three dots icon**, then select **View Agent Profile**. 4. Click **Edit**. 5. Edit the profile fields you’d like to change, then click **Save**. ### Assign access to a Service Agent By default, no one can use [Agentforce Service Agents](https://help.salesforce.com/s/articleView?id=service.service_agent_overview.htm&type=5) in Slack until they’re assigned access by an owner or admin. #### Pro and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Manage Agentforce** from the menu. 3. Click **Installed agents** at the top of the page. 4. Next to an agent, click **Manage Agent**. 5. Next to **Who can use this agent?**, click **Edit**. 6. Choose who can access the agent, then click **Save**. #### Enterprise plans 1. From **Home**, click your **organization name** in the sidebar. ![Image 3](https://a.slack-edge.com/8e8e4/helpcenter/img/workspace-picker@2x.jpg) 2. Hover over **Tools & settings**, then click **Organization settings**. 3. Click **Salesforce**, then select **Agentforce**. 4. Next to the agent you’d like to add, click **Review Agent**. 5. Review the permissions the agent will have in Slack, then click **Install Agent**. 6. Check the box next to the workspace(s) you’d like to remove the agent from and click **Next**. 7. Check the box next to **I’m ready to remove this agent**, then select **Remove agent**. ### Remove or uninstall an agent On the Pro and Business+ plans, you can uninstall an agent. On Enterprise plans, you can remove an agent from specific workspaces, or uninstall it from your organization. #### Pro and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Manage Agentforce** from the menu. 3. Click **Installed agents** at the top of the page. 4. Next to an agent, click **Manage Agent**. 5. Click **Manage** in the top-right corner, then select **Remove [agent name]**. ### Remove an agent from a workspace 1. From **Home**, click your **organization name** in the sidebar. ![Image 4](https://a.slack-edge.com/8e8e4/helpcenter/img/workspace-picker@2x.jpg) 2. Hover over **Tools & settings**, then click **Organization settings**. 3. Click **Salesforce**, then select **Agentforce**. 4. Click **Installed agents** at the top of the page, then click **Manage agent** next to the agent you'd like to remove. 5. Select **Manage** in the top right, then click **Remove from a workspace**. 6. Check the box next to the workspace(s) you’d like to remove the agent from and click **Next**. 7. Check the box next to **I’m ready to remove this agent**, then select **Remove agent**. ### Uninstall an agent from your org 1. From **Home**, click your **organization name** in the sidebar. ![Image 5](https://a.slack-edge.com/8e8e4/helpcenter/img/workspace-picker@2x.jpg) 2. Hover over **Tools & settings**, then click **Organization settings**. 3. Click **Salesforce**, then select **Agentforce**. 4. Click **Installed agents** at the top of the page, then click **Manage agent** next to the agent you'd like to uninstall. 5. Select **Manage** in the top right, then click **Uninstall from your organization**. 6. Check the box next to **I’m ready to remove this agent**, then click **Remove agent**. **Who can use this feature?** - **Workspace Owners** / **Admins** (Free, Pro, and Business+ plans) **Org Owners** / **Admins** (Enterprise plans) - Available on [**all Slack plans**](https://slack.com/pricing) with a Salesforce [Agentforce](https://www.salesforce.com/agentforce/) license --- # Configure automations for app approval By default, members can install apps without approval from a Workspace Owner, but you can choose to [approve and restrict](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace) apps on a case by case basis, or you can automate the process by configuring rules so that apps that meet your assigned criteria are automatically approved. **Note**: We recommend developing and testing these features in a testing environment before using the functionality in production. ## Before getting started - Review the [Guide to automation rules for app approval](https://slack.com/help/articles/9978438318227-Guide-to-automation-rules-for-app-approval) to familiarize yourself with the outcomes of each rule. - [Rate and review scopes](#h_01GHY35SHQ1Q8D2G0WGD1GEEDA) and their risk levels to use them in a rule. ## Create a rule You can create rules based on a chain of comparisons for each app request to be checked against. Any app that meets the conditions of your rule will be automatically approved or restricted based on the resolution you specify. ### Free, Pro, and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **Requests** in the left sidebar, then select the **Automation rules** tab. If you don't see **Requests**, make sure [app approval](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace) is enabled for your workspace. 4. At the top of the list, select **Create a rule**, then give your rule a name and add a description. 5. Choose if **all** conditions need to match, or **any** single condition. 6. Choose what condition you’d like the rule to look for from the drop-down menu. You can also choose a comparison from the following drop-down menu, if you need to. 7. To add additional conditions, click **Add new condition.** 8. Choose to **Approve, Deny, Dismiss** or **Restrict** an app that meets the conditions. 9. If you'd like, select who to notify about the resolution and include a message to send the requestor. 10. Click **Save**. ### Enterprise plans 1. From your desktop, click your **organization name** in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **Integrations**, then click **Requests** and select the **Automation Rules** tab. 4. At the top of the list, select **Create a rule**, then give your rule a name and add a description. 5. Choose if **all** conditions need to match, or **any** single condition. 6. Choose what condition you’d like the rule to look for from the drop-down menu. You can also choose a comparison from the following drop-down menu, if you need to. 7. To add additional conditions, click **Add new condition.** 8. Choose to **Approve, Deny, Dismiss** or **Restrict** an app that meets the conditions. 9. If you'd like, select who to notify about the resolution and include a message to send the requestor. 10. Click **Save**. **Tip**: Rules you create will not be enabled until you [activate them](#h_01GDBJRP4FM0PDTJJKME94DRZ4). ## Manage rules ### Free, Pro, and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **Requests** in the left sidebar. 4. Click **Automation rules** to view a list of your existing rules, then click the **three dots icon** next to the rule you’d like to **Activate**, **Pause**, **Edit**, or **Remove**. ### Enterprise plans 1. From your desktop, click your **organization name** in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **Integrations**, then click **Requests**. 4. Click **Automation Rules** to view a list of your existing rules, then click the **three dots icon** next to the rule you’d like to **Activate**, **Pause**, **Edit**, or **Remove**. **Note**: Removing a rule will not undo previous requests that were resolved by this rule. Removing a rule cannot be undone, and you'll need to recreate it from scratch. Proceed with caution! ## Reorder rules The order of the rules in the list is relevant to your automation, since a requested app will be resolved at the first matching rule. If you have multiple rules, you can reorder the list if you determine a rule should take priority over another. ### Free, Pro, and Business+ plans 1. From your desktop, click **Admin** in the sidebar. 2. Select **Apps and workflows** from the menu to open the Slack Marketplace. 3. Click **Requests** in the left sidebar. 4. Click **Automation rules** to view a list of your existing rules, then click **Reorder list**. 5. Using the available actions, choose if you’d like to move the rule up, down, to the top, or bottom of the automation rules list, then click **Save**. ### Enterprise plans 1. From your desktop, click your **organization name** in the sidebar. 2. Hover over **Tools & settings**, then click **Organization settings**. 3. From the left sidebar, click **Integrations**, then click **Requests**. 4. Click **Automation Rules** to view a list of your existing rules, then click **Reorder rules**. 5. Using the available actions, choose if you’d like to move the rule up, down, to the top, or bottom of the automation rules list, then click **Save**. **Note**: To apply the same rating to multiple scopes, select all the desired scopes then click the **Rate as high risk**, **Rate as medium risk**, or **Rate as low risk** action at the top of the scope list. **Who can use this feature?** - **Workspace Owners/Admins, Org Owners**/**Admins**, and **members** with [permission to manage apps](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#choose-how-app-requests-work) - Available on [**all plans**](https://slack.com/pricing) **Awesome!** Thanks so much for your feedback! If you’d like a member of our support team to respond to you, please send a note to [feedback@slack.com](mailto:feedback@slack.com). **Got it!** If you’d like a member of our support team to respond to you, please send a note to [feedback@slack.com](mailto:feedback@slack.com). **Was this article helpful?** - Yes, thanks! - Not really **Sorry about that! What did you find most unhelpful?** - This article didn’t answer my questions or solve my problem - I found this article confusing or difficult to read - I don’t like how the feature works - Other **Tip**: To apply the same rating to multiple scopes, select all the desired scopes then click the **Rate as high risk**, **Rate as medium risk**, or **Rate as low risk** action at the top of the scope list. **Submit article feedback** If you’d like a member of our support team to respond to you, please send a note to [feedback@slack.com](mailto:feedback@slack.com). --- # Guide to automation rules for app approval When setting up [automated app approvals](https://slack.com/help/articles/9487088123411-Configure-automations-for-app-approval) for your organization, it's important to proceed with care and ensure that your rules meet any unique [security requirements](https://slack.com/help/articles/360001670528-Security-recommendations-for-approving-apps) established by your team. Read on for an overview of the components that make up rules and how to apply them. **Note:** We recommend testing these features in a separate testing environment before implementing them in production. For additional support, you can [contact us](https://slack.com/help/requests/new) at any time. ## How it works App installation requests can be automatically approved, restricted, dismissed, or flagged for human review based on conditions that your rules will look out for. Rules can be comprised of several rule components, which will be evaluated in the order that you determine. If the requested app meets the requirements of the rule, your predetermined resolution will be automatically applied. ## Terms to know ### Rule component Components are what a rule looks out for to determine an automated outcome. | Available components | | --- | | Scopes | Previous resolution | App distribution | App IDs | ### Conditions Conditional statements modify how the component and comparison interact. | Available conditions | | --- | | Is | Is not | ### Comparisons Comparisons are the state of the rule component. Each component has its own set of available comparisons. | Available comparisons | | --- | | Includes | Is empty | Approved | Restricted | Unresolved | | Internal app | Slack Marketplace approved | Specific app ID | ### Resolutions Resolutions determine how you'd like to action a requested app that contains all the elements of a rule. | Available resolutions | | --- | | Restrict | Approve | Cancel | Review | ### Rules The available components, conditions and comparisons are constructed into a conditional statement with a resolution, known as a rule: | If any or all Component + Condition + Comparison then Resolution = Restrict Approve Cancel Review | | --- | | Scope Requested | | Scopes Requested refers to all the scopes present in any requested app. | | **Comparison** | **Rating list** | | Includes any of those in | Low risk list | | Includes only those in | Medium risk list | | Is empty | High risk list | | Is not empty | Unrated list | | **Condition** | **Comparison** | | Is | Approved | | Is | Restricted | | Is | Unresolved | | Previous resolution is | | Previous resolution is not | | Previous resolution is approved, restrict | | --- | | **Condition** | **Comparison** | | Is | Approved | | Is | Restricted | | Is | Unresolved | | **Condition** | **Comparison** | | Is not | Approved | | Is not | Restricted | | Is not | Unresolved | | "If previous resolution is approved, approve" | | App distribution is | | --- | | App distribution is internal | | App distribution is Slack Marketplace approved | | **Condition** | **Comparison** | | Is | An internal app | | Is | Slack Marketplace approved | | **Condition** | **Comparison** | | Is not | An internal app | | Is not | Slack Marketplace approved | | "If app requested is an internal app, send for review" | | App ID is | | --- | | App ID is a specific app ID | | **Condition** | **Comparison** | | Is | A specific app ID | | "If app ID is [any app ID], cancel" | ## Resolutions When a requested app meets all the conditions of a rule, it will be resolved based on the set resolution and the requestor will be notified. - **Restrict**: App cannot be installed and cannot be requested again unless the scopes change. - **Approve**: App will be installed. - **Cancel**: Dismiss the request without making a decision. A new request can be made anytime. - **Review**: App will be sent to a human for review and approval. **Who can use this feature?** - **Workspace/Org Owners**, **Workspace/Org Admins** and **members** with [permission to manage apps](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace#choose-how-app-requests-work) - Available on [**all plans**](https://slack.com/pricing) **Awesome!** Thanks so much for your feedback! If you’d like a member of our support team to respond to you, please send a note to [feedback@slack.com](mailto:feedback@slack.com). **Got it!** If you’d like a member of our support team to respond to you, please send a note to [feedback@slack.com](mailto:feedback@slack.com). **Was this article helpful?** - Yes, thanks! - Not really **Sorry about that! What did you find most unhelpful?** - This article didn’t answer my questions or solve my problem - I found this article confusing or difficult to read - I don’t like how the feature works - Other **Submit article feedback** If you’d like a member of our support team to respond to you, please send a note to [feedback@slack.com](mailto:feedback@slack.com). --- # Slack platform overview [![Slack Developer Docs](https://docs.slack.dev/img/logos/slack-developers-white.png)](https://docs.slack.dev/) ## More doing, less reading Hello there, fellow developer! 👋 Welcome to the Slack API documentation, the place where ideas turn into interactive apps, workflows get automated, and Slack becomes the platform that powers your workday. **With new tools for building AI agents and intelligent apps,** our documentation on APIs, SDKs, and tools can assist you in creating apps that make work life simpler, more pleasant and more productive. **The Slack developer platform revolves around Slack apps.** Which brings us to... ## What is a Slack app? A Slack app is a tool or integration that extends the functionality of Slack: it adds new features, automates tasks, integrates with external services, or enhances the user experience. A Slack app allows you to do more within Slack than just chat. With the Slack platform, individual and enterprise developers alike can create apps that integrate directly with the tools teams already use, whether that's connecting a CRM, managing project boards, or sending automated alerts. We know our platform is deep and wide, and possibly a little intimidating as a result. It's okay to not know where to start. - **If you want to take it slow**, [this guide on designing your app](https://docs.slack.dev/surfaces/app-design) is a little light reading on how to define the look and feel of your app. - **If you'd rather stop the chitchat and get into it**, build an app with the [Quickstart](https://docs.slack.dev/quickstart) guide. If you're just looking to get a token to call the Web API methods, completing the first three steps of [this guide](https://docs.slack.dev/app-management/quickstart-app-settings) will get you there. ✨ Our [sample apps and tutorials](https://docs.slack.dev/samples) are also particularly useful for those floating aimlessly, as they utilize our [Bolt framework and SDK](https://docs.slack.dev/tools). No matter what you try to do, we'll be right beside you. ### The path of app creation There are three high-level steps to creating a Slack app: 1. **Create an app** using the [CLI](https://docs.slack.dev/tools/slack-cli/) or the [app settings](https://api.slack.com/apps) page. Then, decide which scopes your app needs and get tokens in return. 2. **Code the logic of your app**—which [APIs](https://docs.slack.dev/apis) your app will use, events it will respond to, which actions it will take, etc.—in the code editor of your choice. We recommend VS Code and using the [Bolt](https://docs.slack.dev/tools) framework (a Slack-created open source framework for JavaScript, Python, or Java) to make things easier. 3. **Deploy your app** locally to test it. Then, look into [distribution](https://docs.slack.dev/app-management/distribution) and [authentication](https://docs.slack.dev/authentication). Along the way, you can decide to use different surfaces, methods, and blocks that make up the visual structure of your app. ### Go deeper #### Build AI-Powered Apps & Agents Integrate your app with your chosen Large Language Model (LLM) to build intelligent, autonomous **AI agents** and **AI-enabled apps** that take action for your users right in Slack. - **[Learn about the AI features available for Slack apps](https://docs.slack.dev/ai)** - **[Explore developing Slack apps with AI features](https://docs.slack.dev/ai/developing-ai-apps)** Define where your app lives across the several available [Surfaces](https://docs.slack.dev/surfaces). ![Message Abstract](https://docs.slack.dev/assets/images/message-abstract-06be210d128e91ff97e3ca6d791ef7d9.png) [Surfaces](https://docs.slack.dev/surfaces) encompass all the areas that a Slack app can touch: [messages](https://docs.slack.dev/messaging), [modals](https://docs.slack.dev/surfaces/modals), the [App Home](https://docs.slack.dev/surfaces/app-home), and [canvases](https://docs.slack.dev/surfaces/canvases). Messages, modals, and canvases are available for all types of Slack apps, while the App Home is available for Bolt apps. ![Block Kit](https://docs.slack.dev/assets/images/bk_landing_bkb-e64c290c97543b50e0b09c0b291c7c78.png) [Block Kit](https://docs.slack.dev/block-kit) allows you to build beautiful surfaces with reusable components. Customize the order, appearance, and direct user interactivity with stackable, versatile blocks. ### Further customization Make your app _yours_. Introduce personality and further custom functionality. ✨ [Build AI agents and context-aware apps](https://docs.slack.dev/ai): Integrate your LLM and take advantage of features like the split-view pane and text streaming, all outlined [here](https://docs.slack.dev/ai#ai-features). ✨ [Interactivity](https://docs.slack.dev/interactivity) covers the ways users can initiate interaction with Slack apps, including slash commands and shortcuts. Slash commands allow you to start your app from a simple keystroke and provide even wider functionality. Shortcuts are a simple and reliable way to save your app's location for ease of discovery by users. --- ## Tools of the trade Slack provides several tools to aid you in your quest to creating Slack apps. - ✨ The **[Slack CLI](https://docs.slack.dev/tools/slack-cli/)** is the recommended way to manage your app's entire lifecycle, from creation to installation and administration. - ✨ **[Developer sandboxes](https://docs.slack.dev/tools/developer-sandboxes)** let you play around with platform features outside of a production environment. - ✨ The **Bolt framework**, available for [Python](https://docs.slack.dev/tools/bolt-python/), [JavaScript](https://docs.slack.dev/tools/bolt-js/), and [Java](https://docs.slack.dev/tools/java-slack-sdk/guides/bolt-basics/), uses the **Slack SDKs** (available for [Python](https://docs.slack.dev/tools/python-slack-sdk/), [Node](https://docs.slack.dev/tools/node-slack-sdk/), and [Java](https://docs.slack.dev/tools/java-slack-sdk/)) under the hood to handle the fiddly bits of app development, including token rotation and navigating rate limiting. It is the fastest way to build a capable and secure app. - ✨ Use the **[App settings](https://api.slack.com/apps)** to create apps for times when you don't need any code but want to enable access to the platform via tokens to use with the **[Web API](https://docs.slack.dev/apis/web-api)**. --- ## App vs. workflow For the non-technically inclined, Slack offers a no-code tool to build workflows: [Workflow Builder](https://slack.com/help/articles/360035692513-Guide-to-Slack-Workflow-Builder). This tool is accessed via the Slack client. The Slack platform extends Workflow Builder by providing an avenue to write custom workflow steps. These steps are coded as a function in an app. Once deployed, they are available to use as a step in Workflow Builder. Those custom workflow steps can be created in an app built with the Bolt framework, in any of Bolt's flavors ([Python](https://docs.slack.dev/tools/bolt-python/concepts/custom-steps), [JavaScript](https://docs.slack.dev/tools/bolt-js/concepts/custom-steps), and [Java](https://docs.slack.dev/tools/java-slack-sdk/guides/custom-steps)). The Slack platform offers many options on the road to creating custom Slack apps and workflows. While there is power in those possibilities, it can be daunting to recognize which pieces of the platform apply where. We encourage you to read through a detailed comparison of the options [here](https://docs.slack.dev/workflows/comparing-workflows-apps). --- ## How to use these docs This documentation is broken down into four categories: - **Guides**: These are more lengthy explanations of a concept within a Slack app, i.e. how to build out a feature, how to implement OAuth, what a surface is, etc. You are here. - **Reference**: Have you landed here looking for reference documentation? We admire a straight-shooter. Direct your attention to the [Reference](https://docs.slack.dev/reference) section for referential material on API methods, scopes, events, Block Kit payloads, etc. - **Samples**: Our collection of [sample apps and accompanying tutorials](https://docs.slack.dev/samples). - **Tools**: The library of available [tools](https://docs.slack.dev/tools) you can use to build a Slack app. Psst...check out Bolt. --- ## What's next? Each developer's needs differ. Maybe you want to explore how to [distribute your app](https://docs.slack.dev/app-management/distribution) or even have it listed on the [Slack Marketplace](https://www.slack.com/marketplace). Perhaps you're interested in managing apps [as an admin](https://docs.slack.dev/admins). Better yet, explore the [tools](https://docs.slack.dev/tools) that make the job of app building easier. Keep the end-goal in sight like a guiding horizon: a user wants to accomplish something with your app. The rest is getting there as productively and pleasantly as possible. Ready? [Get Started](https://docs.slack.dev/quickstart) --- # Source: https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux # Installing the Slack CLI for Mac & Linux The Slack CLI is a useful tool for building Slack apps. This is your one-stop shop for installing this tool. ## Automated Installation **Run the automated installer from your terminal window:** ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash ``` This will install the Slack CLI and configure the command. ### Runtime Installations Runtime installations are left to the developer and depend on the app being built. For more information and next steps, review the quickstart guides: - [Bolt for JavaScript](/tools/bolt-js/getting-started) - [Bolt for Python](/tools/bolt-python/getting-started) - [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started) #### Optional: Use an Alias for the Slack CLI Binary If you have another CLI tool in your path called `slack`, you can rename this `slack` binary to a different name to avoid errors during installation. The Slack CLI won't overwrite the existing one! To do this, pass the `-s` argument and an alias to the automated installer: ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s ``` The alias you use should come after any flags used in the installer. For example, if you use the version flag your installation script might look like this: ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v 2.1.0 ``` #### Optional: Download a Specific Version The latest Slack CLI version is installed by default, but a particular version can be pinned using the `-v` flag: ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v 2.1.0 ``` #### Troubleshooting: Command Not Found After running the Slack CLI installation script, the `slack` command might not be available in the current shell. The download has often succeeded but a symbolic link to the command needs to be added to your path. Determine which shell you're using then update your shell profile with the following commands: - **bash**: ```sh echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` - **fish**: ```sh mkdir -p $HOME/.config/fish echo 'fish_add_path $HOME/.local/bin' >> $HOME/.config/fish/config.fish source $HOME/.config/fish/config.fish ``` - **zsh**: ```sh echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` Once the profile is sourced, or a new shell is opened, the `slack` command should be available. ## Manual Installation Manual installation allows you to customize certain paths used when installing the Slack CLI. Runtime installations are omitted from these steps but are still required to run an app. ### 1. Download and Install Git Download and install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), a dependency of the `slack` CLI. ### 2. Download the Slack CLI Installer for Your Environment 🍎 ⚡️ [Download for macOS Apple Silicon (.tar.gz)](https://downloads.slack-edge.com/slack-cli/slack_cli_3.10.0_macOS_arm64.tar.gz) 🍏 🪨 [Download for macOS Intel (.tar.gz)](https://downloads.slack-edge.com/slack-cli/slack_cli_3.10.0_macOS_amd64.tar.gz) 🐧 💾 [Download for Linux (.tar.gz)](https://downloads.slack-edge.com/slack-cli/slack_cli_3.10.0_linux_64-bit.tar.gz) ### 3. Add the `slack` CLI to Your Path Create a symbolic link to the Slack CLI download from (or move the downloaded binary to) any folder that is already in your path. In the following example, we download the Slack CLI to the `.slack` directory and create a symbolic link to `.local` path: ```sh ln -s "$HOME/.slack/bin/slack" "$HOME/.local/bin/slack" ``` We recommend using an alias if another `slack` binary exists. To do this, change the alias used at the end of the symbolic link to something else that makes sense, or rename the moved download to something special. ### 4. Verify That `slack` Is Installed and in Your Path ```sh $ slack version Using slack v3.10.0 ``` --- # Creating interactive messages Transform your Slack app into a powerful workflow partner by making messages interactive. In this guide we'll walk through how [app interactivity](/interactivity) applies to messages and show you how to build a Slack app capable of interacting with users via message. --- ## App interactivity in messages Beyond creating [rich message layouts](/messaging/formatting-message-text#rich-layouts), [Block Kit](/block-kit) also contains a subset of [components that enable interactivity](/block-kit#making-things-interactive). These [**interactive components**](/block-kit#making-things-interactive) can be inserted into messages, converting them from mere information relays into powerful partners for users. Where once your Slack app might have just pulled in data from external services, interactivity allows your app to manipulate, update, and send back data to that same service, thanks to user action. --- ## Getting started with interactive messages For this guide, you'll need to have [created a Slack app](/app-management/quickstart-app-settings#creating), though you won't need to have built it out with any features yet. When you're ready, it's time to get started. ## 1. Compose your interactive message Adding interactive components is no different from adding any other block. Let's add a couple of [buttons](/reference/block-kit/block-elements/button-element) to an [actions](/reference/block-kit/blocks/actions-block) block in a message payload: ```json { "channel": "C123ABC456", "text": "New Paid Time Off request from Fred Enriquez", "blocks": [ { "type": "header", "text": { "type": "plain_text", "text": "New request", "emoji": true } }, { "type": "section", "fields": [ { "type": "mrkdwn", "text": "*Type:*\nPaid Time Off" }, { "type": "mrkdwn", "text": "*Created by:*\n" } ] }, { "type": "section", "fields": [ { "type": "mrkdwn", "text": "*When:*\nAug 10 - Aug 13" } ] }, { "type": "actions", "elements": [ { "type": "button", "text": { "type": "plain_text", "emoji": true, "text": "Approve" }, "style": "primary", "value": "click_me_123" }, { "type": "button", "text": { "type": "plain_text", "emoji": true, "text": "Reject" }, "style": "danger", "value": "click_me_123" } ] } ] } ``` [View in Block Kit Builder](https://api.slack.com/block-kit-builder/#%7B%22blocks%22:%5B%7B%22type%22:%22header%22,%22text%22:%7B%22type%22:%22plain_text%22,%22text%22:%22New%20request%22,%22emoji%22:true%7D%7D,%7B%22type%22:%22section%22,%22fields%22:%5B%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Type:*%5CnPaid%20Time%20Off%22%7D,%7B%22type%22:%22mrkdwn%22,%22text%22:%22*Created%20by:*%5Cn%3Cexample.com%7CFred%20Enriquez%3E%22%7D%5D%7D,%7B%22type%22:%22section%22,%22fields%22:%5B%7B%22type%22:%22mrkdwn%22,%22text%22:%22*When:*%5CnAug%2010%20-%20Aug%2013%22%7D%5D%7D,%7B%22type%22:%22actions%22,%22elements%22:%5B%7B%22type%22:%22button%22,%22text%22:%7B%22type%22:%22plain_text%22,%22emoji%22:true,%22text%22:%22Approve%22%7D,%22style%22:%22primary%22,%22value%22:%22click_me_123%22%7D,%7B%22type%22:%22button%22,%22text%22:%7B%22type%22:%22plain_text%22,%22emoji%22:true,%22text%22:%22Reject%22%7D,%22style%22:%22danger%22,%22value%22:%22click_me_123%22%7D%5D%7D%5D%7D) You could replace these buttons with any of the [available interactive components](/block-kit#making-things-interactive). You can also add a button as a [`section` block's `accessory`](/reference/block-kit/blocks/section-block) element, rather than the `actions` block used above. Browse the [interactive components](/block-kit#making-things-interactive) to see a full list of what's available, or try the [Block Kit Builder tool](https://api.slack.com/tools/block-kit-builder) to visually prototype a layout with interactive components. ## 2. Publishing an interactive message There's nothing special about the process of an app publishing an interactive message, compared to a regular message. Read our [guide to sending messages](/messaging/sending-and-scheduling-messages) to find the best publishing method for your app. After you've chosen a sending method, try to send the message payload above, substituting a real `channel` ID. Once you do, your app's message will be sitting in channel, waiting for someone to click the button within. Let's see what happens when they do. ## 3. Prepare your app to receive interaction payloads When someone uses an interactive component published by your app, Slack will send an [interaction payload to you](/interactivity/handling-user-interaction#payloads). An interaction payload is both a way of notifying your app about an interaction, and a bundle of info describing the where and when (and many other Ws) of the interaction. It is vital to the interaction process, so your app has to be able to understand it. The payload will be sent to your [configured Request URL](/interactivity/handling-user-interaction#payloads) in an HTTP POST. The body of that request will contain a `payload` parameter. Your app should parse this `payload` parameter as JSON. The entirety of this payload will contain all the contextual info that your app needs to be able to figure out what kind of interaction occurred. Your app can use as much or as little of the info as needed. For the purposes of this guide, you should grab the `channel` object, and store that channel's `id` for later. You'll also want to grab the `response_url` here too. Now that your app can receive and understand interaction payloads, it needs to decide what it will do after one of them is sent. ## 4. Respond to the interaction In our [guide to handling user interaction](/interactivity/handling-user-interaction) we explained the different app responses to any interaction. The most important is the required [acknowledgment response](/interactivity/handling-user-interaction#acknowledgment_response). This response is sent back to the same HTTP POST that [delivered the interaction payload](#understanding_payloads). In addition to this acknowledgment, your app can also choose to [compose a message response](/interactivity/handling-user-interaction#message_responses), [invoke a modal](/interactivity/handling-user-interaction#modal_responses), or [one of a multitude of asynchronous responses](/interactivity/handling-user-interaction#async_responses). --- ## Next steps Through this guide you've learned how to add interactive components to messages, prepared your app to handle payloads, and created a simplified interactive flow. From here you can dive into our [reference guides](/reference/block-kit/blocks) to learn more about the different types of blocks you can use, and deepen what your app is capable of doing for users. --- # Sending messages using incoming webhooks Incoming webhooks are a way to post messages from apps into Slack. Creating an incoming webhook gives you a unique URL to which you send a [JSON](https://en.wikipedia.org/wiki/JSON) payload with the message text and some options. You can use all the usual [formatting](/messaging/formatting-message-text) and [layout blocks](/messaging#complex_layouts) with incoming webhooks to make the messages stand out. If you're looking for the Help Center article on using webhooks with Workflow Builder, [head over here](https://slack.com/help/articles/360041352714). Otherwise, read on! --- ## Getting started with incoming webhooks We're going to walk through a 4-step process (if you've already done some of these things it'll be even easier) that will have you posting messages using incoming webhooks in just a few minutes: ### 1. Create a Slack app (if you don't have one already) [Create an app](https://api.slack.com/apps?new_app=1) Pick a name, choose a workspace to associate your app with (bear in mind you'll probably be posting lots of test messages, so you may want to create a channel for sandbox use), then click **Create App**. If you've already created an app, you can use that one. Have a treat for being prepared! 🍪 ### 2. Enable incoming webhooks You'll be redirected to the settings page for your new app (if you're using an existing app, you can load its settings via your [app's management dashboard](https://api.slack.com/apps)). From here, select **Incoming Webhooks**, and toggle **Activate Incoming Webhooks** to on. If you already have this activated, well, you deserve another treat! 🍪 ### 3. Create an incoming webhook Now that incoming webhooks are enabled, the settings page should refresh and some additional options will appear. One of those options is a very helpful button called **Add New Webhook to Workspace** — click it! What this button does is trigger a shortcut version of the installation flow for Slack apps, one that is completely self-contained so that you don't have to actually build any code to generate an incoming webhook URL. We'll [show how you can generate webhooks programmatically later](#incoming_webhooks_programmatic), but for now, you'll see something like the following: ![Permissions screen with incoming webhooks channel selector](https://slack.dev/img/guides/incoming_webhooks_permissions_screen.png) Go ahead and pick a channel that the app will post to, then select **Authorize**. If you need to add the incoming webhook to a private channel, you must first be in that channel. You'll be sent back to your app settings, where you should see a new entry under the **Webhook URLs for Your Workspace** section. Your webhook URL will look something like this: ```http https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX ``` That URL is your shiny new incoming webhook, one that's specific to a single user and a single channel. #### For GovSlack devs If you're developing a [GovSlack](/govslack) app for use by public sector customers, make your API calls to the `slack-gov.com` domain instead of the `slack.com` domain. Let's see how you can actually use that webhook to post a message. #### Keep it secret, keep it safe Your webhook URL contains a secret. Don't share it online, including via public version control repositories. **Slack actively searches out and revokes leaked secrets.** ### 4. Use your incoming webhook URL to post a message Later in this doc we'll explain [how to make your messages more expressive or interactive](#advanced_message_formatting), but for right now anything will do, so we're going to use that old standby — "Hello, world". Make an HTTP POST request like this: ```http POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX Content-type: application/json { "text": "Hello, world." } ``` The URL that you're making the POST request to should be the same URL you generated in the previous step. That's it! Go and check the channel your app was installed into, and you'll see that the "Hello, World" message has been posted by your app. You can use this in a real Slack app without much change, just substitute your favorite HTTP Request library for cURL and structure all the requests in the exact same way. You'll also need to pay attention to some details [we've outlined below](#incoming_webhooks_programmatic) when you're distributing your app. #### Incoming webhooks do not allow you to delete a message after it's been posted. If you need a more complex chat flow including message deletion, call [`chat.postMessage`](/reference/methods/chat.postMessage). Great work, you've set up incoming webhooks for your Slack app and made a successful test call, and you're ready to start making those messages more interesting and useful. We baked some extra treats to celebrate! 🍪🍪🍪🍪 --- ## Making it fancy with advanced formatting Incoming webhooks conform to the same rules and functionality as any of our other messaging APIs. You can make your posted messages just a single line of text, or use [interactive components](/messaging/creating-interactive-messages). The process of using all these extras and features is similar to [the one explained above](#posting_with_webhooks). The only difference is the JSON payload that you send to your webhook URL will contain other fields in addition to `text`. Here's a more advanced HTTP request example that you can use with the same webhook `url` that you [used above](#posting_with_webhooks): ```http POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX Content-type: application/json { "text": "Danny Torrence left a 1 star review for your property.", "blocks": [ { "type": "section", "text": { "type": "mrkdwn", "text": "Danny Torrence left the following review for your property:" } }, { "type": "section", "block_id": "section567", "text": { "type": "mrkdwn", "text": " \n :star: \n Doors had too many axe holes, guest in room 237 was far too rowdy, whole place felt stuck in the 1920s." }, "accessory": { "type": "image", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Purple3/v4/d3/72/5c/d3725c8f-c642-5d69-1904-aa36e4297885/source/256x256bb.jpg", "alt_text": "Haunted hotel image" } }, { "type": "section", "block_id": "section789", "fields": [ { "type": "mrkdwn", "text": "*Average Rating*\n1.0" } ] } ] } ``` This example uses [Block Kit](/block-kit) visual components to make the message more expressive and --- # Quickstart guide using Bolt We recommend using the CLI and the Slack Bolt framework for simplicity in creating an app. Pick your flavor of Bolt below and get started! Would you rather create an app from the [app settings](https://api.slack.com/apps) in a browser? Head over to [Creating an app with app settings](/app-management/quickstart-app-settings) to learn how to create a basic Slack app that can send messages using webhooks. ## Prerequisites A few tools are needed for the following steps. We recommend using the [Slack CLI](/tools/slack-cli/) for the smoothest experience, but other options remain available. You can also begin by installing git and downloading [Python 3.7 or later](https://www.python.org/downloads/), or the latest stable version of Python. Refer to [Python's setup and building guide](https://devguide.python.org/getting-started/setup-building/) for more details. Install the latest version of the Slack CLI to get started: - [Slack CLI for macOS & Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) - [Slack CLI for Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) Then confirm a successful installation with the following command: ```sh $ slack version ``` An authenticated login is also required if this hasn't been done before: ```sh $ slack login ``` ### A place to belong A workspace where development can happen is also needed. We recommend using [developer sandboxes](/tools/developer-sandboxes) to avoid disruptions where real work gets done. ## Creating a project With the toolchain configured, it's time to set up a new Bolt project. This contains the code that handles logic for your app. If you don’t already have a project, let’s create a new one! ### Slack CLI The getting started app template contains a `manifest.json` file with details about an app that we will use to get started. Use the following command and select "Create a new app" to install the app to the team of choice: ```sh $ slack run ... ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@first-bolt-app (local)` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ### Browser Navigate to your list of apps and [create a new Slack app](https://api.slack.com/apps/new) using the "from a manifest" option: 1. Select the workspace to develop your app in. 2. Copy and paste the `manifest.json` file contents to create your app. 3. Confirm the app features and click "Create". You'll then land on your app's **Basic Information** page, which is an overview of your app and which contains important credentials: ![Basic Information page](/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) To listen for events happening in Slack (such as a new posted message) without opening a port or exposing an endpoint, we will use [Socket Mode](/tools/bolt-python/concepts/socket-mode). This connection requires a specific app token: 1. On the **Basic Information** page, scroll to the **App-Level Tokens** section and click **Generate Token and Scopes**. 2. Name the token "Development" or something similar and add the `connections:write` scope, then click **Generate**. 3. Save the generated `xapp` token as an environment variable within your project: ```sh $ export SLACK_APP_TOKEN= ``` The above command works on Linux and macOS but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). ### Keep it secret. Keep it safe. Treat your tokens like a password and [keep it safe](/security). Your app uses these to retrieve and send information to Slack. A bot token is also needed to interact with the Web API methods as your app's bot user. We can gather this as follows: 1. Navigate to the **OAuth & Permissions** on the left sidebar and install your app to your workspace to generate a token. 2. After authorizing the installation, you'll return to the **OAuth & Permissions** page and find a **Bot User OAuth Token**: ![OAuth Tokens](/assets/images/bot-token-3d6c761238c7a66557fd08d00a2a1b0c.png) 1. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable: ```sh $ export SLACK_BOT_TOKEN=xoxb- ``` After saving tokens for the app you created, it is time to run it: ```sh $ python3 app.py ... ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@BoltApp` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ## Updating the app At this point, you've successfully run the getting started Bolt for Python [app](https://github.com/slack-samples/bolt-python-getting-started-app)! The defaults included leave opportunities abound, so to personalize this app let's now edit the code to respond with a kind farewell. ### Responding to a farewell Chat is a common thing apps do and responding to various types of messages can make conversations more interesting. Using an editor of choice, open the `app.py` file and add the following import to the top of the file, and message listener after the "hello" handler: ```python import random @app.message("goodbye") def message_goodbye(say): responses = ["Adios", "Au revoir", "Farewell"] parting = random.choice(responses) say(f"{parting}!") ``` Once the file is updated, save the changes and then we'll make sure those changes are being used. ### Slack CLI Run the following command and select the app created earlier to start, or restart, your app with the latest changes: ```sh $ slack run ... ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Terminal Run the following command to start, or restart, your app with the latest changes: ```sh $ python3 app.py ... ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Customizing app settings The created app will have some placeholder values and a small set of [scopes](/reference/scopes) to start, but we recommend exploring the customizations possible on app settings. Open app settings for your app with the following command: ```sh $ slack app settings ``` This will open the following page in a web browser: ![Basic Information page](/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) Browse to [https://api.slack.com/apps](https://api.slack.com/apps) and select your app "Getting Started Bolt App" from the list. This will open the following page: ![Basic Information page](/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app! ## Adding AI features Now that you're familiar with a basic app setup, try it out again, this time using the AI agent template! Get started with the agent template: ```sh $ slack create ai-app --template slack-samples/bolt-python-assistant-template $ cd ai-app ``` ### Slack CLI ### Browser Once the project is created, update the `.env.sample` file by setting the `OPENAI_API_KEY` with the value of your key and removing the `.sample` from the file name. In the `ai` folder of this app, you'll find default instructions for the LLM and an OpenAI client setup. The `listeners` include utilities intended for messaging with an LLM. Those are outlined in detail in the guide to [Using AI in apps](/tools/bolt-python/concepts/ai-apps) and [Sending messages](/tools/bolt-python/concepts/message-sending). ## Next steps Congrats once more on getting up and running with this quick start. --- # 5 steps to managing apps securely and at scale | Slack [Skip to main content](#main_focusable) [![Slack Logo](https://a.slack-edge.com/38f0e7c/marketing/img/nav/slack-salesforce-logo-nav-white.png)](https://slack.com/) [![Slack Logo](https://a.slack-edge.com/38f0e7c/marketing/img/nav/slack-salesforce-logo-nav-black.png)](https://slack.com/) ## Features ### COLLABORATION - [Channels](https://slack.com/features/channels) - Organize teams and work - [Slack Connect](https://slack.com/connect) - Work with external partners - [Messaging](https://slack.com/team-chat) - Chat with your team - [Huddles](https://slack.com/features/huddles) - Meet with audio and video - [Clips](https://slack.com/features/clips) - Record and share updates ### CRM - [Salesforce in Slack](https://slack.com/features/crm) - Bring Salesforce into the flow of work ### PROJECT MANAGEMENT - [Templates](https://slack.com/templates) - Start any task, fast - [Canvas](https://slack.com/features/canvas) - Create rich, flexible docs - [Lists](https://slack.com/features/task-list) - Organize, track and manage projects - [File Sharing](https://slack.com/document-sharing) - Bring files to the flow of work ### PLATFORM - [Agentic Platform](https://slack.com/features/agentic-platform) - Customize, extend, and unify your tech stack in Slack - [Apps & Integrations](https://slack.com/integrations) - Connect your tools with Slack - [Workflow Builder](https://slack.com/features/workflow-automation) - Automate everyday tasks ### INTELLIGENCE - ![AI Icon](https://a.slack-edge.com/7d8fca7/marketing/img/nav/ai-sparkles.svg) [AI in Slack](https://slack.com/features/ai) - Save time and work smarter with powerfully simple AI - ![Slackbot Icon](https://a.slack-edge.com/b518216/marketing/img/nav/slackbot-nav-icon.svg) [Slackbot](https://slack.com/features/slackbot) - Power productivity with your personal AI agent - [Agentforce](https://slack.com/ai-agents) - Empower your whole team with AI-powered agents in Slack - [Enterprise Search](https://slack.com/features/enterprise-search) - Find anything, all from a single search bar ### ADMIN & SECURITY - [Security](https://slack.com/trust/security) - Protect data, ensure compliance - [Enterprise Key Management](https://slack.com/enterprise-key-management) - Monitor and revoke access - [Slack Atlas](https://slack.com/atlas) - Discover rich profiles and org charts - [Watch demo](http://slack.com/demo) - [Download Slack](/get) ![Download Icon](https://a.slack-edge.com/fd21de4/marketing/img/nav/download.svg) ## Slack Marketplace - [![Marketplace Image](https://a.slack-edge.com/11136b7/marketing/img/nav/img-marketplace-nav.jpg) Find new agents and apps that fit your team’s needs. Browse marketplace](https://slack.com/marketplace) - [What is Slack?](https://slack.com/resources/why-use-slack/what-is-slack-and-how-does-it-work) - [Slack vs. Email](https://slack.com/why/slack-vs-email) - [Accessibility](https://slack.com/accessibility) ## Solutions ### BY DEPARTMENT - [Engineering](https://slack.com/solutions/engineering) - [IT](https://slack.com/solutions/information-technology) - [Customer Service](https://slack.com/solutions/customer-service) - [Sales](https://slack.com/solutions/sales) - [Project Management](https://slack.com/solutions/project-management) - [Marketing](https://slack.com/solutions/marketing) - [Human Resources](https://slack.com/solutions/human-resources) - [Security](https://slack.com/solutions/security) ### BY INDUSTRY - [Manufacturing, Auto & Energy](https://slack.com/solutions/manufacturing) - [Technology](https://slack.com/solutions/technology) - [Media](https://slack.com/solutions/media) - [Small Business](https://slack.com/solutions/small-business) - [Financial Services](https://slack.com/solutions/financial-services) - [Retail](https://slack.com/solutions/retail) - [Public Sector](https://slack.com/solutions/public-sector) - [Education](https://slack.com/solutions/distance-learning) - [Health & Life Sciences](https://slack.com/solutions/healthcare) - [Watch demo](http://slack.com/demo) - [Download Slack](/get) ![Download Icon](https://a.slack-edge.com/fd21de4/marketing/img/nav/download.svg) - [See all solutions](/solutions) ## TEMPLATE GALLERY - [![Template Gallery Image](https://a.slack-edge.com/e1ed284/marketing/img/nav/feature-template-gallery@2x.jpg) Start work faster with pre-made templates for every task. See all templates](https://slack.com/templates/gallery) - [Task Management](https://slack.com/solutions/task-management) - [Scale](https://slack.com/scale) - [Engagement](https://slack.com/engage-users) - [Trust](https://slack.com/trust) ## Enterprise [Enterprise](https://slack.com/enterprise) ## Resources ### Resources Library - [Resources Library](https://slack.com/resources) - [What’s New](https://slack.com/whats-new) - [Product Tour](https://slackdemo.com/) - [Events](https://slack.com/events) - [Developers](https://api.slack.com/) - [Partners](https://slack.com/partners) - [Customer Stories](https://slack.com/customer-stories) - [Community](https://slack.com/community) - [Slack Certified](https://slackcertified.com) - [Blog](https://slack.com/blog) - [Slack Marketplace](https://slack.com/marketplace) - [Watch demo](http://slack.com/demo) - [Download Slack](/get) ![Download Icon](https://a.slack-edge.com/fd21de4/marketing/img/nav/download.svg) ### FEATURED - [![State of AI Agents Report Image](https://a.slack-edge.com/496f288/marketing/img/nav/nav-ad-state-of-work@2x.png) AI agents are the catalyst for a limitless workforce Get the report](https://slack.com/resources/why-use-slack/state-of-ai-agents) - [Help Center](https://slack.com/help) - [Customer Support](https://slack.com/help/requests/new) ## Pricing [Pricing](https://slack.com/pricing) [Sign in](https://slack.com/signin) [Request a demo](https://slack.com/contact-sales?category=slack-for-admins&slug=app-management) [Get started](https://slack.com/get-started?entry_point=nav_menu) --- # Source: https://docs.slack.dev/tools/slack-cli/guides/running-slack-cli-commands # Running Slack CLI commands The Slack CLI allows you to interact with your apps via the command line. Using the main command `slack`, you can create, run, and deploy apps, as well as create triggers and query datastores. ## Running `slack help` will display available commands in your terminal window. Use commands as follows (unless otherwise noted): ```text slack [flags] ``` To view global flags and each subcommands flags, run the following in your terminal: ```text slack --help ``` ## Commands overview Below you'll find all the commands and subcommands for the Slack CLI. Each one has its own reference page. | Command | Description | | --- | --- | | [slack activity](/tools/slack-cli/reference/commands/slack_activity) | Display the app activity logs from the Slack Platform | | [slack app](/tools/slack-cli/reference/commands/slack_app) | Install, uninstall, and list teams with the app installed | | [slack auth](/tools/slack-cli/reference/commands/slack_auth) | Add and remove local team authorizations | | [slack collaborator](/tools/slack-cli/reference/commands/slack_collaborator) | Manage app collaborators | | [slack create](/tools/slack-cli/reference/commands/slack_create) | Create a Slack project | | [slack datastore](/tools/slack-cli/reference/commands/slack_datastore) | Query an app's datastore | | [slack delete](/tools/slack-cli/reference/commands/slack_delete) | Delete the app | | [slack deploy](/tools/slack-cli/reference/commands/slack_deploy) | Deploy the app to the Slack Platform | | [slack doctor](/tools/slack-cli/reference/commands/slack_doctor) | Check and report on system and app information | | [slack env](/tools/slack-cli/reference/commands/slack_env) | Add, remove, and list environment variables | | [slack external-auth](/tools/slack-cli/reference/commands/slack_external-auth) | Add and remove external authorizations and client secrets for providers in your app | | [slack feedback](/tools/slack-cli/reference/commands/slack_feedback) | Share feedback about your experience or project | | [slack function](/tools/slack-cli/reference/commands/slack_function) | Manage the functions of an app | | [slack install](/tools/slack-cli/reference/commands/slack_install) | Install the app to a team | | [slack list](/tools/slack-cli/reference/commands/slack_list) | List all authorized accounts | | [slack login](/tools/slack-cli/reference/commands/slack_login) | Log in to a Slack account | | [slack logout](/tools/slack-cli/reference/commands/slack_logout) | Log out of a team | | [slack manifest](/tools/slack-cli/reference/commands/slack_manifest) | Print the app manifest of a project or app | | [slack platform](/tools/slack-cli/reference/commands/slack_platform) | Deploy and run apps on the Slack Platform | | [slack run](/tools/slack-cli/reference/commands/slack_run) | Start a local server to develop and run the app locally | | [slack samples](/tools/slack-cli/reference/commands/slack_samples) | List available sample apps | | [slack trigger](/tools/slack-cli/reference/commands/slack_trigger) | List details of existing triggers | | [slack uninstall](/tools/slack-cli/reference/commands/slack_uninstall) | Uninstall the app from a team | | [slack upgrade](/tools/slack-cli/reference/commands/slack_upgrade) | Checks for available updates to the CLI or SDK | | [slack version](/tools/slack-cli/reference/commands/slack_version) | Print the version number | [Previous: Using on Enterprise Grid](/tools/slack-cli/guides/using-slack-cli-on-an-enterprise-grid-organization) [Next: Using environment variables](/tools/slack-cli/guides/using-environment-variables-with-the-slack-cli) --- # Source: https://docs.slack.dev/tools/slack-cli/ # Slack CLI The Slack command-line interface (CLI) allows you to create and manage Slack apps from the command line. Use it in combination with the Deno Slack SDK, or the Bolt frameworks for JavaScript and Python. Follow the installation guide for either [MacOS / Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) or [Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) to get set up. Then, follow the [Authorization guide](/tools/slack-cli/guides/authorizing-the-slack-cli) to connect your workspace. ## Getting help This site has lots of guides on the Slack CLI. There's also an in-depth reference both for [commands](/tools/slack-cli/reference/commands/slack) and [errors](/tools/slack-cli/reference/errors). If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/slack-cli/issues) for questions, bug reports, feature requests, and general discussion related to the Slack CLI. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. ## Contributing These docs live within the open source [Slack CLI](https://github.com/slackapi/slack-cli) repository. We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/slack-cli/blob/main/.github/CONTRIBUTING.md) for how to contribute in a helpful and collaborative way. --- # Using AI in Apps The Slack platform offers features tailored for AI agents and assistants. Your apps can [utilize the `Assistant` class](#assistant) for a side-panel view designed with AI in mind, or they can utilize features applicable to messages throughout Slack, like [chat streaming](#text-streaming) and [feedback buttons](#adding-and-handling-feedback). If you're unfamiliar with using these features within Slack, you may want to read the [API documentation on the subject](/ai/). Then come back here to implement them with Bolt! ## The `Assistant` class instance **Some features within this guide require a paid plan** If you don't have a paid workspace for development, you can join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. The [`Assistant`](/tools/bolt-js/reference#the-assistantconfig-configuration-object) class can be used to handle the incoming events expected from a user interacting with an app in Slack that has the Agents & AI Apps feature enabled. A typical flow would look like: 1. [The user starts a thread](#handling-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](/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`](/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`](/reference/events/message.im) event. ```js const assistant = new Assistant({ /** * (Recommended) A custom ThreadContextStore can be provided, inclusive of methods to * get and save thread context. When provided, these methods will override the `getThreadContext` * and `saveThreadContext` utilities that are made available in other Assistant event listeners. */ // threadContextStore: { // get: async ({ context, client, payload }) => {}, // save: async ({ context, client, payload }) => {}, // }, /** * `assistant_thread_started` is sent when a user opens the Assistant container. * This can happen via DM with the app or as a side-container within a channel. */ threadStarted: async ({ event, logger, say, setSuggestedPrompts, saveThreadContext }) => {}, /** * `assistant_thread_context_changed` is sent when a user switches channels * while the Assistant container is open. If `threadContextChanged` is not * provided, context will be saved using the AssistantContextStore's `save` * method (either the DefaultAssistantContextStore or custom, if provided). */ threadContextChanged: async ({ logger, saveThreadContext }) => {}, /** * Messages sent from the user to the Assistant are handled in this listener. */ userMessage: async ({ client, context, logger, message, getThreadContext, say, setTitle, setStatus }) => {} }); ``` **Consider the following** You _could_ go it alone and [listen](/tools/bolt-js/concepts/event-listening) for the `assistant_thread_started`, `assistant_thread_context_changed`, and `message.im` events in order to implement the AI features in your app. That being said, using the `Assistant` class will streamline the process. And we already wrote this nice guide for you! While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextStore` property — but it also provides a `DefaultThreadContextStore` instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](/messaging/message-metadata/) as the user interacts with the app. If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods. **Be sure to give the [reference docs](/tools/bolt-js/reference#agents--assistants) a look!** ### Configuring your app to support the `Assistant` class 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`](/reference/scopes/assistant.write) - [`chat:write`](/reference/scopes/chat.write) - [`im:history`](/reference/scopes/im.history) 3. Within the App Settings **Event Subscriptions** page, subscribe to the following events: - [`assistant_thread_started`](/reference/events/assistant_thread_started) - [`assistant_thread_context_changed`](/reference/events/assistant_thread_context_changed) - [`message.im`](/reference/events/message.im) ### Handling a new thread When the user opens a new thread with your AI-enabled app, the [`assistant_thread_started`](/reference/events/assistant_thread_started) event will be sent to your app. Capture this with the `threadStarted` handler to allow your app to respond. In the example below, the app is sending a message — containing thread context [message metadata](/messaging/message-metadata/) behind the scenes — to the user, along with a single [prompt](/reference/methods/assistant.threads.setSuggestedPrompts). ```js threadStarted: async ({ event, logger, say, setSuggestedPrompts, saveThreadContext }) => { const { context } = event.assistant_thread; try { /** * Since context is not sent along with individual user messages, it's necessary to keep * track of the context of the conversation to better assist the user. Sending an initial * message to the user with context metadata facilitates this, and allows us to update it * whenever the user changes context (via the `assistant_thread_context_changed` event). * The `say` utility sends this metadata along automatically behind the scenes. * !! Please note: this is only intended for development and demonstrative purposes. */ await say('Hi, how can I help?'); await saveThreadContext(); /** * Provide the user up to 4 optional, preset prompts to choose from. * * The first `title` prop is an optional label above the prompts that * defaults to 'Try these prompts:' if not provided. */ if (!context.channel_id) { await setSuggestedPrompts({ title: 'Start with this suggested prompt:', prompts: [ { title: 'This is a suggested prompt', message: 'When a user clicks a prompt, the resulting prompt message text ' + 'can be passed directly to your LLM for processing.\n\n' + 'Assistant, please create some helpful prompts I can provide to ' + 'my users.' }, ], }); } } catch (error) { console.error(error); } }; ``` --- # Quickstart with Bolt for JavaScript This quickstart guide aims to help you get a Slack app using Bolt for JavaScript up and running as soon as possible! When complete, you'll have a local environment configured with a customized [app](https://github.com/slack-samples/bolt-js-getting-started-app) running that responds to a simple greeting. ## Prerequisites A few tools are needed for the following steps. We recommend using the [**Slack CLI**](https://docs.slack.dev/tools/slack-cli/) for the smoothest experience, but other options remain available. ### Slack CLI Install the latest version of the Slack CLI to get started: - [Slack CLI for macOS & Linux](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) - [Slack CLI for Windows](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-windows) Then confirm a successful installation with the following command: ```sh $ slack version ``` An authenticated login is also required if this hasn't been done before: ```sh $ slack login ``` ### Tooling for the Terminal Tooling for the terminal can also be used to follow along: - [Git](https://git-scm.com/downloads) - [Node.js](https://nodejs.org/en/download) Once installed, make sure recent versions are being used: ```sh $ git --version $ node --version ``` ### A Place to Belong A workspace where development can happen is also needed. We recommend using [developer sandboxes](https://docs.slack.dev/tools/developer-sandboxes) to avoid disruptions where real work gets done. ## Creating a Project With the toolchain configured, it's time to set up a new Bolt project. This contains the code that handles logic for your app. If you don’t already have a project, let’s create a new one! ### Slack CLI A starter template can be used to start with project scaffolding: ```sh $ slack create first-bolt-app --template slack-samples/bolt-js-getting-started-app $ cd first-bolt-app ``` After a project is created you'll have a `package.json` file for app dependencies and a `.slack` directory for Slack CLI configuration. A few other files exist too, but we'll visit these later. ### A Starter Template A starter template can be cloned to start with project scaffolding: ```sh $ git clone https://github.com/slack-samples/bolt-js-getting-started-app first-bolt-app $ cd first-bolt-app $ npm install ``` Outlines of a project are taking shape, so we can move on to running the app! ## Running the App Before you can start developing with Bolt, you will want a running Slack app. ### Slack CLI The getting started app template contains a `manifest.json` file with details about an app that we will use to get started. Use the following command and select "Create a new app" to install the app to the team of choice: ```sh $ slack run ... [INFO] bolt-app ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@first-bolt-app (local)` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ### Terminal Navigate to your list of apps and [create a new Slack app](https://api.slack.com/apps/new) using the "from a manifest" option: 1. Select the workspace to develop your app in. 2. Copy and paste the `manifest.json` file contents to create your app. 3. Confirm the app features and click "Create". You'll then land on your app's **Basic Information** page, which is an overview of your app and which contains important credentials: ![Basic Information page](https://docs.slack.dev/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) To listen for events happening in Slack (such as a new posted message) without opening a port or exposing an endpoint, we will use [Socket Mode](https://docs.slack.dev/tools/bolt-js/concepts/socket-mode). This connection requires a specific app token: 1. On the **Basic Information** page, scroll to the **App-Level Tokens** section and click **Generate Token and Scopes**. 2. Name the token "Development" or something similar and add the `connections:write` scope, then click **Generate**. 3. Save the generated `xapp` token as an environment variable within your project: ```sh $ export SLACK_APP_TOKEN=xapp-1-A0123456789-example ``` The above command works on Linux and macOS but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). **Keep it secret. Keep it safe** Treat your tokens like a password and [keep it safe](https://docs.slack.dev/security). Your app uses these to retrieve and send information to Slack. A bot token is also needed to interact with the Web API methods as your app's bot user. We can gather this as follows: 1. Navigate to the **OAuth & Permissions** on the left sidebar and install your app to your workspace to generate a token. 2. After authorizing the installation, you'll return to the **OAuth & Permissions** page and find a **Bot User OAuth Token**: ![OAuth Tokens](https://docs.slack.dev/assets/images/bot-token-3d6c761238c7a66557fd08d00a2a1b0c.png) 3. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable: ```sh $ export SLACK_BOT_TOKEN=xoxb-example ``` After saving tokens for the app you created, it is time to run it: ```sh $ npm run start ... [INFO] bolt-app ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@BoltApp` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ## Updating the App At this point, you've successfully run the getting started Bolt for JavaScript [app](https://github.com/slack-samples/bolt-js-getting-started-app)! The defaults included leave opportunities abound, so to personalize this app let's now edit the code to respond with a kind farewell. ### Responding to a Farewell Chat is a common thing apps do and responding to various types of messages can make conversations more interesting. Using an editor of choice, open the `app.js` file and add the following message listener after the "hello" handler: ```js app.message('goodbye', async ({ say }) => { const responses = ['Adios', 'Au revoir', 'Farewell']; const parting = responses[Math.floor(Math.random() * responses.length)]; await say(`/${parting}!`); }); ``` Once the file is updated, save the changes and then we'll make sure those changes are being used. ### Slack CLI Run the following command and select the app created earlier to start, or restart, your app with the latest changes: ```sh $ slack run ... [INFO] bolt-app ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Terminal Run the following command to start, or restart, your app with the latest changes: ```sh $ npm run start ... [INFO] bolt-app ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Customizing App Settings The created app will have some placeholder values and a small set of [scopes](https://docs.slack.dev/reference/scopes) to start, but we recommend exploring the customizations possible on app settings. ### Slack CLI Open app settings for your app with the following command: ```sh $ slack app settings ``` This will open the following page in a web browser: ![Basic Information page](https://docs.slack.dev/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) Browse to [https://api.slack.com/apps](https://api.slack.com/apps) and select your app "Getting Started Bolt App" from the list. This will open the following page: ![Basic Information page](https://docs.slack.dev/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app! ## Adding AI Features Now that you're familiar with a basic app setup, try it out again, this time using the AI agent template! ### Slack CLI Get started with the agent template: ```sh $ slack create ai-app --template slack-samples/bolt-js-assistant-template $ cd ai-app ``` ### Terminal Get started with the agent template: ```sh $ git clone https://github.com/slack-samples/bolt-js-assistant-template ai-app $ cd ai-app $ npm install ``` Using this method, be sure to set the app and bot tokens as we did in the [Running the app](#running-the-app) section above. Once the project is created, update the `.env.sample` file by setting the `OPENAI_API_KEY` with the value of your key and removing the `.sample` from the file name. In the `ai` folder of this app, you'll find default instructions for the LLM and an OpenAI client setup. The `listeners` include utilities intended for messaging with an LLM. Those are outlined in detail in the guide to [Using AI in apps](https://docs.slack.dev/tools/bolt-js/concepts/ai-apps) and [Sending messages](https://docs.slack.dev/tools/bolt-js/concepts/message-sending). ## Next Steps Congrats once more on getting up and running with this quick start. ### Dive Deeper Follow along with the step-by-step guide to adding AI features to your app. ### Next Steps Now that you have a solid foundation, you can dive into more advanced topics and explore the full capabilities of Bolt for JavaScript. --- # AI Code Assistant with Hugging Face In this tutorial, we will create an [app that has platform AI features enabled](/ai/developing-ai-apps) with the Bolt framework and integrate a [Hugging Face](https://huggingface.co/) model to assist the user with coding questions. We'll also make this functionality available as a step in a workflow to use in Workflow Builder. Hugging Face is an open-source community best known for its transformers library and platform for machine learning models. Hugging Face's model hub is an online repository where you can find thousands of pre-trained models for natural language processing, computer vision, speech recognition, and more. The platform is open-source, so anyone can contribute to the models and browse the models others have started. Here, we will be using the [Qwen2.5-Coder-32B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct) model to create an app that can answer coding questions. ## Prerequisites Before getting started, you will need the following: - a development workspace where you have permissions to install apps. If you don’t have a workspace, go ahead and set that up now—you can [go here](https://slack.com/get-started#create) to create one, or you can join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. - a Hugging Face account in which you can generate an access token. ## Creating your app 1. Navigate to the [app creation page](https://api.slack.com/apps/new) and select **From a manifest**. 2. Select the workspace you want to install the application in and click **Next**. 3. Copy the contents below and paste it into the text box that says **Paste your manifest code here** (within the **JSON** tab), replacing the placeholder text, and click **Next**. ```json { "display_information": { "name": "Code Assistant" }, "features": { "app_home": { "home_tab_enabled": false, "messages_tab_enabled": true, "messages_tab_read_only_enabled": false }, "bot_user": { "display_name": "Code Assistant", "always_online": false }, "assistant_view": { "assistant_description": "An Assistant to help you with coding questions and challenges!", "suggested_prompts": [] } }, "oauth_config": { "scopes": { "bot": [ "assistant:write", "channels:join", "im:history", "channels:history", "groups:history", "chat:write" ] } }, "settings": { "event_subscriptions": { "bot_events": [ "assistant_thread_context_changed", "assistant_thread_started", "message.im", "function_executed" ] }, "interactivity": { "is_enabled": true }, "org_deploy_enabled": true, "socket_mode_enabled": true, "function_runtime": "remote", "token_rotation_enabled": false }, "functions": { "code_assist": { "title": "Code Assist", "description": "Get an answer about a code related question", "input_parameters": { "message_id": { "type": "string", "title": "Message ID", "description": "The message the question was asked in.", "is_required": true }, "channel_id": { "type": "slack#/types/channel_id", "title": "Channel ID", "description": "The channel the question was asked in", "is_required": true } }, "output_parameters": { "message": { "type": "string", "title": "Answer", "description": "The response from the Code Assistant LLM", "is_required": true } } } } } ``` 4. Review the configuration and click **Create**. Clicking around in these settings, you can see what the manifest has created for us. Some highlights: - Within **App Home**, we've enabled the **Chat Tab**. This will allow users to access your app both in the split-view container as well as within a chat tab of the app. - **Agents & AI Apps** is enabled. With this toggled on, the split-view container is available for your app. - A custom step has been added to **Workflow Steps**. A workflow step is a custom step that can be used in Workflow Builder. Setting up information about that step here (its name, input parameters, and output parameters) lets Slack know what data to collect from the workflow to send to the function. We'll implement the logic step for this in code. - **Org Level Apps** has been enabled. This means that your app will be installed at the organization level. Upon installation, it is not added to any workspaces, but the workspace admin can choose which workspaces in the org to add the app to. - Within **OAuth & Permissions**, you will find several bot scopes have been added. - Within **Event Subscriptions**, you will find several events this app subscribes to, which allow it to respond to user requests appropriately. 5. Navigate to the **Install App** page in the left nav and click **Install to Workspace**, then **Allow** on the screen that follows. ### Obtaining your environment variables In order to connect this configuration with the app we are about to code, you'll need to first obtain and set some environment variables. 1. **Bot token**: On the **Install App< --- # Bolt for JavaScript Bolt for JavaScript is a JavaScript framework to build Slack apps with the latest Slack platform features. Read the [Quickstart Guide](/tools/bolt-js/getting-started) to set up and run your first Bolt app. Then, explore the rest of the pages within the Guides section. The documentation there will help you build a Bolt app for whatever use case you may have. ## Getting help These docs have lots of information on Bolt for JavaScript. There's also an in-depth Reference section. Please explore! If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/bolt-js/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. ## Contributing These docs live within the [Bolt-JS](https://github.com/slackapi/bolt-js/) repository and are open source. We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/bolt-js/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way. --- # Using AI in Apps The Slack platform offers features tailored for AI agents and assistants. Your apps can [utilize the `Assistant` class](#assistant) for a side-panel view designed with AI in mind, or they can utilize features applicable to messages throughout Slack, like [chat streaming](#text-streaming) and [feedback buttons](#adding-and-handling-feedback). If you're unfamiliar with using these features within Slack, you may want to read the [API documentation on the subject](/ai/). Then come back here to implement them with Bolt! ## The `Assistant` class instance
Some features within this guide require a paid plan
The [`Assistant`](/tools/bolt-python/reference#the-assistantconfig-configuration-object) class can be used to handle the incoming events expected from a user interacting with an app in Slack that has the Agents & AI Apps feature enabled. A typical flow would look like: 1. [The user starts a thread](#handling-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](/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`](/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`](/reference/events/message.im) event. ```python assistant = Assistant() # This listener is invoked when a human user opened an assistant thread @assistant.thread_started def start_assistant_thread( say: Say, get_thread_context: GetThreadContext, set_suggested_prompts: SetSuggestedPrompts, logger: logging.Logger, ): try: # This listener is invoked when the human user sends a reply in the assistant thread @assistant.user_message def respond_in_assistant_thread( client: WebClient, context: BoltContext, get_thread_context: GetThreadContext, logger: logging.Logger, payload: dict, say: Say, set_status: SetStatus, ): try: # Enable this assistant middleware in your Bolt app app.use(assistant) ```
Consider the following

You _could_ go it alone and [listen](/tools/bolt-python/concepts/event-listening) for the `assistant_thread_started`, `assistant_thread_context_changed`, and `message.im` events in order to implement the AI features in your app. That being said, using the `Assistant` class will streamline the process. And we already wrote this nice guide for you!

While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread context — the `threadContextStore` property — but it also provides a `DefaultThreadContextStore` instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](/messaging/message-metadata/) as the user interacts with the app. If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods.
Refer to the [reference docs](https://docs.slack.dev/tools/bolt-python/reference/kwargs_injection/args.html) to learn the available listener arguments.
### Configuring your app to support the `Assistant` class 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`](/reference/scopes/assistant.write) - [`chat:write`](/reference/scopes/chat.write) - [`im:history`](/reference/scopes/im.history) 3. Within the App Settings **Event Subscriptions** page, subscribe to the following events: - [`assistant_thread_started`](/reference/events/assistant_thread_started) - [`assistant_thread_context_changed`](/reference/events/assistant_thread_context_changed) - [`message.im`](/reference/events/message.im) ### Handling a new thread When the user opens a new thread with your AI-enabled app, the [`assistant_thread_started`](/reference/events/assistant_thread_started) event will be sent to your app.
When a user opens an app thread while in a channel, the channel info is stored as the thread's `AssistantThreadContext` data.

You can grab that info by using the `get_thread_context` utility, as subsequent user message event payloads won't include the channel info.

```python assistant = Assistant() @assistant.thread_started def start_assistant_thread( say: Say, get_thread_context: GetThreadContext, set_suggested_prompts: SetSuggestedPrompts, logger: logging.Logger, ): try: say("How can I help you?") prompts: List[Dict[str, str]] = [ { "title": "Suggest names for my Slack app", "message": "Can you suggest a few names for my Slack app? The app helps my teammates better organize information and plan priorities and action items.", }, ] thread_context = get_thread_context() if thread_context is not None and thread_context.channel_id is not None: summarize_channel = { "title": "Summarize the referred channel", "message": "Can you generate a brief summary of the referred channel?", } prompts.append(summarize_channel) set_suggested_prompts(prompts=prompts) except Exception as e: logger.exception(f"Failed to handle an assistant_thread_started event: {e}", e) say(f":warning: Something went wrong! ({e})") ``` You can send more complex messages to the user — see [block kit](#block-kit). --- # Quickstart guide with Bolt for Python This quickstart guide aims to help you get a Slack app using Bolt for Python up and running as soon as possible! When complete, you'll have a local environment configured with a customized [app](https://github.com/slack-samples/bolt-python-getting-started-app) running to modify and make your own. ## Prerequisites A few tools are needed for the following steps. We recommend using the [Slack CLI](https://docs.slack.dev/tools/slack-cli/) for the smoothest experience, but other options remain available. You can also begin by installing git and downloading [Python 3.7 or later](https://www.python.org/downloads/), or the latest stable version of Python. Refer to [Python's setup and building guide](https://devguide.python.org/getting-started/setup-building/) for more details. Install the latest version of the Slack CLI to get started: - [Slack CLI for macOS & Linux](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) - [Slack CLI for Windows](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-windows) Then confirm a successful installation with the following command: ```sh $ slack version ``` An authenticated login is also required if this hasn't been done before: ```sh $ slack login ``` ### A place to belong A workspace where development can happen is also needed. We recommend using [developer sandboxes](https://docs.slack.dev/tools/developer-sandboxes) to avoid disruptions where real work gets done. ## Creating a project With the toolchain configured, it's time to set up a new Bolt project. This contains the code that handles logic for your app. If you don’t already have a project, let’s create a new one! A starter template can be used to start with project scaffolding: ```sh $ slack create first-bolt-app --template slack-samples/bolt-python-getting-started-app $ cd first-bolt-app ``` After a project is created you'll have a `requirements.txt` file for app dependencies and a `.slack` directory for Slack CLI configuration. A few other files exist too, but we'll visit these later. We recommend using a [Python virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) to manage your project's dependencies. This is a great way to prevent conflicts with your system's Python packages. Let's create and activate a new virtual environment with [Python 3.7 or later](https://www.python.org/downloads/): ```sh $ python3 -m venv .venv $ source .venv/bin/activate $ pip install -r requirements.txt ``` Confirm the virtual environment is active by checking that the path to `python3` is _inside_ your project ([a similar command is available on Windows](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment)): ```sh $ which python3 # Output: /path/to/first-bolt-app/.venv/bin/python3 ``` ## Running the app Before you can start developing with Bolt, you will want a running Slack app. ### Slack CLI The getting started app template contains a `manifest.json` file with details about an app that we will use to get started. Use the following command and select "Create a new app" to install the app to the team of choice: ```sh $ slack run ... ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@first-bolt-app (local)` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ### Browser Navigate to your list of apps and [create a new Slack app](https://api.slack.com/apps/new) using the "from a manifest" option: 1. Select the workspace to develop your app in. 2. Copy and paste the `manifest.json` file contents to create your app. 3. Confirm the app features and click "Create". You'll then land on your app's **Basic Information** page, which is an overview of your app and which contains important credentials: ![Basic Information page](https://docs.slack.dev/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) To listen for events happening in Slack (such as a new posted message) without opening a port or exposing an endpoint, we will use [Socket Mode](https://docs.slack.dev/tools/bolt-python/concepts/socket-mode). This connection requires a specific app token: 1. On the **Basic Information** page, scroll to the **App-Level Tokens** section and click **Generate Token and Scopes**. 2. Name the token "Development" or something similar and add the `connections:write` scope, then click **Generate**. 3. Save the generated `xapp` token as an environment variable within your project: ```sh $ export SLACK_APP_TOKEN= ``` The above command works on Linux and macOS but [similar commands are available on Windows](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153). Treat your tokens like a password and [keep it safe](https://docs.slack.dev/security). Your app uses these to retrieve and send information to Slack. A bot token is also needed to interact with the Web API methods as your app's bot user. We can gather this as follows: 1. Navigate to the **OAuth & Permissions** on the left sidebar and install your app to your workspace to generate a token. 2. After authorizing the installation, you'll return to the **OAuth & Permissions** page and find a **Bot User OAuth Token**: ![OAuth Tokens](https://docs.slack.dev/assets/images/bot-token-3d6c761238c7a66557fd08d00a2a1b0c.png) 3. Copy the bot token beginning with `xoxb` from the **OAuth & Permissions page** and then store it in a new environment variable: ```sh $ export SLACK_BOT_TOKEN=xoxb- ``` After saving tokens for the app you created, it is time to run it: ```sh $ python3 app.py ... ⚡️ Bolt app is running! ``` With the app running, you can test it out with the following steps in Slack: 1. Open a direct message with your app or invite the bot `@BoltApp` to a public channel. 2. Send "hello" to the current conversation and wait for a response. 3. Click the attached button labelled "Click Me" to post another reply. After confirming the app responds, celebrate, then interrupt the process by pressing `CTRL+C` in the terminal to stop your app from running. ## Updating the app At this point, you've successfully run the getting started Bolt for Python [app](https://github.com/slack-samples/bolt-python-getting-started-app)! The defaults included leave opportunities abound, so to personalize this app let's now edit the code to respond with a kind farewell. ### Responding to a farewell Chat is a common thing apps do and responding to various types of messages can make conversations more interesting. Using an editor of choice, open the `app.py` file and add the following import to the top of the file, and message listener after the "hello" handler: ```python import random @app.message("goodbye") def message_goodbye(say): responses = ["Adios", "Au revoir", "Farewell"] parting = random.choice(responses) say(f"{parting}!") ``` Once the file is updated, save the changes and then we'll make sure those changes are being used. ### Slack CLI Run the following command and select the app created earlier to start, or restart, your app with the latest changes: ```sh $ slack run ... ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Terminal Run the following command to start, or restart, your app with the latest changes: ```sh $ python3 app.py ... ⚡️ Bolt app is running! ``` After finding the above output appears, open Slack to perform these steps: 1. Return to the direct message or public channel with your bot. 2. Send "goodbye" to the conversation. 3. Receive a parting response from before and repeat "goodbye" to find another one. Your app can be stopped again by pressing `CTRL+C` in the terminal to end these chats. ### Customizing app settings The created app will have some placeholder values and a small set of [scopes](https://docs.slack.dev/reference/scopes) to start, but we recommend exploring the customizations possible on app settings. Open app settings for your app with the following command: ```sh $ slack app settings ``` This will open the following page in a web browser: ![Basic Information page](https://docs.slack.dev/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) Browse to [https://api.slack.com/apps](https://api.slack.com/apps) and select your app "Getting Started Bolt App" from the list. This will open the following page: ![Basic Information page](https://docs.slack.dev/assets/images/basic-information-page-e7d531fe4721830376d61a91de5d933e.png) On these pages you're free to make changes such as updating your app icon, configuring app features, and perhaps even distributing your app! ## Adding AI features Now that you're familiar with a basic app setup, try it out again, this time using the AI agent template! Get started with the agent template: ```sh $ slack create ai-app --template slack-samples/bolt-python-assistant-template $ cd ai-app ``` Using this method, be sure to set the app and bot tokens as we did in the [Running the app](#running-the-app) section above. Once the project is created, update the `.env.sample` file by setting the `OPENAI_API_KEY` with the value of your key and removing the `.sample` from the file name. In the `ai` folder of this app, you'll find default instructions for the LLM and an OpenAI client setup. The `listeners` include utilities intended for messaging with an LLM. Those are outlined in detail in the guide to [Using AI in apps](https://docs.slack.dev/tools/bolt-python/concepts/ai-apps) and [Sending messages](https://docs.slack.dev/tools/bolt-python/concepts/message-sending). ## Next steps Congrats once more on getting up and running with this quick start. ### Dive deeper Follow along with the steps that went into making this app on the [building an app](https://docs.slack.dev/tools/bolt-python/building-an-app) guide for an educational overview. You can now continue customizing your app with various features to make it right for whatever job's at hand. Here are some ideas about what to explore next: - Explore the different events your bot can listen to with the [`app.event()`](https://docs.slack.dev/tools/bolt-python/concepts/event-listening) method. See the full events reference [here](https://docs.slack.dev/reference/events). - Bolt allows you to call [`app.event()`](https://docs.slack.dev/tools/bolt-python/concepts/event-listening) with the `message` event. See the full events reference [here](https://docs.slack.dev/reference/events). - Bolt allows you to call [`app.event()`](https://docs.slack.dev/tools/bolt-python/concepts/event-listening) with the `message` event. See the full events reference [here](https://docs.slack.dev/reference/events). --- # AI Chatbot In this tutorial, you'll learn how to bring the power of AI into your Slack workspace using a chatbot called Bolty that uses Anthropic or OpenAI. Here's what we'll do with this sample app: 1. Create your app from an app manifest and clone a starter template 2. Set up and run your local project 3. Create a workflow using Workflow Builder to summarize messages in conversations 4. Select your preferred API and model to customize Bolty's responses 5. Interact with Bolty via direct message, the `/ask-bolty` slash command, or by mentioning the app in conversations ## Prerequisites Before getting started, you will need the following: - a development workspace where you have permissions to install apps. If you don’t have a workspace, go ahead and set that up now — you can [go here](https://slack.com/get-started#create) to create one, or you can join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. - a development environment with [Python 3.7](https://www.python.org/downloads/) or later. - an Anthropic or OpenAI account with sufficient credits, and in which you have generated a secret key. **Skip to the code** If you'd rather skip the tutorial and just head straight to the code, you can use our [Bolt for Python AI Chatbot sample](https://github.com/slack-samples/bolt-python-ai-chatbot) as a template. ## Creating your app 1. Navigate to the [app creation page](https://api.slack.com/apps/new) and select **From a manifest**. 2. Select the workspace you want to install the application in. 3. Copy the contents of the [`manifest.json`](https://github.com/slack-samples/bolt-python-ai-chatbot/blob/main/manifest.json) file into the text box that says **Paste your manifest code here** (within the **JSON** tab) and click **Next**. 4. Review the configuration and click **Create**. 5. You're now in your app configuration's **Basic Information** page. Navigate to the **Install App** link in the left nav and click **Install to Workspace**, then **Allow** on the screen that follows. ### Obtaining and storing your environment variables Before you'll be able to successfully run the app, you'll need to first obtain and set some environment variables. #### Slack tokens From your app's page on [app settings](https://api.slack.com/apps) collect an app and bot token: 1. On the **Install App** page, copy your **Bot User OAuth Token**. You will store this in your environment as `SLACK_BOT_TOKEN` (we'll get to that next). 2. Navigate to **Basic Information** and in the **App-Level Tokens** section, click **Generate Token and Scopes**. Add the [`connections:write`](/reference/scopes/connections.write) scope, name the token, and click **Generate**. (For more details, refer to [understanding OAuth scopes for bots](/authentication/tokens#bot)). Copy this token. You will store this in your environment as `SLACK_APP_TOKEN`. To store your tokens and environment variables, run the following commands in the terminal. Replace the placeholder values with your bot and app tokens collected above: **For macOS** ```bash export SLACK_BOT_TOKEN= export SLACK_APP_TOKEN= ``` **For Windows** ```powershell set SLACK_BOT_TOKEN= set SLACK_APP_TOKEN= ``` #### Provider tokens Models from different AI providers are available if the corresponding environment variable is added as shown in the sections below. ##### Anthropic To interact with Anthropic models, navigate to your Anthropic account dashboard to [create an API key](https://console.anthropic.com/settings/keys), then export the key as follows: ```bash export ANTHROPIC_API_KEY= ``` ##### Google Cloud Vertex AI To use Google Cloud Vertex AI, [follow this quick start](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstarts/quickstart-multimodal#expandable-1) to create a project for sending requests to the Gemini API, then gather [Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) with the strategy to match your development environment. Once your project and credentials are configured, export environment variables to select from Gemini models: ```bash export VERTEX_AI_PROJECT_ID= export VERTEX_AI_LOCATION= ``` The project location can be located under the **Region** on the [Vertex AI](https://console.cloud.google.com/vertex-ai) dashboard, as well as more details about available Gemini models. ##### OpenAI Unlock the OpenAI models from your OpenAI account dashboard by clicking [create a new secret key](https://platform.openai.com/api-keys), then export the key like so: ```bash export OPENAI_API_KEY= ``` ## Setting up and running your local project Clone the starter template onto your machine by running the following command: ```bash git clone https://github.com/slack-samples/bolt-python-ai-chatbot.git ``` Change into the new project directory: ```bash cd bolt-python-ai-chatbot ``` Start your Python virtual environment: **For macOS** ```bash python3 -m venv .venv source .venv/bin/activate ``` **For Windows** ```bash py -m venv .venv .venv\Scripts\activate ``` Install the required dependencies: ```bash pip install -r requirements.txt ``` Start your local server: ```bash python app.py ``` If your app is up and running, you'll see a message that says "⚡️ Bolt app is running!" ## Choosing your provider Navigate to the Bolty **App Home** and select a provider from the drop-down menu. The options listed will be dependent on which secret keys you added when setting your environment variables. If you don't see Bolty listed under **Apps** in your workspace right away, never fear! You can mention **@Bolty** in a public channel to add the app, then navigate to your **App Home**. ![Choose your AI provider](https://docs.slack.dev/assets/images/6-90ef0d4d041ca7d3607699b802eca6ba.png) ## Setting up your workflow Within your development workspace, open Workflow Builder by clicking on your workspace name and then **Tools > Workflow Builder**. Select **New Workflow** > **Build Workflow**. Click **Untitled Workflow** at the top to rename your workflow. For this tutorial, we'll call the workflow **Welcome to the channel**. Enter a description, such as _Summarizes channels for new members_, and click **Save**. ![Setting up a new workflow](https://docs.slack.dev/assets/images/1-f9c24f965e8474d3c7e673ce05673ffd.png) Select **Choose an event** under **Start the workflow...**, and then choose **When a person joins a channel**. Select the channel name from the drop-down menu and click **Save**. ![Start the workflow](https://docs.slack.dev/assets/images/2-f28431ae65be1c00553a7b2aec61bc10.png) Under **Then, do these things**, click **Add steps** and complete the following: 1. Select **Messages** > **Send a message to a person**. 2. Under **Select a member**, choose **The user who joined the channel** from the drop-down menu. 3. Under **Add a message**, enter a short message, such as _Hi! Welcome to `{{}The channel that the user joined}`. Would you like a summary of the recent conversation?_ Note that the _`{}The channel that the user joined`_ is a variable; you can insert it by selecting **Insert a variable** at the bottom of the message text box. 4. Select the **Add Button** button, and name the button _Yes, give me a summary_. Click **Done**. ![Send a message](https://docs.slack.dev/assets/images/3-905316d2b75f243f2a05ed06eaf32cd0.png) We'll add two more steps under the **Then, do these things** section. First, scroll to the bottom of the list of steps and choose **Custom**, then choose **Bolty** and **Bolty Custom Function**. In the **Channel** drop-down menu, select **Channel that the user joined**. Click **Save**. ![Bolty custom function](https://docs.slack.dev/assets/images/4-dc916f899491971827db1a6ebe7a16aa.png) For the final step, complete the following: 1. Choose **Messages** and then **Send a message to a person**. Under **Select a member**, choose **Person who clicked the button** from the drop-down menu. 2. Under **Add a message**, click **Insert a variable** and choose **`{}Summary`** under the **Bolty Custom Function** section in the list that appears. Click **Save**. ![Summary](https://docs.slack.dev/assets/images/5-51cb5fc9c8350067939001cee6315f8f.png) When finished, click **Finish Up**, then click **Publish** to make the workflow available in your workspace. ## Interacting with Bolty ### Summarizing recent conversations In order for Bolty to provide summaries of recent conversation in a channel, Bolty _must_ be a member of that channel. 1. Invite Bolty to a channel that you are able to leave and rejoin (for example, not the **#general** channel or a private channel someone else created) by mentioning the app in the channel — i.e., tagging **@Bolty** in the channel and sending your message. 2. Slackbot will prompt you to either invite Bolty to the channel, or do nothing. Click **Invite Them**. Now when new users join the channel, the workflow you just created will be kicked off. To test this, leave the channel you just invited Bolty to and rejoin it. This will kick off your workflow and you'll receive a direct message from **Welcome to the channel**. Click the **Yes, give me a summary** button, and Bolty will summarize the recent conversations in the channel you joined. ![Channel summary](https://docs.slack.dev/assets/images/7-a94698b85daeed62f48e11366cae7cba.png) The central part of this functionality is shown in the following code snippet. Note the use of the [`user_context`](/tools/deno-slack-sdk/reference/slack-types#usercontext) object, a Slack type that represents the user who is interacting with our workflow, as well as the `history` of the channel that will be summarized, which includes the ten most recent messages. ```python from ai.providers import get_provider_response from logging import Logger from slack_bolt import Complete, Fail, Ack from slack_sdk import WebClient from .listener_utils.listener_constants import SUMMARIZE_CHANNEL_WORKFLOW from .listener_utils.parse_conversation import parse_conversation """ Handles the event to summarize a Slack channel's conversation history. It retrieves the conversation history, parses it, generates a summary using an AI response, and completes the workflow with the summary or fails if an error occurs. """ def handle_summary_function_callback( ack: Ack, inputs: dict, fail: Fail, logger: Logger, client: WebClient, complete: Complete ): ack() try: user_context = inputs["user_context"] channel_id = inputs["channel_id"] parsed_message = parse_conversation(channel_id, user_context) summary = get_provider_response( "Bolty", "Bolty Custom Function", channel_id, "Channel that the user joined", "Person who clicked the button", "Summary", ) complete(SUMMARIZE_CHANNEL_WORKFLOW, summary) except Exception as e: fail(failure_type="Error", failure_details=e) ``` --- # Bolt for Python Bolt for Python is a Python framework to build Slack apps with the latest Slack platform features. Read the [Getting Started Guide](/tools/bolt-python/getting-started) to set up and run your first Bolt app. Then, explore the rest of the pages within the Guides section. The documentation there will help you build a Bolt app for whatever use case you may have. ## Getting help These docs have lots of information on Bolt for Python. There's also an in-depth Reference section. Please explore! If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/bolt-python/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for Python. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. ## Contributing These docs live within the [Bolt-Python](https://github.com/slackapi/bolt-python/) repository and are open source. We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/bolt-python/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way. --- # Creating functions ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. Functions are one of the three building blocks that make up workflow apps. You will encounter all three as you navigate the path of building your app: 1. Functions define the actions of your app. (⬅️ you are here) 2. Workflows are a combination of functions, executed in order. 3. Triggers execute workflows. There are three types of functions: - **[Slack functions](/tools/deno-slack-sdk/guides/creating-slack-functions)** enable Slack-native actions, like creating a channel or sending a message. - **[Connector functions](/tools/deno-slack-sdk/guides/creating-connector-functions)** enable actions native to services outside of Slack. Google Sheets, Dropbox and Microsoft Excel are just a few of the services with available connector functions. Connector functions cannot be used in a workflow intended for use in a Slack Connect channel. - **[Custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions)** enable developer-specific actions. Pass in any desired inputs, perform any actions you can code up, and pass on outputs to other parts of your workflows. Custom functions also allow your app to create and process workflow steps that users can add in Workflow Builder. See the [Workflow Builder custom step tutorial](/tools/deno-slack-sdk/tutorials/workflow-builder-custom-step/) for instruction. --- # Following security best practices ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. Keeping your apps and functions secure is an important part of developing on the Slack platform. Slack’s managed hosted environment is built on the [Deno](https://deno.land/) runtime, a secure JavaScript runtime. Learn more about Deno’s [permissions model](https://deno.land/manual@v1.32.1/basics/permissions). Here are some best practices to keep in mind when developing [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions), [workflows](/tools/deno-slack-sdk/guides/creating-workflows), and [triggers](/tools/deno-slack-sdk/guides/using-triggers) for Slack automations. ## Set appropriate access control levels (ACLs) - [Limit access](/tools/deno-slack-sdk/guides/managing-triggers#manage) to your [functions](/tools/deno-slack-sdk/guides/creating-custom-functions) and [triggers](/tools/deno-slack-sdk/guides/using-triggers) to only the intended audience. Use the `slack function access` or `slack trigger access` commands to control who can use your functions or trip your triggers. - Your app collaborators can deploy your functions and manage your workflows and triggers. Only add collaborators to your app that you trust. ## Validate input - It’s always important to validate inputs to your functions. If you’ve changed the distribution of your function, keep in mind it may be used in other workflows in ways you may not anticipate. Your app collaborators may also create or update triggers to start your workflows. - When using Slack [datastores](/tools/deno-slack-sdk/guides/using-datastores), avoid [injection attacks](https://owasp.org/Top10/A03_2021-Injection/) by properly sanitizing user input when building queries, and use the `expression_values` and `expression_attributes` fields when querying for data. Also ensure that the user has read access to data from the datastore before processing it. - Always confirm the user has access to perform whatever operation your function is being asked to perform. In complex workflows, several users may participate in the various steps, so ensure you’re checking the correct user’s permissions. For example, in a contract approval workflow, anyone may be able to request an approval, but only certain approvers may actually provide an approval. - When listening to [message metadata events](/tools/deno-slack-sdk/guides/integrating-message-metadata-events), keep in mind that many apps may be posting messages with the same event types. If you’d like to listen to messages from only specific apps, use a filter on the `app_id` in the event trigger definition. ## Handle sensitive data - Secrets needed by your custom functions running on Slack-managed infrastructure should be shared with Slack using the `slack env add` command and never hard-coded in your functions. Examples are API keys, OAuth client IDs and secrets, certificates, and cryptography keys. If possible, use Slack’s [third party auth support](https://docs.slack.dev/faq#third-party) to manage OAuth-based credentials. - For local apps using `slack run`, ensure that the `.env` file containing local secrets does not end up in your source control system. - When using `slack env add`, ensure the secret does not end up in your shell’s history. This can be done using shell environment variables, or by running `slack env add` without any parameters. With no parameters, `slack env add` will prompt you for the secret’s name and value in the console, using a password display. - Be careful about collecting or logging sensitive information in workflows from users, especially passwords or personally identifiable information (PII). Data may be exposed to later workflow steps, in data exports, or in activity logs. ## Secure credentials - The Slack CLI stores credentials in the `credentials.json` file in the `.slack` folder in your home directory. Slack will never ask you share the tokens contained in that file. - While these credentials expire and are regularly rotated, access to this file should be limited to only you. - Never share the tokens or challenge strings generated by the `slack login` flow. - Never paste a `/slackauthticket` command given to you by another user into Slack. ## Use secure libraries - It is your responsibility to monitor and respond to security vulnerabilities in your custom function’s code and dependencies, and to deploy new versions to Slack-managed infrastructure as needed. - Keep your Slack CLI and SDKs up to date by upgrading when prompted. - Only use a Slack CLI download by following instructions found within the [Slack CLI docs](/tools/slack-cli/). ## Handle network egress - Slack’s `outgoingDomains` configuration limits which domains your custom function code can use when making external network requests. Only list `outgoingDomains` if the domains are required by your functions. ## Make scopes and tokens - Functions are given a short-lived token that can be used to make [Slack API](/tools/deno-slack-sdk/guides/calling-slack-api-methods) calls, which use the scopes requested in the app’s manifest. We recommend only sending these tokens to Slack API endpoints, and not logging them or sending them to external systems. - Only request the scopes your functions need to do their job. Following these guidelines will get you on your way to building secure workflow apps. --- # Getting started with the Deno Slack SDK ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. In the following guide, you'll install the Slack CLI and authorize it in your workspace. Then, you'll use the Slack CLI to scaffold a fully-functional workflow app and run it locally. Don't have a workspace yet? You can get up and running by provisioning a sandbox with an associated workspace by following [this guide](/tools/developer-sandboxes/). Come on back when you're ready! ## Step 1: Install the Slack CLI Refer to [these instructions](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) to install the latest version of the Slack CLI. The instructions will guide you through installing the Slack CLI and all required dependencies. ## Step 2: Authorize the Slack CLI With the Slack CLI installed, authorize the Slack CLI in your workspace with the following command: ```bash slack login ``` In your terminal window, you should see an authorization ticket in the form of a slash command, and a prompt to enter a challenge code: ```bash $ slack login 📋 Run the following slash command in any Slack channel or DM This will open a modal with user permissions for you to approve Once approved, a challenge code will be generated in Slack /myworkspace (Team ID: T123ABC456) User ID: U123ABC456 Last updated: 2023-01-01 12:00:00 -07:00 Authorization Level: Workspace ``` You should see an entry for the workspace you just authorized. If you don't, get a new authorization ticket with `slack login` to try again. ## Step 3: Create an app from a template Evaluate third-party apps and exercise caution when using third-party applications and automations (those outside of [`slack-samples`](https://github.com/slack-samples)). Review all source code created by third-parties before running `slack create` or `slack deploy`. The `create` command is how you create a workflow app. For this guide, we'll be creating a Slack app using the [Deno Starter Template](https://github.com/slack-samples/deno-starter-template) as a template: ```bash slack create my-app --template https://github.com/slack-samples/deno-starter-template ``` The Slack CLI creates an app project folder and fills it with the sample app code. Once it has finished, `cd` into your new project directory: ```bash cd my-app ``` Then continue to the next step. ## Step 4: Run the app in local development mode While building your app, you can see your changes propagated to your workspace in real-time by running `slack run` within your app's directory. When you execute `slack run`, you'll be asked to select a local environment: ```bash ? Choose a local environment > Install to a new workspace or organization ``` Since you've not installed your app to any workspaces, select _Install to a new workspace_. Then select the workspace you authenticated in. The Slack CLI will attempt to list any triggers, and in this case, will inform you there are no existing triggers installed for the app. [Triggers](/tools/deno-slack-sdk/guides/using-triggers) are what cause workflows to run. A [link trigger](/tools/deno-slack-sdk/guides/creating-link-triggers) generates a _Shortcut URL_ which, when posted in a channel or added as a bookmark, becomes a link. Triggers are created from trigger definition files. The Slack CLI will then look for any trigger definition files and prompt you to select one. In this case, there is only one trigger: `sample_trigger.ts`. Select it. ```bash ? Choose a trigger definition file: > triggers/sample_trigger.ts Do not create a trigger ``` Once your app's trigger is created, you will see the following output: ```bash ⚡ Trigger successfully created! Sample trigger (local) Ft0123ABC456 (shortcut) Created: 2023-01-01 12:00:00 -07:00 (1 second ago) Collaborators: You! @You U123ABC456DE Can be found and used by: everyone in the workspace https://slack.com/shortcuts/Ft0123ABC456/XYZ123 ``` The Slack CLI will also start a local development server, syncing changes to your workspace's development version of your app. You'll know your local development server is up and running when your terminal window tells you it's `Connected, awaiting events`. ## Step 5: Use your app Grab the `Shortcut URL` you generated in the previous step and paste it in a public channel in your workspace. You will see the shortcut unfurl with a "Start Workflow" button. Click the button to execute the shortcut. In the modal that appears, select a channel, and enter a message. When you click the "Send message" button, you should see your message appear in the channel you specified. When you want to turn _off_ the local development server, use `Ctrl+c` in the command prompt. --- ## Onward At this point your Slack CLI is fully authorized and ready to create new projects. It's time to choose the next path of adventure. We have curated a collection of sample apps. Many have tutorials. All highlight features of workflow apps. Learn how to: - design [datastores](/tools/deno-slack-sdk/guides/using-datastores) to store data with the [Virtual Running Buddies app](/tools/deno-slack-sdk/tutorials/virtual-running-buddies-app). - send [event-triggered](/tools/deno-slack-sdk/guides/creating-event-triggers) automated [messages](/tools/deno-slack-sdk/reference/slack-functions/send_message) with the [Welcome Bot app](/tools/deno-slack-sdk/tutorials/welcome-bot). - create [forms](/tools/deno-slack-sdk/guides/creating-a-form) to receive user input with the [Give Kudos app](/tools/deno-slack-sdk/tutorials/give-kudos-app). Each tutorial will expose you to many aspects of the workflow automations. If you'd rather explore the documentation on your own, here are a few places to start. You can learn how to: - [deploy your app](/tools/deno-slack-sdk/guides/deploying-to-slack) so you don't need to run it locally. - [build an app from scratch](/tools/deno-slack-sdk/guides/creating-an-app). - use workflow apps in conjunction with other services, whether that's with [third-party API calls](/faq#third-party) or [external authentication](/tools/deno-slack-sdk/guides/integrating-with-services-requiring-external-authentication). - use the [Deno Slack SDK](https://github.com/slackapi/deno-slack-sdk) in tandem with the Slack CLI to access the API, additional documentation, and code libraries. You'll first need to download and install [Deno](/tools/deno-slack-sdk/guides/installing-deno). If you're using VSCode for development, make sure to also download the [Deno extension for VSCode](/tools/deno-slack-sdk/guides/installing-deno#vscode). --- # Deno Slack SDK ## Workflow apps require a paid plan Join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free. You can create Slack-hosted workflows written in TypeScript using the [Deno Slack SDK](https://github.com/slackapi/deno-slack-sdk). Workflows are a combination of functions, executed in order. There are three types of functions: - **Slack functions** enable Slack-native actions, like creating a channel or sending a message. - **Connector functions** enable actions native to services _outside_ of Slack. Google Sheets, Dropbox, and Microsoft Excel are a few of the services with available connector functions. - **Custom functions** enable developer-specific actions. Pass in any desired inputs, perform any actions you can code up, and pass on outputs to other parts of your workflows. Workflows are invoked via triggers. You can invoke workflows: - via a link within Slack, - on a schedule, - when specified events occur, - or via webhooks. Workflows make use of specifically designed features of the Slack platform such as [datastores](/tools/deno-slack-sdk/guides/using-datastores), a Slack-hosted way to store data. While in development, you can keep your project mostly to yourself, or share it with a close collaborator. If your Slack admin requires approval of app installations, they’ll need to approve what you’re creating first. ### The app management UI on `api.slack.com/apps` doesn't support configuring workflow apps. Workflow apps are also currently not eligible for listing in the Slack Marketplace. ## Getting help These docs have lots of information on the Deno Slack SDK. Please explore! If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/deno-slack-sdk/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. --- # Installing the Slack CLI for Mac & Linux The Slack CLI is a useful tool for building Slack apps. This is your one-stop shop for installing this tool. ## Automated Installation **Run the automated installer from your terminal window:** ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash ``` This will install the Slack CLI and configure the command. ### Runtime Installations Runtime installations are left to the developer and depend on the app being built. For more information and next steps, review the quickstart guides: - [Bolt for JavaScript](/tools/bolt-js/getting-started) - [Bolt for Python](/tools/bolt-python/getting-started) - [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started) #### Optional: Use an Alias for the Slack CLI Binary If you have another CLI tool in your path called `slack`, you can rename this `slack` binary to a different name to avoid errors during installation. The Slack CLI won't overwrite the existing one! To do this, pass the `-s` argument and an alias to the automated installer: ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s ``` The alias you use should come after any flags used in the installer. For example, if you use the version flag your installation script might look like this: ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v 2.1.0 ``` #### Optional: Download a Specific Version The latest Slack CLI version is installed by default, but a particular version can be pinned using the `-v` flag: ```sh curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash -s -- -v 2.1.0 ``` #### Troubleshooting: Command Not Found After running the Slack CLI installation script, the `slack` command might not be available in the current shell. The download has often succeeded but a symbolic link to the command needs to be added to your path. Determine which shell you're using then update your shell profile with the following commands: ```sh basename "$SHELL" ``` - **bash**: ```sh echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc ``` - **fish**: ```sh mkdir -p $HOME/.config/fish echo 'fish_add_path $HOME/.local/bin' >> $HOME/.config/fish/config.fish source $HOME/.config/fish/config.fish ``` - **zsh**: ```sh echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` Once the profile is sourced, or a new shell is opened, the `slack` command should be available. ## Manual Installation Manual installation allows you to customize certain paths used when installing the Slack CLI. Runtime installations are omitted from these steps but are still required to run an app. ### 1. Download and Install Git Download and install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), a dependency of the `slack` CLI. ### 2. Download the Slack CLI Installer for Your Environment 🍎 ⚡️ [Download for macOS Apple Silicon (.tar.gz)](https://downloads.slack-edge.com/slack-cli/slack_cli_3.10.0_macOS_arm64.tar.gz) 🍏 🪨 [Download for macOS Intel (.tar.gz)](https://downloads.slack-edge.com/slack-cli/slack_cli_3.10.0_macOS_amd64.tar.gz) 🐧 💾 [Download for Linux (.tar.gz)](https://downloads.slack-edge.com/slack-cli/slack_cli_3.10.0_linux_64-bit.tar.gz) ### 3. Add the `slack` CLI to Your Path Create a symbolic link to the Slack CLI download from (or move the downloaded binary to) any folder that is already in your path. In the following example, we download the Slack CLI to the `.slack` directory and create a symbolic link to `.local` path: ```sh ln -s "$HOME/.slack/bin/slack" "$HOME/.local/bin/slack" ``` We recommend using an alias if another `slack` binary exists. To do this, change the alias used at the end of the symbolic link to something else that makes sense, or rename the moved download to something special. ### 4. Verify That `slack` Is Installed and in Your Path ```sh $ slack version Using slack v3.10.0 ``` --- # Running Slack CLI commands The Slack CLI allows you to interact with your apps via the command line. Using the main command `slack`, you can create, run, and deploy apps, as well as create triggers and query datastores. ## Running `slack help` will display available commands in your terminal window. Use commands as follows (unless otherwise noted): ```text slack [flags] ``` To view global flags and each subcommands flags, run the following in your terminal: ```text slack --help ``` ## Commands overview Below you'll find all the commands and subcommands for the Slack CLI. Each one has its own reference page. | Command | Description | | --- | --- | | [slack activity](/tools/slack-cli/reference/commands/slack_activity) | Display the app activity logs from the Slack Platform | | [slack app](/tools/slack-cli/reference/commands/slack_app) | Install, uninstall, and list teams with the app installed | | [slack auth](/tools/slack-cli/reference/commands/slack_auth) | Add and remove local team authorizations | | [slack collaborator](/tools/slack-cli/reference/commands/slack_collaborator) | Manage app collaborators | | [slack create](/tools/slack-cli/reference/commands/slack_create) | Create a Slack project | | [slack datastore](/tools/slack-cli/reference/commands/slack_datastore) | Query an app's datastore | | [slack delete](/tools/slack-cli/reference/commands/slack_delete) | Delete the app | | [slack deploy](/tools/slack-cli/reference/commands/slack_deploy) | Deploy the app to the Slack Platform | | [slack doctor](/tools/slack-cli/reference/commands/slack_doctor) | Check and report on system and app information | | [slack env](/tools/slack-cli/reference/commands/slack_env) | Add, remove, and list environment variables | | [slack external-auth](/tools/slack-cli/reference/commands/slack_external-auth) | Add and remove external authorizations and client secrets for providers in your app | | [slack feedback](/tools/slack-cli/reference/commands/slack_feedback) | Share feedback about your experience or project | | [slack function](/tools/slack-cli/reference/commands/slack_function) | Manage the functions of an app | | [slack install](/tools/slack-cli/reference/commands/slack_install) | Install the app to a team | | [slack list](/tools/slack-cli/reference/commands/slack_list) | List all authorized accounts | | [slack login](/tools/slack-cli/reference/commands/slack_login) | Log in to a Slack account | | [slack logout](/tools/slack-cli/reference/commands/slack_logout) | Log out of a team | | [slack manifest](/tools/slack-cli/reference/commands/slack_manifest) | Print the app manifest of a project or app | | [slack platform](/tools/slack-cli/reference/commands/slack_platform) | Deploy and run apps on the Slack Platform | | [slack run](/tools/slack-cli/reference/commands/slack_run) | Start a local server to develop and run the app locally | | [slack samples](/tools/slack-cli/reference/commands/slack_samples) | List available sample apps | | [slack trigger](/tools/slack-cli/reference/commands/slack_trigger) | List details of existing triggers | | [slack uninstall](/tools/slack-cli/reference/commands/slack_uninstall) | Uninstall the app from a team | | [slack upgrade](/tools/slack-cli/reference/commands/slack_upgrade) | Checks for available updates to the CLI or SDK | | [slack version](/tools/slack-cli/reference/commands/slack_version) | Print the version number | [Previous: Using on Enterprise Grid](/tools/slack-cli/guides/using-slack-cli-on-an-enterprise-grid-organization) [Next: Using environment variables](/tools/slack-cli/guides/using-environment-variables-with-the-slack-cli) --- # Using environment variables with the Slack CLI Storing and using environment variables in an application allows for certain variables to be maintained outside of the code of the application. You can use environment variables from within Slack [functions](/tools/deno-slack-sdk/guides/creating-custom-functions), [triggers](/tools/deno-slack-sdk/guides/using-triggers), and [manifests](/tools/deno-slack-sdk/guides/using-the-app-manifest). ## Using environment variables with a custom function When accessing environment variables from within a [custom function](/tools/deno-slack-sdk/guides/creating-custom-functions), where you store them differs when the app is local versus deployed. ### Storing local environment variables Local environment variables are stored in a `.env` file at the root of the project and made available for use in [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions) via the `env` [context property](/tools/deno-slack-sdk/guides/creating-custom-functions#context). A local `.env` file might look like this: ```env MY_ENV_VAR=asdf1234 ``` Note that changes to your `.env` file will be reflected when you restart your local development server. While the `.env` file should **never** be committed to source control for security reasons, you can see a sample `.env` file we've included in the [Timesheet approval sample app](https://github.com/slack-samples/deno-timesheet-approval) and the [Incident management sample app](https://github.com/slack-samples/deno-incident-management). ### Storing deployed environment variables When your app is [deployed](/tools/deno-slack-sdk/guides/deploying-to-slack), it will no longer use the `.env` file. Instead, you will have to add the environment variables using the [`env add`](/tools/slack-cli/reference/commands/slack_env_add) command. Environment variables added with `env add` will be made available to your deployed app's [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions) just as they are locally; see examples in the next section. For the above example, we could run the following command before deploying our app: ```zsh slack env add MY_ENV_VAR asdf1234 ``` If your token contains non-alphanumeric characters, wrap it in quotes like this: ```zsh slack env add SLACK_API_URL "https://dev.slack.com/api/" ``` Your environment variables are always encrypted before being stored on our servers and will be automatically decrypted when you use them—including when listing environment variables with `slack env list`. ### Access variables from within function We can retrieve the `MY_ENV_VAR` environment variable from within a [custom Slack function](/tools/deno-slack-sdk/guides/creating-custom-functions) via the `env` [context property](/tools/deno-slack-sdk/guides/creating-custom-functions#context) like this: ```javascript // functions/my_function.ts import { DefineFunction, SlackFunction } from 'deno-slack-sdk/mod.ts'; import { MyFunctionDefinition } from 'functions/myfunction.ts'; export default SlackFunction(MyFunctionDefinition, ({ env }) => { const myEnvVar = env["MY_ENV_VAR"]; // ... return { outputs: {} }; }); ``` Environment variables also play an important part in making calls to a third-party API. Learn more about how to do that in the [FAQ](https://docs.slack.dev/faq#third-party). ## Using environment variables with a trigger or manifest Accessing environment variables from within a [trigger](/tools/deno-slack-sdk/guides/using-triggers) definition or when constructing the [manifest](/tools/deno-slack-sdk/guides/using-the-app-manifest) differs slightly from custom functions. Whether your app is being run locally or already deployed, constructing these definitions happens entirely on your machine and so the environment variables stored on your machine are used. ### Storing environment variables Environment variables used in trigger or manifest definitions should be saved in the local `.env` file for your project [as shown above](#local-env-vars). The values from this file are collected and used when generating these definitions. Regardless of whether you're working with a local or deployed app, the same values from this file will be used. Read on to learn how to access these stored variables in code. ### Accessing variables from a trigger or manifest The Deno runtime provides a helpful `load` function to autoload environment variables as part of the `dotenv` module of the standard library. We'll leverage this to easily access our environment variables. Including this module in code will automatically import local environment variables for immediate use! Start by adding [the latest version](https://deno.land/std/dotenv/mod.ts) of this module to your `import_map.json`: ```json { "imports": { "deno-slack-sdk/": "https://deno.land/x/deno_slack_sdk@a.b.c/", "deno-slack-api/": "https://deno.land/x/deno_slack_api@x.y.z/", "std/": "https://deno.land/std@0.202.0/" } } ``` Then, you can import the module into any file that makes use of environment variables and start accessing the environment with [`Deno.env.get("VARIABLE_NAME")`](https://examples.deno.land/environment-variables) like so: ```javascript // manifest.ts import { Manifest } from 'deno-slack-sdk/mod.ts'; import ExampleWorkflow from "./workflows/example_workflow.ts"; import "std/dotenv/load.ts"; export default Manifest({ name: "Chatbot4000", displayName: Deno.env.get("CHATBOT_DISPLAY_NAME"), description: "Workflows for communicating with an imagined chatbot", icon: "assets/icon.png", workflows: [ExampleWorkflow], outgoingDomains: [ Deno.env.get("CHATBOT_API_URL")! ], botScopes: ["commands", "chat:write", "chat:write.public"], }); ``` After including this new module, you may have to run [`deno cache manifest.ts`](https://docs.deno.com/runtime/manual/getting_started/command_line_interface#cache-and-compilation-flags) to refresh your local dependency cache. Variable values such as these are commonly used to specify [outgoing domains](/tools/deno-slack-sdk/guides/using-the-app-manifest#manifest-properties) used by functions, channel IDs for [event triggers](/tools/deno-slack-sdk/guides/creating-event-triggers#event-object), or client IDs of an [external authentication](/tools/deno-slack-sdk/guides/integrating-with-services-requiring-external-authentication#define) provider. But, don't let that limit you — environment variables can be used in so many other places! #### Requiring environment variables values Setting values for environment variables can sometimes be forgotten, which can cause problems at runtime. Catching errors for these missing values early is often better than waiting for that runtime problem. Including a `!` with your call to `Deno.env.get()` will ensure this value is defined at the time of building a definition and will throw an error otherwise. The previous example uses this pattern to ensure an outgoing domain is always set: ```javascript outgoingDomains: [ Deno.env.get("CHATBOT_API_URL")!", ], ``` With this addition, running `slack deploy` without defining a value for `CHATBOT_API_URL` in the `.env` file will throw an error to give you a chance to set it before actually deploying! ## Enabling debug mode The included environment variable `SLACK_DEBUG` can enable a basic debug mode. Set `SLACK_DEBUG` to `true` to have all function-related payloads logged. For local apps, add the following to your `.env` file: ```text SLACK_DEBUG=true ``` For deployed apps, run the following command before deployment: ```text slack env add SLACK_DEBUG true ``` ## Included local and deployed variables Slack provides two environment variables by default, `SLACK_WORKSPACE` and `SLACK_ENV`. The workspace name is specified by `SLACK_WORKSPACE` and `SLACK_ENV` provides a distinction between the `local` and `deployed` app. Use these values if you want to have different values based on the workspace or environment that the app is installed in. These variables are automatically included when generating the manifest or triggers only. For access from within a custom function, these variables can be set from the `.env` file or with the [`env add`](/tools/slack-cli/reference/commands/slack_env_add) command. A custom `WorkspaceMapSchema` can be created and used with these variables to decide which values to use for certain instances of an app. This can be used as an alternative to a local `.env` file or in conjunction with it. The following snippet works well for inclusion in your app manifest, or for triggers (for example, to change event trigger channel IDs): ```javascript // functions/my_function.ts import { DefineFunction, SlackFunction } from 'deno-slack-sdk/mod.ts'; import { MyFunctionDefinition } from 'functions/myfunction.ts'; export default SlackFunction(MyFunctionDefinition, ({ env }) => { const myEnvVar = env["MY_ENV_VAR"]; // ... return { outputs: {} }; }); --- # Using the Slack CLI with Bolt frameworks You can use the Slack CLI to streamline development of apps using [Bolt for JavaScript](/tools/bolt-js) and [Bolt for Python](/tools/bolt-python). ## Feeling adventurous? To create a Bolt app using features currently under development, refer to the [experiments](/tools/slack-cli/reference/experiments) page. ## Getting started Creating a Bolt app via the Slack CLI is similar to creating other apps with the Slack CLI. Run the following command to begin: ```text slack create ``` Select an option from the following list. For this example, choose **Starter app**: ```zsh > Starter app - Getting started Slack app Automation app - Custom steps and workflows AI app - Slack agents & assistants View more samples ``` You will then be prompted to choose between **Bolt for JavaScript** or **Bolt for Python**. Choose your favorite flavor. Your app will be cloned from the respective [JavaScript](https://github.com/slack-samples/bolt-js-starter-template) or [Python](https://github.com/slack-samples/bolt-python-starter-template) project template on our Slack Platform Sample Code repository, and its project dependencies will be installed. Then, `cd` into your project folder. > For Bolt for Python projects, automatic project dependency installation is currently unsupported, and will need to be done manually. > > For more information, refer to [Getting started with Bolt for Python](/tools/bolt-python/getting-started). To run your new app, use the `slack run` command with the experiment flag as follows: ```text slack run ``` You'll be prompted to choose your team/workspace, and then your app should let you know that it's up and running. 🎉 ## App manifest The Slack app manifest is the configuration of the app. The `manifest.json` file included with selected templates and samples reflects the features and permissions of your app. When you create an app with the CLI, the corresponding app and matching manifest can be found on [app settings](https://api.slack.com/apps). For Bolt apps created through the CLI, by default, the manifest source set in the `config.json` file is `remote`. This means that the manifest in your [app settings](https://api.slack.com/apps) is the source of truth. To modify the manifest (add new features, scopes, etc.), do so in the app settings. If you change the `config.json` to reflect a `local` manifest source and modify the local `manifest.json` file, the CLI will ask for confirmation before overriding the settings upstream on reinstall (run). This prompt appears if the app manifest on app settings differs from a known state saved in `.slack/cache`. There is not currently a dedicated manifest update command. In contrast, Deno apps created with the CLI have the manifest source configuration of `local` because those apps are not managed in the [app settings page](https://api.slack.com/apps). [Previous: Authorizing the Slack CLI](/tools/slack-cli/guides/authorizing-the-slack-cli) [Next: Using on Enterprise Grid](/tools/slack-cli/guides/using-slack-cli-on-an-enterprise-grid-organization) --- # Slack CLI The Slack command-line interface (CLI) allows you to create and manage Slack apps from the command line. Use it in combination with the Deno Slack SDK, or the Bolt frameworks for JavaScript and Python. Follow the installation guide for either [MacOS / Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) or [Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) to get set up. Then, follow the [Authorization guide](/tools/slack-cli/guides/authorizing-the-slack-cli) to connect your workspace. ## Getting help This site has lots of guides on the Slack CLI. There's also an in-depth reference both for [commands](/tools/slack-cli/reference/commands/slack) and [errors](/tools/slack-cli/reference/errors). If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue: - [Issue Tracker](http://github.com/slackapi/slack-cli/issues) for questions, bug reports, feature requests, and general discussion related to the Slack CLI. Try searching for an existing issue before creating a new one. - [Email](mailto:support@slack.com) our developer support team: `support@slack.com`. ## Contributing These docs live within the open source [Slack CLI](https://github.com/slackapi/slack-cli) repository. We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/slack-cli/blob/main/.github/CONTRIBUTING.md) for how to contribute in a helpful and collaborative way. --- # Source: https://docs.slack.dev/tools/slack-cli/guides/using-environment-variables-with-the-slack-cli # Using environment variables with the Slack CLI Storing and using environment variables in an application allows for certain variables to be maintained outside of the code of the application. You can use environment variables from within Slack [functions](/tools/deno-slack-sdk/guides/creating-custom-functions), [triggers](/tools/deno-slack-sdk/guides/using-triggers), and [manifests](/tools/deno-slack-sdk/guides/using-the-app-manifest). ## Using environment variables with a custom function When accessing environment variables from within a [custom function](/tools/deno-slack-sdk/guides/creating-custom-functions), where you store them differs when the app is local versus deployed. ### Storing local environment variables Local environment variables are stored in a `.env` file at the root of the project and made available for use in [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions) via the `env` [context property](/tools/deno-slack-sdk/guides/creating-custom-functions#context). A local `.env` file might look like this: ```env MY_ENV_VAR=asdf1234 ``` Note that changes to your `.env` file will be reflected when you restart your local development server. While the `.env` file should **never** be committed to source control for security reasons, you can see a sample `.env` file we've included in the [Timesheet approval sample app](https://github.com/slack-samples/deno-timesheet-approval) and the [Incident management sample app](https://github.com/slack-samples/deno-incident-management). ### Storing deployed environment variables When your app is [deployed](/tools/deno-slack-sdk/guides/deploying-to-slack), it will no longer use the `.env` file. Instead, you will have to add the environment variables using the [`env add`](/tools/slack-cli/reference/commands/slack_env_add) command. Environment variables added with `env add` will be made available to your deployed app's [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions) just as they are locally; see examples in the next section. For the above example, we could run the following command before deploying our app: ```zsh slack env add MY_ENV_VAR asdf1234 ``` If your token contains non-alphanumeric characters, wrap it in quotes like this: ```zsh slack env add SLACK_API_URL "https://dev.slack.com/api/" ``` Your environment variables are always encrypted before being stored on our servers and will be automatically decrypted when you use them—including when listing environment variables with `slack env list`. ### Access variables from within function We can retrieve the `MY_ENV_VAR` environment variable from within a [custom Slack function](/tools/deno-slack-sdk/guides/creating-custom-functions) via the `env` [context property](/tools/deno-slack-sdk/guides/creating-custom-functions#context) like this: ```javascript // functions/my_function.ts import { DefineFunction, SlackFunction } from 'deno-slack-sdk/mod.ts'; import { MyFunctionDefinition } from 'functions/myfunction.ts'; export default SlackFunction(MyFunctionDefinition, ({ env }) => { const myEnvVar = env["MY_ENV_VAR"]; // ... return { outputs: {} }; }); ``` Environment variables also play an important part in making calls to a third-party API. Learn more about how to do that in the [FAQ](https://docs.slack.dev/faq#third-party). ## Using environment variables with a trigger or manifest Accessing environment variables from within a [trigger](/tools/deno-slack-sdk/guides/using-triggers) definition or when constructing the [manifest](/tools/deno-slack-sdk/guides/using-the-app-manifest) differs slightly from custom functions. Whether your app is being run locally or already deployed, constructing these definitions happens entirely on your machine and so the environment variables stored on your machine are used. ### Storing environment variables Environment variables used in trigger or manifest definitions should be saved in the local `.env` file for your project [as shown above](#local-env-vars). The values from this file are collected and used when generating these definitions. Regardless of whether you're working with a local or deployed app, the same values from this file will be used. Read on to learn how to access these stored variables in code. ### Accessing variables from a trigger or manifest The Deno runtime provides a helpful `load` function to autoload environment variables as part of the `dotenv` module of the standard library. We'll leverage this to easily access our environment variables. Including this module in code will automatically import local environment variables for immediate use! Start by adding [the latest version](https://deno.land/std/dotenv/mod.ts) of this module to your `import_map.json`: ```json { "imports": { "deno-slack-sdk/": "https://deno.land/x/deno_slack_sdk@a.b.c/", "deno-slack-api/": "https://deno.land/x/deno_slack_api@x.y.z/", "std/": "https://deno.land/std@0.202.0/" } } ``` Then, you can import the module into any file that makes use of environment variables and start accessing the environment with [`Deno.env.get("VARIABLE_NAME")`](https://examples.deno.land/environment-variables) like so: ```javascript // manifest.ts import Manifest from 'deno-slack-sdk/mod.ts'; import ExampleWorkflow from "./workflows/example_workflow.ts"; import "std/dotenv/load.ts"; export default Manifest({ name: "Chatbot4000", displayName: Deno.env.get("CHATBOT_DISPLAY_NAME"), description: "Workflows for communicating with an imagined chatbot", icon: "assets/icon.png", workflows: [ExampleWorkflow], outgoingDomains: [ Deno.env.get("CHATBOT_API_URL")! ], botScopes: ["commands", "chat:write", "chat:write.public"], }); ``` After including this new module, you may have to run [`deno cache manifest.ts`](https://docs.deno.com/runtime/manual/getting_started/command_line_interface#cache-and-compilation-flags) to refresh your local dependency cache. Variable values such as these are commonly used to specify [outgoing domains](/tools/deno-slack-sdk/guides/using-the-app-manifest#manifest-properties) used by functions, channel IDs for [event triggers](/tools/deno-slack-sdk/guides/creating-event-triggers#event-object), or client IDs of an [external authentication](/tools/deno-slack-sdk/guides/integrating-with-services-requiring-external-authentication#define) provider. But, don't let that limit you — environment variables can be used in so many other places! #### Requiring environment variables values Setting values for environment variables can sometimes be forgotten, which can cause problems at runtime. Catching errors for these missing values early is often better than waiting for that runtime problem. Including a `!` with your call to `Deno.env.get()` will ensure this value is defined at the time of building a definition and will throw an error otherwise. The previous example uses this pattern to ensure an outgoing domain is always set: ```javascript outgoingDomains: [ Deno.env.get("CHATBOT_API_URL")!", ] ``` With this addition, running `slack deploy` without defining a value for `CHATBOT_API_URL` in the `.env` file will throw an error to give you a chance to set it before actually deploying! ## Enabling debug mode The included environment variable `SLACK_DEBUG` can enable a basic debug mode. Set `SLACK_DEBUG` to `true` to have all function-related payloads logged. For local apps, add the following to your `.env` file: ```text SLACK_DEBUG=true ``` For deployed apps, run the following command before deployment: ```text slack env add SLACK_DEBUG true ``` ## Included local and deployed variables Slack provides two environment variables by default, `SLACK_WORKSPACE` and `SLACK_ENV`. The workspace name is specified by `SLACK_WORKSPACE` and `SLACK_ENV` provides a distinction between the `local` and `deployed` app. Use these values if you want to have different values based on the workspace or environment that the app is installed in. These variables are automatically included when generating the manifest or triggers only. For access from within a custom function, these variables can be set from the `.env` file or with the [`env add`](/tools/slack-cli/reference/commands/slack_env_add) command. A custom `WorkspaceMapSchema` can be created and used with these variables to decide which values to use for certain instances of an app. This can be used as an alternative to a local `.env` file or in conjunction with it. The following snippet works well for inclusion in your app manifest, or for triggers (for example, to change event trigger channel IDs): ```javascript // Custom schemas can be defined for workspace values type WorkspaceSchema = { channel_id: string }; type WorkspaceMapSchema = { [workspace: string]: { [environment: string]: WorkspaceSchema; }; }; // Custom values can be set for each known workspace export const workspaceValues: WorkspaceMapSchema = { beagoodhost: { deployed: { channel_id: "C123ABC456", }, local: { channel_id: "C123ABC456", }, }, sandbox: { deployed: { channel_id: "C222BBB222", }, local: { channel_id: "C222BBB222", }, }, }; // Fallback options can also be defined export const defaultValue: WorkspaceSchema = { channel_id: "{{data.channel_id}}", }; // Included environment variables will determine which value is used const environment = Deno.env.get("SLACK_ENV") || ""; const workspace = Deno.env.get("SLACK_WORKSPACE") || ""; const { channel_id } = workspaceValues[workspace]?.environment ?? ""; defaultValues; ``` --- # Source: https://docs.slack.dev/tools/slack-cli/guides/using-slack-cli-with-bolt-frameworks # Using the Slack CLI with Bolt frameworks You can use the Slack CLI to streamline development of apps using [Bolt for JavaScript](/tools/bolt-js) and [Bolt for Python](/tools/bolt-python). ## Feeling adventurous? To create a Bolt app using features currently under development, refer to the [experiments](/tools/slack-cli/reference/experiments) page. ## Getting started Creating a Bolt app via the Slack CLI is similar to creating other apps with the Slack CLI. Run the following command to begin: ```text slack create ``` Select an option from the following list. For this example, choose **Starter app**: ```zsh > Starter app - Getting started Slack app Automation app - Custom steps and workflows AI app - Slack agents & assistants View more samples ``` You will then be prompted to choose between **Bolt for JavaScript** or **Bolt for Python**. Choose your favorite flavor. Your app will be cloned from the respective [JavaScript](https://github.com/slack-samples/bolt-js-starter-template) or [Python](https://github.com/slack-samples/bolt-python-starter-template) project template on our Slack Platform Sample Code repository, and its project dependencies will be installed. Then, `cd` into your project folder. > For Bolt for Python projects, automatic project dependency installation is currently unsupported, and will need to be done manually. > > For more information, refer to [Getting started with Bolt for Python](/tools/bolt-python/getting-started). To run your new app, use the `slack run` command with the experiment flag as follows: ```text slack run ``` You'll be prompted to choose your team/workspace, and then your app should let you know that it's up and running. 🎉 ## App manifest The Slack app manifest is the configuration of the app. The `manifest.json` file included with selected templates and samples reflects the features and permissions of your app. When you create an app with the CLI, the corresponding app and matching manifest can be found on [app settings](https://api.slack.com/apps). For Bolt apps created through the CLI, by default, the manifest source set in the `config.json` file is `remote`. This means that the manifest in your [app settings](https://api.slack.com/apps) is the source of truth. To modify the manifest (add new features, scopes, etc.), do so in the app settings. If you change the `config.json` to reflect a `local` manifest source and modify the local `manifest.json` file, the CLI will ask for confirmation before overriding the settings upstream on reinstall (run). This prompt appears if the app manifest on app settings differs from a known state saved in `.slack/cache`. There is not currently a dedicated manifest update command. In contrast, Deno apps created with the CLI have the manifest source configuration of `local` because those apps are not managed in the [app settings page](https://api.slack.com/apps). [Previous: Authorizing the Slack CLI](/tools/slack-cli/guides/authorizing-the-slack-cli) [Next: Using on Enterprise Grid](/tools/slack-cli/guides/using-slack-cli-on-an-enterprise-grid-organization)