-
-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
66a0dc0
commit e253611
Showing
5 changed files
with
197 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| # Create Slack App | ||
|
|
||
| Create a Slack account and follow the prompts to create a new workspace. The workspace will be used to deploy the Slack App for testing purposes. | ||
|
|
||
| > Use an existing Slack workspace if sufficient administration privelleges are available (and you wont affect other peoples use of Slack) | ||
| [Slack Quickstart](https://api.slack.com/start/quickstart) describes how to create a Slack app. | ||
|
|
||
| [Create a new Slack app with the Slack UI](https://api.slack.com/apps) | ||
|
|
||
| {loading=lazy} | ||
|
|
||
| Select **From Scratch** | ||
|
|
||
| {loading=lazy} | ||
|
|
||
| Enter App Name and select the Development Workspace to experiment and build the app. | ||
|
|
||
| {loading=lazy} | ||
|
|
||
| > Regardless of development workspace, the app can be distributed to any other workspaces. | ||
| The Slack Web UI displays the basic information for the newly created Slack app. | ||
|
|
||
| {loading=lazy} | ||
|
|
||
| <!-- TODO: add App Manifest approach to creating a Slack App --> | ||
|
|
||
|
|
||
| ## Configure scopes | ||
|
|
||
| Add a scope to post messages to a channel | ||
|
|
||
| **Sidebar** > **OAuth & Permissions** > **Scopes** > **Add an OAuth Scope** | ||
|
|
||
| {loading=lazy} | ||
|
|
||
| Add the following Bot Token Scopes | ||
|
|
||
| - `chat:write` scope to the Bot Token to allow the app to post messages | ||
| - `channels:read` scope too so your app can gain knowledge about public Slack channels | ||
|
|
||
| {loading=lazy} | ||
|
|
||
|
|
||
| > Reisntall the app if changing scopes and other features | ||
|
|
||
| ## Update Display information | ||
|
|
||
| > This feels like it should have been done before installing the app | ||
| Provide a short & long description of the app and set background colour. Optionally add an app icon (between 512 and 2000 px in size). | ||
|
|
||
| - **Short description**: A random function from the Clojure Standard Library | ||
| - **Long description**: A random function is selected from the Clojure Standard Library and displayed along with the documentation (doc string) to explain what the function does. A bonus feature will be to provide examples of function use. | ||
|
|
||
|
|
||
| ## Install app in workspace | ||
|
|
||
| Install your app to your Slack workspace to test it and generate the tokens you need to interact with the Slack API. You will be asked to authorize this app after clicking an install option. | ||
|
|
||
| Sidebar > Settings > Basic Information > Install your app | ||
|
|
||
| {loading=lazy} | ||
|
|
||
|
|
||
| ### Authorization token | ||
|
|
||
| The Authorization token for the workspace is in the [app management web page](https://api.slack.com/apps/) for the specific app | ||
|
|
||
| **Sidebar** > **OAuth & Permissions** > **OAuth Tokens for Your Workspace** | ||
|
|
||
| Create an environment variable to hold the authorization token with the value of the **Bot User OAuth Token** | ||
|
|
||
| ```shell | ||
| export SLACK_AUTHENTICATION_TOKEN=xxxx-123412341234-12345123451245-... | ||
| ``` | ||
|
|
||
| > Environment variables used with Clojure must be set before running the REPL, so the variables are available to the Java Virtual Machine process. | ||
| > | ||
| > Add the environment variables to `.bashrc` for Bash or `.zshenv` for Zsh | ||
|
|
||
| Access tokens represent the permissions delegated to the app by the installing user. | ||
|
|
||
| > Avoid checking access tokens into version control | ||
|
|
||
| ## Test app - save for later... | ||
|
|
||
| Add the app to a public channel and test its (as yet unconfigured slash command) | ||
|
|
||
| {loading=lazy} | ||
|
|
||
| Confirm the Slack App should be added to the selected workspace | ||
|
|
||
| {loading=lazy} | ||
|
|
||
|
|
||
|
|
||
| ## Local Development | ||
|
|
||
| Use Socket Mode to route the app interactions and events over a WebSockets connection instead sending payloads to Request URLs, the public HTTP endpoints. | ||
|
|
||
| Socket mode is intended for internal apps that are in development or need to be deployed behind a firewall. It is not intended for widely distributed apps. | ||
|
|
||
| Alternatively, use ngrock to redirect requests to the local app. | ||
|
|
||
|
|
||
| ### Install app into workspace | ||
|
|
||
| Install Slack app into a workspace (not the development workspace) | ||
|
|
||
| **Sidebar** > **Install App** > **Install App To Workspace** > **Slack OAuth UI** | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Clojure powered Slack Application | ||
|
|
||
| Slack applications provide a way to extend the functionality of Slack and provide integration with other services, e.g. GitHub, Atlassian Jira & Confluence, etc. | ||
|
|
||
|
|
||
| ## Development process Overview | ||
|
|
||
| - create a slack account and slack space (to test the application) | ||
| - create a slack app | ||
| - deploy the slack app in the slack test workspace created previously | ||
| - Create a clojure project and interact with the Slack API | ||
| - Setup ngrok domain for Slack app to access a locally running Clojure web service (to respond to interaction with the app - assuming the slack isnt just push driven) | ||
| - alternatively, webservices connection can be configured between the locally running Clojure app and slack (desktop app required? - how does this work...) | ||
|
|
||
| - deploy clojure application to public cloud (AWS, Render.com, etc) | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| # Slack API Methods | ||
|
|
||
| An access token allows the calling of the methods described by the scopes requested during a Slack App installation, | ||
| e.g., the chat:write scope allows an app to post messages. | ||
|
|
||
| The app isn't a member of any channels when installed. Choose a channel suitable for testing purposes and `/invite` the Slack app to the channel. | ||
|
|
||
| You can find the corresponding id for the channel that your app just joined by looking through the results of the conversations.list method: | ||
|
|
||
| ```shell | ||
| curl https://slack.com/api/conversations.list -H "Authorization: Bearer xoxb-1234..." | ||
| ``` | ||
|
|
||
| You'll receive a list of conversation objects. | ||
|
|
||
| Now, post a message to the same channel your app just joined with the chat.postMessage method: | ||
|
|
||
| ```shell | ||
| curl -X POST -F channel=C1234 -F text="Reminder: we've got a softball game tonight!" https://slack.com/api/chat.postMessage -H "Authorization: Bearer xoxb-1234..." | ||
| ``` | ||
|
|
||
| {loading=lazy} | ||
|
|
||
|
|
||
| Voila! We're already well on our way to putting a full-fledged Slack app on the table. | ||
|
|
||
| [Web API Guide](https://api.slack.com/web) | ||
|
|
||
| [API Methods list](https://api.slack.com/methods) | ||
|
|
||
| [Interactive Workflows](https://api.slack.com/interactivity) | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # Slack Scopes Overview | ||
|
|
||
| Scopes give the app permission to carry out actions, e.g. post messages, in the development workspace. | ||
|
|
||
| Open the development workspace, either in a web page or in the Slack desktop app. | ||
|
|
||
| **Sidebar** > **OAuth & Permissions** > **Scopes** > **Add an OAuth Scope** | ||
|
|
||
| - `chat:write` scope to the Bot Token to allow the app to post messages | ||
| - `channels:read` scope too so your app can gain knowledge about public Slack channels | ||
| - `commands` scope to build a Slash command. | ||
| - `incoming-webhook` scope to use Incoming Webhooks. | ||
| - `chat:write.public` scope to gain the ability to post in all public channels, without joining. Otherwise, you'll need to use conversations.join, or have your app invited by a user into a channel, before you can post. | ||
| - `chat:write.customize` scope to adjust the app's message authorship to make use of the username, icon_url, and icon_emoji parameters in `chat.postMessage`. | ||
|
|
||
|
|
||
| > Add scopes to the Bot Token. | ||
| > | ||
| > Only add scopes to the User Token when the app needs to act as a specific user (e.g. post message as user, set user status, etc.) | ||
|
|
||
| If the scopes applied to a Slack App are changed, the Slack App must be redeployed to the workspace (and Slack App Directory) for the changes to take effect. | ||
|
|
||
| {loading=lazy} | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters