{"id":26289998,"url":"https://github.com/slack-samples/bolt-js-slack-connect","last_synced_at":"2025-05-07T22:44:12.088Z","repository":{"id":38031368,"uuid":"462501209","full_name":"slack-samples/bolt-js-slack-connect","owner":"slack-samples","description":"This project aims to speed up the time to understand \u0026 implement automations with Slack Connect APIs. This project aims to be the baseline on which a few different automations can be built.","archived":false,"fork":false,"pushed_at":"2024-03-02T01:46:28.000Z","size":39,"stargazers_count":9,"open_issues_count":1,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T22:44:06.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://api.slack.com/apis/connect","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slack-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-02-22T22:49:58.000Z","updated_at":"2025-04-07T00:16:09.000Z","dependencies_parsed_at":"2024-03-02T02:43:36.765Z","dependency_job_id":"51aa268d-2649-45d8-aa29-59e07fd94130","html_url":"https://github.com/slack-samples/bolt-js-slack-connect","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slack-samples%2Fbolt-js-slack-connect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slack-samples%2Fbolt-js-slack-connect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slack-samples%2Fbolt-js-slack-connect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slack-samples%2Fbolt-js-slack-connect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slack-samples","download_url":"https://codeload.github.com/slack-samples/bolt-js-slack-connect/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252967974,"owners_count":21833245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-14T23:17:36.273Z","updated_at":"2025-05-07T22:44:12.064Z","avatar_url":"https://github.com/slack-samples.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Bolt JS Slack Connect Admin 🤖\n\u003cp align=\"center\"\u003e\n\n[![Add App to Channel](https://user-images.githubusercontent.com/10428517/155399298-a7784e0a-3b13-42b3-a3e4-96217efbd0d9.gif)](https://user-images.githubusercontent.com/10428517/155399298-a7784e0a-3b13-42b3-a3e4-96217efbd0d9.gif)\n\u003c/p\u003e\n\n\u003e **Note:🚨** Because this app can approve Slack Connect invites, apps with this feature can only be installed by a workspace owner or admin. Read more about the `conversations.connect:manage` scope [here](https://slack.com/create). 🚨 \n\nThis project aims to speed up the time to understand \u0026 implement automations with [Slack Connect APIs](https://api.slack.com/apis/connect). This project aims to be the baseline\non which a few different automations can be built, such as:\n\n* Disconnect channels automatically (based on a date picked at channel creation time)\n* Customize org settings for auto approval to speed up creating multiple \nchannels between the same two organizations \n\n# Steps \n1. [App Configuration](#step-1-app-configuration)\n2. [Install the App](#step-2-install-the-app)\n3. [Add the App to a Channel](#step-3-add-the-app-to-a-channel)\n4. [Send a Slack Connect Invite](#step-4-send-a-slack-connect-invite)\n5. [(Optional) Send a Slack Connect Invite using User ID](#step-5-optional-send-a-slack-connect-invite-using-user-id)\n6. [(Optional) Create Custom Slack Connect Settings to Never Require Approval](#step-6-optional-create-custom-slack-connect-settings-to-never-require-approval)\n7. [Accept the Slack Connect Invite](#step-7-accept-the-slack-connect-invite)\n8. [Approve the Slack Connect Invite](#step-8-approve-the-slack-connect-invite)\n9. [Disconnect the Channel](#step-9-disconnect-the-channel) \n10. [Conclusion](#conclusion) \n\n## App Configuration\n\nBefore getting started, make sure you have a development workspace where you have permissions to install apps. If you don’t have one setup, go ahead and [create one](https://slack.com/create).\n## Installation\n\n#### Create a Slack App\n\n1. Open [https://api.slack.com/apps/new](https://api.slack.com/apps/new) and choose \"From an app manifest\"\n2. Choose the workspace you want to install the application to\n3. Copy the contents of [manifest.json](./manifest.json) into the text box that says `*Paste your manifest code here*` (within the JSON tab) and click _Next_. Make sure to change the URLs on the `manifest.json` in three\nspecific places, as shown in the screenshot below.\n\n![changeManifest](https://user-images.githubusercontent.com/10428517/155407272-44a2eaf9-e735-453f-a9c7-18c21004a037.png)\n\n4. Review the configuration and click _Create_\n5. Click _Install to Workspace_ and _Allow_ on the screen that follows. You'll then be redirected to the App Configuration dashboard.\n6. Click on `Manage Distribution` and then make sure all boxes have \ngreen check marks. Select `Remove Hard Coded Information`, check the box\nand then `Activate Public Distribution`.\n\n![activeDistribution](https://user-images.githubusercontent.com/10428517/155411289-45f63a4f-72dc-40b1-a45e-9fae8d2df673.png)\n\n#### Environment Variables\n\nBefore you can run the app, you'll need to store some environment variables.\n\n1. Copy `.env.sample` to `.env`\n2. Click _Basic Information_ from the left hand menu. There, in the `App Credentials` you should see your `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and `SLACK_SIGNING_SECRET`. Click on `Show` and copy and paste those values into your `.env` file.\n3. This app uses (the free version of) MongoDB. You'll need to provide your MongoDB username, password, and database name in the `.env` file: `DB_USERNAME`, `DB_PASSWORD`, and `DB_NAME`. You can \nfeel free to leave the DB_NAME as `slack_connect_test`.\n4. Lastly, you'll need to set the `CLUSTER` env variable. To do this, you'll need your connection info to be able to connect to your MongoDB cluster. Please follow the below screenshots to see your cluster information to be able to set the `CLUSTER` env variable.\n\nFirst, click on `Database` from the left side bar, under `Deployments`.\n![dbDeployments](https://user-images.githubusercontent.com/10428517/175144163-a503528a-290a-4030-8359-c0e401865475.png)\n\nNext, click on `Connect` next to `Cluster0`. Note that your cluster may be named differently. You should see the following after you click on `Connect`.\n![connect](https://user-images.githubusercontent.com/10428517/175144181-37a9e8a5-eff3-4844-8ca3-b3d0fd9068e9.png)\n\nLastly, click on `connect your application`.\n![connect](https://user-images.githubusercontent.com/10428517/175156902-6bd48d2f-a44e-4dc0-b76b-8f70c886bff5.png)\n\nThere you should see your cluster info. Mine is `cluster0.yvswg`. Yours should look different. Copy your connection string as and paste it in your \n`.env` file. See my example of my cluster info in `env.sample` [here](https://github.com/slack-samples/bolt-js-slack-connect/blob/main/env.sample#L9).\n\nBelow, you can see a screenshot of my database configuration. The `DB_NAME` is `slack_connect_test` \nand the collection is named `users`. \n\n![Screen Shot 2022-02-22 at 11 05 10 AM](https://user-images.githubusercontent.com/10428517/155201340-b6b77e0d-e49b-41c9-a26f-f24c1eb419a2.png)\n\n#### Source your Env Variables\nThat's it! You now have all the info to set your environmental variables to connect to your MongoDB cluster. \n\n\u003e Don't forget to save your `.env` and then run \n```source .env``` to set your env variables. \n\n#### Install Dependencies\n\n`npm install`\n\n#### Run Bolt Server\n\n`npm start`\n\n## Project Structure\n\n### `manifest.json`\n\n`manifest.json` is a configuration for Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.\n\n### `app.js`\n\n`app.js` is the entry point for the application and is the file you'll run to start the server. This project aims to keep this file as thin as possible, primarily using it as a way to route inbound requests.\n\n### `/listeners`\n\nEvery incoming request is routed to a \"listener\". Inside this directory, we group each listener based on the Slack Platform feature used, so `/listeners/shortcuts` handles incoming [Shortcuts](https://api.slack.com/interactivity/shortcuts) requests, `/listeners/views` handles [View submissions](https://api.slack.com/reference/interaction-payloads/views#view_submission) and so on.\n\nGreat job! You're now ready to install the app using Slack's OAuth process. \n\n## Step 1. Configure Interactivity, Events, and Redirect URLs\n\nFollow the steps below based on if you plan to use Ngrok or Glitch as a way to host your app. Either will work.\n\nIf you are using [Ngrok](www.ngrok.com), make sure you have started up ngrok, and have updated your app with the ngrok forwarding address in the following places:\n1. Update your event subscriptions request URL. It should look like the following: `https://3cb89939.ngrok.io/slack/events`. Save this.\n2. Update your interactivity request URL. It should look like the following: `https://3cb89939.ngrok.io/slack/events`. Save this.\n3. Go to OAuth \u0026 Permissions -\u003e Redirect URLs. Add a new redirect URL. It should look like the following: `https://3cb89939.ngrok.io/slack/oauth_redirect`. Save the URL.\n\n## App Distribution / OAuth\n\nThis app uses app distribution / OAuth by default. When using OAuth, Slack requires a public URL where it can send requests. In this template app, we've used [`ngrok`](https://ngrok.com/download). Checkout [this guide](https://ngrok.com/docs#getting-started-expose) for setting it up.\n\nStart `ngrok` to access the app on an external network and create a redirect URL for OAuth. \n\n## Step 2. Install the App\n\n\u003e **Note:🚨** Because this app can approve Slack Connect invites, apps with this feature can only be installed by a worksapce owner or admin. Read more about the `conversations.connect:manage` scope [here](https://slack.com/create). 🚨 \n\nWatch the video below **(sound on)** to understand how to install the app. Note that the video is showing the install path from a Ngrok URL. \nThe base URL will always we different, based on if you are using Ngrok or Glitch, and depending on what your app is named on Glitch / what forwarding address is used in Ngrok.\n\n[![Install App via OAuth](https://user-images.githubusercontent.com/10428517/154159350-3e5ab314-d9f9-4c38-8d8a-122751d1cc51.png)](https://user-images.githubusercontent.com/10428517/155203611-ffa7b69a-9b6d-40d1-a33e-9ba622c0dfcf.mov)\n\n\nNext, navigate to your install endpoint. Since we are using Bolt, this endpoint is automatically created for us from the Bolt package. \n1. If you are using Glitch (and assuming your app is hosted at `https://bolt-template-slack-connect.glitch.me`), you can navigate to `https://bolt-template-slack-connect.glitch.me/slack/install`\nIf you are using Ngrok, it should look something like `https://3cb89939.ngrok.io/slack/install`\n2. Click on the `Add to Slack` button.\n3. Pick a workspace to install the app to from the top-right corner.\n4. Click on the green `Allow` button.\n5. You will be redirected to the Redirect URL. Click on \"Open Slack\". \n6. Once you click on \"Open Slack\" your browser, you will be taken to the messages tab of your new Slack Connect Admin app! 🎉\n\n\n## Step 3. Add the App to a Channel\n\nWatch the video below **(sound on)** to understand how to add the app to a channel. First, we \ncreate a new channel, then we add the app to that channel.\n\n[![Add App to Channel](https://user-images.githubusercontent.com/10428517/155204764-789193f2-8cce-46aa-8268-508cf38195b9.png)](https://user-images.githubusercontent.com/10428517/155204315-2fa1b888-d479-494d-ae80-ebe59da02868.mov)\n\n## Step 4. Send a Slack Connect Invite\n\nWatch the video below **(sound on)** to understand how to send an invite to a user outside of your current organization.\n\n[![sendInvite](https://user-images.githubusercontent.com/10428517/155223135-f9f6a0fd-4e93-4494-bb73-feddbbb09170.png)](https://user-images.githubusercontent.com/10428517/155223009-e03aa7c6-ba0c-46e6-9803-db90906e0138.mov)\n\nFirst, click on the `Send Invites` button.\n\nThen, in the modal which pops up, choose the channel which you've just added the Slack Connect Admin App to.\n\nIn the email section, choose the email which coressponds to the workspace which you want to start a shared channel with.\n\nLeave the rest of the sections blank and click on `Invite`. Lastly, click on `View Invitations` and you should see your \nnewly created inviation.\n\n## Step 5. (Optional) Send a Slack Connect Invite using User ID\n[![sendInvite](https://user-images.githubusercontent.com/10428517/155223135-f9f6a0fd-4e93-4494-bb73-feddbbb09170.png)](https://user-images.githubusercontent.com/10428517/170152797-c8a784b9-22f7-45ea-8140-1c1c54df30d4.mov)\n\n\u003e **Note:🚨** A tip about sending invites using the `user_id` field. If your app is already installed on both the inviting \u003cb\u003eand\u003c/b\u003e the target organization, you can invite the app via User ID directly. This will\nresult in the automatic accepting of the invite.\nSimply grab the `user_id` field. This is recommended for orgs that you have a close working relationship with. Read more [here](https://api.slack.com/apis/connect#invite). 🚨 \n\nFirst, click on the Send Invites button.\n\nThen, in the modal which pops up, choose the channel which you've just added the Slack Connect Admin App to.\n\nIn the `user_id` section, choose the `user_id` which coressponds to the bot\nwhich has been installed on the target Organization (i.e. Organization which\nwill receive the invite). \n\n\u003e **Note:🚨** To find the `user_id` of the app, simply click on the app's \nhome (make sure it is the app which is installed on the target Organization), and then click on the App's name. From there, you should see the `Member ID` which starts with a `U`. That is the `user_id` which you can use in the invite. 🚨 \n\nLeave the rest of the sections blank and click on Invite. Lastly, click on View Invitations and you should see your newly created inviation.\n\n## Step 6. (Optional) Create Custom Slack Connect Settings to Never Require Approval\n\n[![sendInvite](https://user-images.githubusercontent.com/10428517/155223135-f9f6a0fd-4e93-4494-bb73-feddbbb09170.png)](https://user-images.githubusercontent.com/10428517/170152824-80389b26-54da-48c4-9547-bb7215369bc1.mov)\n\n\nNow - if you've also created special rules in the Admin console of your \nGrid Organization, you can have it so that any accepted invite will be \nauto-approved from a specific organization. This is the way to make Slack\nConnect channels seamlessly be approved between trusted Organizations.\n\n## Step 7. Accept the Slack Connect Invite\nWatch the video below **(sound on)** to understand how to accept the invite.\n\n\u003e **Note:🚨** The invite must be accepted from a user from a different workspace / organization than the workspace / org from which the invite was sent. 🚨 \n\n[![acceptInvite](https://user-images.githubusercontent.com/10428517/155223135-f9f6a0fd-4e93-4494-bb73-feddbbb09170.png)](https://user-images.githubusercontent.com/10428517/155225771-184cca6d-f715-45ca-9ba6-452c3a86216b.mov)\n\nClick on the Invite ID at the top of the invitation to be taken to the invite. Select the email account \nassociated with the workspace you want to accept the invite from. For me that is the account with `horeaporutiu1@gmail.com`.\nClick through the following two pages. You can leave the defaults as is (Public channel, same channel name). Lastly,\nclick on `Join Channel`. Now, if you click on `View Invitations again` you should see that the buttons have changed. Instead of seeing `Accept` and `Ignore`you will\nnow see `Approve` and `Deny`. \n\n## Step 8. Approve the Slack Connect Invite\nWatch the video below **(sound on)** to understand how to approve the invite.\n\n[![approveInvite](https://user-images.githubusercontent.com/10428517/155223135-f9f6a0fd-4e93-4494-bb73-feddbbb09170.png)](https://user-images.githubusercontent.com/10428517/155228571-f4a10314-f5bb-4af2-803e-3bcfd41145a9.mov)\n\nClick on the green `Approve` button next to the invite. After a few seconds, you should see that invite dissapear and then the `demo_sc_app` channel will be added under the `Connections` tab, which means it's been shared outside of your own organization! \n\n## Step 9. Disconnect the Channel\n\nWatch the video below **(sound on)** to understand how to disconnect your shared channel. This will involve installing the app again, but this \ntime at the org level. 🚨You need to be **logged in as an org owner / admin** to be able to use this feature.🚨\n\n[![disconnect](https://user-images.githubusercontent.com/10428517/155223135-f9f6a0fd-4e93-4494-bb73-feddbbb09170.png)](https://user-images.githubusercontent.com/10428517/155230983-046ff198-6017-410a-97d1-5ba311496b77.mp4)\n\nTo disconnect a channel, we will need a special, [admin scope](https://api.slack.com/scopes/admin.conversations:write). The main difference between\nthis scope and the other scopes we've requested in the past is that this endpoint reaches across \nan entire Enterprise Grid organization, not individual workspaces. This means it has a lot more \npower than the traditional scopes. \n\nOnce you are ready to install, navigate to the following endpoint: `www.example.com/slack/install/orgadmin`. Since I am using ngrok currently, my endpoint is: https://3015-98-51-61-120.ngrok.io/slack/install/orgadmin. Your base path will look different than mine.\n\nOnce you navigate to that endpoint, you should see a purple Add to Slack button. Once you click on that, you should be able to install the app **at the org level**. This means that it is normal to \nsee organizations in the drop down, in addition to workspaces. This install will ONLY work on a valid \norganization which you are a Owner or admin of. Watch the video below to see the process in action.\n\nAfter you've sucessfully installed the app at the org level, click on the \n`Disconnect Channels` button. Select the channel `demo_sc_app` and then \nclick on `Disconnect`. \nWithin a few seconds, you should see that channel move from the `Connections` section of the sidebar, to the `Channels` section. This means \nthat this channel has now been disconnected from the organization it was previously connected to.\n\n## 🎊 Conclusion 🎊 \n\nGreat job! You've learned how the Slack Connect APIs work! You've learned how to send an invite, accept and invite, approve an invite, and \nalso disconnect a shared channel!\n\nAnother thing you may want to try is to edit settings for your organization's Slack Connect use case. If you want to auto approve all \nchannels between a certain organization you may do that. This will speed up the creation of Slack Connect channels. \n\nThanks so much for learning with me. Please file any issues in this GitHub repo! \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslack-samples%2Fbolt-js-slack-connect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslack-samples%2Fbolt-js-slack-connect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslack-samples%2Fbolt-js-slack-connect/lists"}