|
| 1 | + |
1 | 2 | # Modals |
2 | 3 |
|
3 | | -If you're learning about Slack apps, modals, or slash commands for the first time, you've come to the right place! In this tutorial, we'll take a look at setting up your very own server using Glitch, and using that server to run your Slack app. |
| 4 | +If you're learning about Slack apps, modals, or slash commands for the first time, you've come to the right place! In this tutorial, we'll take a look at setting up your very own server using GitHub Codespaces, then using that server to run your Slack app built with the [**Bolt for Python framework**](https://github.com/SlackAPI/bolt-python). |
4 | 5 |
|
5 | | -Let's take a look at the technologies we'll use in this tutorial: |
| 6 | +:::info[GitHub Codespaces] |
| 7 | +GitHub Codespaces is an online IDE that allows you to work on code and host your own server at the same time. While Codespaces is good for testing and development purposes, it should not be used in production. |
6 | 8 |
|
7 | | -* Glitch is a online IDE that allows you to collaboratively work on code and host your own server. Glitch should only be used for development purposes and should not be used in production. |
8 | | -* We'll use Python in conjunction with our [Bolt for Python](https://github.com/SlackAPI/bolt-python) SDK. |
9 | | -* [Block Kit](https://docs.slack.dev/block-kit/) is a UI framework for Slack apps that allows you to create beautiful, interactive messages within Slack. If you've ever seen a message in Slack with buttons or a select menu, that's Block Kit. |
10 | | -* Modals are similar to a pop-up window that displays right in Slack. They grab the attention of the user, and are normally used to prompt users to provide some kind of information or input. |
| 9 | +::: |
11 | 10 |
|
12 | | ---- |
| 11 | +At the end of this tutorial, your final app will look like this: |
13 | 12 |
|
14 | | -## Final product overview {#final_product} |
15 | | -If you follow through with the extra credit tasks, your final app will look like this: |
| 13 | + |
16 | 14 |
|
17 | | - |
| 15 | +And will make use of these Slack concepts: |
| 16 | +* [**Block Kit**](https://docs.slack.dev/block-kit/) is a UI framework for Slack apps that allows you to create beautiful, interactive messages within Slack. If you've ever seen a message in Slack with buttons or a select menu, that's Block Kit. |
| 17 | +* [**Modals**](https://docs.slack.dev/surfaces/modals) are a pop-up window that displays right in Slack. They grab the attention of the user, and are normally used to prompt users to provide some kind of information or input in a form. |
| 18 | +* [**Slash Commands**](https://docs.slack.dev/interactivity/implementing-slash-commands) allow you to invoke your app within Slack by just typing into the message composer box. e.g. `/remind`, `/topic`. |
18 | 19 |
|
19 | | ---- |
| 20 | +If you're familiar with using Heroku you can also deploy directly to Heroku with the following button. |
20 | 21 |
|
21 | | -## The process {#steps} |
| 22 | +[](https://www.heroku.com/deploy?template=https://github.com/wongjas/modal-example) |
22 | 23 |
|
23 | | -1. [Create a new app](https://api.slack.com/apps/new) and name it whatever you like. |
| 24 | +--- |
| 25 | + |
| 26 | +## Setting up your app within App Settings {#setting-up-app-settings} |
24 | 27 |
|
25 | | -2. [Remix (or clone)](https://glitch.com/edit/#!/remix/intro-to-modals-bolt) the Glitch template. |
| 28 | +You'll need to create an app and configure it properly within App Settings before using it. |
26 | 29 |
|
27 | | -Here's a copy of what the modal payload looks like — this is what powers the modal. |
| 30 | +1. [Create a new app](https://api.slack.com/apps/new), click `From a Manifest`, and choose the workspace that you want to develop on. Then copy the following JSON object; it describes the metadata about your app, like its name, its bot display name and permissions it will request. |
28 | 31 |
|
29 | 32 | ```json |
30 | 33 | { |
31 | | - "type": "modal", |
32 | | - "callback_id": "gratitude-modal", |
33 | | - "title": { |
34 | | - "type": "plain_text", |
35 | | - "text": "Gratitude Box", |
36 | | - "emoji": true |
37 | | - }, |
38 | | - "submit": { |
39 | | - "type": "plain_text", |
40 | | - "text": "Submit", |
41 | | - "emoji": true |
42 | | - }, |
43 | | - "close": { |
44 | | - "type": "plain_text", |
45 | | - "text": "Cancel", |
46 | | - "emoji": true |
47 | | - }, |
48 | | - "blocks": [ |
49 | | - { |
50 | | - "type": "input", |
51 | | - "block_id": "my_block", |
52 | | - "element": { |
53 | | - "type": "plain_text_input", |
54 | | - "action_id": "my_action" |
55 | | - }, |
56 | | - "label": { |
57 | | - "type": "plain_text", |
58 | | - "text": "Say something nice!", |
59 | | - "emoji": true |
60 | | - } |
| 34 | + "display_information": { |
| 35 | + "name": "Intro to Modals" |
| 36 | + }, |
| 37 | + "features": { |
| 38 | + "bot_user": { |
| 39 | + "display_name": "Intro to Modals", |
| 40 | + "always_online": false |
| 41 | + }, |
| 42 | + "slash_commands": [ |
| 43 | + { |
| 44 | + "command": "/announce", |
| 45 | + "description": "Makes an announcement", |
| 46 | + "should_escape": false |
| 47 | + } |
| 48 | + ] |
| 49 | + }, |
| 50 | + "oauth_config": { |
| 51 | + "scopes": { |
| 52 | + "bot": [ |
| 53 | + "chat:write", |
| 54 | + "commands" |
| 55 | + ] |
| 56 | + } |
| 57 | + }, |
| 58 | + "settings": { |
| 59 | + "interactivity": { |
| 60 | + "is_enabled": true |
| 61 | + }, |
| 62 | + "org_deploy_enabled": false, |
| 63 | + "socket_mode_enabled": true, |
| 64 | + "token_rotation_enabled": false |
61 | 65 | } |
62 | | - ] |
63 | 66 | } |
64 | 67 | ``` |
65 | 68 |
|
66 | | -3. Find the base path to your server by clicking **Share**, then copy the Live site link. |
| 69 | +2. Once your app has been created, scroll down to `App-Level Tokens` and create a token that requests for the [`connections:write`](https://docs.slack.dev/reference/scopes/connections.write) scope, which allows you to use [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode), a secure way to develop on Slack through the use of WebSockets. Copy the value of your app token and keep it for safe-keeping. |
| 70 | + |
| 71 | +3. Install your app by heading to `Install App` in the left sidebar. Hit `Allow`, which means you're agreeing to install your app with the permissions that it is requesting. Be sure to copy the token that you receive, and keep it somewhere secret and safe. |
67 | 72 |
|
68 | | -  |
| 73 | +## Starting your Codespaces server {#starting-server} |
69 | 74 |
|
70 | | -4. On your app page, navigate to **Interactivity & Shortcuts**. Append "/slack/events" to your base path URL and enter it into the **Request URL** e.g., `https://festive-harmonious-march.glitch.me/slack/events`. This allows your server to retrieve information from the modal. You can see the code for this within the Glitch project. |
| 75 | +1. Log into GitHub and head to this [repository](https://github.com/wongjas/modal-example). |
71 | 76 |
|
72 | | -  |
| 77 | +2. Click the green `Code` button and hit the `Codespaces` tab and then `Create codespace on main`. This will bring up a code editor within your browser so you can start coding. |
73 | 78 |
|
74 | | -5. Create the slash command so you can access it within Slack. Navigate to the **Slash Commands** section and create a new command. Note the **Request URL** is the same link as above, e.g. `https://festive-harmonious-march.glitch.me/slack/events` . The code that powers the slash command and opens a modal can be found within the Glitch project. |
| 79 | +## Understanding the project files {#understanding-files} |
75 | 80 |
|
76 | | -  |
| 81 | +Within the project you'll find a `manifest.json` file. This is a a configuration file used by Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app. |
77 | 82 |
|
78 | | -6. Select **Install App**. After you've done this, you'll see a **Bot User OAuth Access Token**, copy this. |
| 83 | +The `simple_modal_example.py` Python script contains the code that powers your app. If you're going to tinker with the app itself, take a look at the comments found within the `simple_modal_example.py` file! |
79 | 84 |
|
80 | | -7. Navigate to your Glitch project and click the `.env` file where the credentials are stored, and paste your bot token where the `SLACK_BOT_TOKEN` variable is shown. This allows your server to send authenticated requests to the Slack API. You'll also need to head to your app's settings page under **Basic Information** and copy the _Signing secret_ to place into the `SLACK_SIGNING_SECRET` variable. |
| 85 | +The `requirements.txt` file contains the Python package dependencies needed to run this app. |
81 | 86 |
|
82 | | -  |
| 87 | +:::info[This repo contains optional Heroku-specific configurations] |
83 | 88 |
|
84 | | -8. Test by heading to Slack and typing `/thankyou`. |
| 89 | +The `app.json` file defines your Heroku app configuration including environment variables and deployment settings, to allow your app to deploy with one click. `Procfile` is a Heroku-specific file that tells Heroku what command to run when starting your app — in this case a Python script would run as a `worker` process. If you aren't deploying to Heroku, you can ignore both these files. |
85 | 90 |
|
86 | | -All done! 🎉 You've created your first slash command using Block Kit and modals! The world is your oyster; you can create more complex modals by playing around with [Block Kit Builder](https://app.slack.com/block-kit-builder). |
| 91 | +::: |
| 92 | + |
| 93 | +## Adding tokens {#adding-tokens} |
| 94 | + |
| 95 | +1. Open a terminal up within the browser's editor. |
| 96 | + |
| 97 | +2. Grab the app and bot tokens that you kept safe. We're going to set them as environment variables. |
| 98 | + |
| 99 | +```bash |
| 100 | +export SLACK_APP_TOKEN=<YOUR-APP-TOKEN-HERE> |
| 101 | +export SLACK_BOT_TOKEN=<YOUR-BOT-TOKEN-HERE> |
| 102 | +``` |
87 | 103 |
|
88 | | -### Extra credit {#extra_credit} |
| 104 | +## Running the app {#running-app} |
| 105 | + |
| 106 | +1. Activate a virtual environment for your Python packages to be installed. |
| 107 | + |
| 108 | +```bash |
| 109 | +# Setup your python virtual environment |
| 110 | +python3 -m venv .venv |
| 111 | +source .venv/bin/activate |
| 112 | +``` |
| 113 | + |
| 114 | +2. Install the dependencies from the `requirements.txt` file. |
| 115 | + |
| 116 | + |
| 117 | +```bash |
| 118 | +# Install the dependencies |
| 119 | +pip install -r requirements.txt |
| 120 | +``` |
| 121 | + |
| 122 | +3. Start your app using the `python3 simple_modal_example.py` command. |
| 123 | + |
| 124 | +```bash |
| 125 | +# Start your local server |
| 126 | +python3 simple_modal_example.py |
| 127 | +``` |
89 | 128 |
|
90 | | -For a little extra credit, let's post the feedback we received in a channel. |
| 129 | +4. Now that your app is running, you should be able to see it within Slack. Test this by heading to Slack and typing `/announce`. |
91 | 130 |
|
92 | | -1. Add the `chat:write` bot scope, which allows your bot to post messages within Slack. You can do this in the **OAuth & Permissions** section for your Slack app. |
93 | | -2. Reinstall your app to apply the scope. |
94 | | -3. Create a channel and name it `#thanks`. Get its ID by right clicking the channel name, copying the link, and copying the last part starting with the letter `C`. For example, if your channel link looks like this: https://my.slack.com/archives/C123FCN2MLM, the ID is `C123FCN2MLM`. |
95 | | -4. Add your bot to the channel by typing the command `/invite @your_bots_name`. |
96 | | -5. Uncomment the `Extra Credit` code within your Glitch project and make sure to replace `your_channel_id` with the ID above. |
97 | | -6. Test it out by typing `/thankyou`, and watching all the feedback come into your channel! |
| 131 | +All done! 🎉 You've created your first slash command using Block Kit and modals! The world is your oyster; play around with [Block Kit Builder](https://app.slack.com/block-kit-builder) and create more complex modals and place them in your code to see what happens! |
98 | 132 |
|
99 | 133 | ## Next steps {#next-steps} |
100 | 134 |
|
101 | | -If you want to learn more about Bolt for Python, refer to the [Getting Started guide](/bolt-python/getting-started). |
| 135 | +If you want to learn more about Bolt for Python, refer to the [Getting Started guide](https://tools.slack.dev/bolt-python/getting-started). |
0 commit comments