{"id":20695819,"url":"https://github.com/ibm-cloud/openwhisk-slackapp","last_synced_at":"2025-04-22T20:27:11.457Z","repository":{"id":136481827,"uuid":"65383460","full_name":"IBM-Cloud/openwhisk-slackapp","owner":"IBM-Cloud","description":"A serverless Slack app built with Slack Events API and IBM Cloud Functions","archived":false,"fork":false,"pushed_at":"2021-04-21T13:21:02.000Z","size":3863,"stargazers_count":27,"open_issues_count":0,"forks_count":28,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-29T18:36:30.584Z","etag":null,"topics":["bot","ibm-bluemix","ibm-cloud","ibm-cloud-solutions","openwhisk-actions","slack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM-Cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","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,"publiccode":null,"codemeta":null}},"created_at":"2016-08-10T13:09:40.000Z","updated_at":"2024-09-28T08:16:42.000Z","dependencies_parsed_at":"2023-05-06T10:31:03.967Z","dependency_job_id":null,"html_url":"https://github.com/IBM-Cloud/openwhisk-slackapp","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fopenwhisk-slackapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fopenwhisk-slackapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fopenwhisk-slackapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM-Cloud%2Fopenwhisk-slackapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM-Cloud","download_url":"https://codeload.github.com/IBM-Cloud/openwhisk-slackapp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250317825,"owners_count":21410823,"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":["bot","ibm-bluemix","ibm-cloud","ibm-cloud-solutions","openwhisk-actions","slack"],"created_at":"2024-11-17T00:11:09.085Z","updated_at":"2025-04-22T20:27:11.447Z","avatar_url":"https://github.com/IBM-Cloud.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A serverless Slack app built with IBM Cloud Functions and Slack Events API\n\nThis sample shows how to build a serverless Slack app using Slack Events API to receive events,\nwith IBM Cloud Functions to process these events.\n\n\u003cimg src=\"xdocs/app-created.png\" width=\"200\"/\u003e\u003cimg src=\"xdocs/team-botchat.png\" width=\"200\"/\u003e\u003cimg src=\"xdocs/team-customcommandoutput.png\" width=\"200\"/\u003e\n\n\u003e A previous version of this sample was using API Connect to expose the actions as HTTP endpoints. With the introduction of web actions in Cloud Functions this was no longer needed. You can browse [this tag](https://github.com/IBM-Cloud/openwhisk-slackapp/tree/using-api-connect) to view the code using API Connect.\n\n## Overview\n\nBuilt using IBM Cloud, the app uses:\n* Cloud Functions - to implement the app bot and commands\n* Cloudant - to keep track of app installations\n* and Slack Events API.\n\nWhen a user installs the app in a Slack team, or interacts with a bot user, or uses a custom command, Slack calls the app implementation. Slack will talk directly with IBM Cloud Functions.\n\nFrom the perspective of the developer of the Slack app, there is no server involved, only actions in a serverless environment. Furthermore the code is not running if no user interacts with the app and if the app gets popular, it will benefit from IBM Cloud Functions scalability.\n\n![Architecture](https://g.gravizo.com/source/architecture_diagram?https%3A%2F%2Fraw.githubusercontent.com%2FIBM-Cloud%2Fopenwhisk-slackapp%2Fmaster%2FREADME.md)\n\u003cdetails\u003e\n\u003csummary\u003e\u003c/summary\u003e\narchitecture_diagram\n  digraph G {\n    node [fontname = \"helvetica\"]\n    rankdir=LR\n    user -\u003e slack\n    slack -\u003e openwhisk\n    openwhisk -\u003e cloudant\n    slack [shape=square style=filled color=\"%23e9a820\" fontcolor=white label=\"%23 Slack\"]\n    openwhisk [shape=circle style=filled color=\"%23325c80\" fontcolor=white label=\"Cloud Functions\"]\n    cloudant [shape=circle style=filled color=\"%2372c7e7\" fontcolor=white label=\"Cloudant\"]\n  }\narchitecture_diagram\n)\n\u003c/details\u003e\n\nIn this sample, we will:\n* create the Slack app in Slack,\n* prepare the Cloud Functions environment, creating the actions implementing our Slack app,\n* complete the integration by updating the endpoints in the Slack app,\n* add our Slack app to a Slack team,\n* test our Slack app.\n\n## Requirements\n\nTo deploy this app, you need:\n* IBM Cloud account. [Sign up](https://cloud.ibm.com/?cm_mmc=GitHubReadMe) for IBM Cloud, or use an existing account.\n* Slack account\n* The [IBM Cloud CLI](https://cloud.ibm.com/docs/cli/index.html) and the [Cloud Functions plugin](https://cloud.ibm.com/docs/cli?topic=cloud-functions-cli-plugin-functions-cli)\n\nYour own Slack team is recommended if you want to play with the integration without impacting others.\n\n## Create the Slack app\n\n1. Proceed to the [new app creation](https://api.slack.com/apps/new) in Slack\n\n1. Type a name for your app, select your Slack team.\n\n1. Click Create\n\n   ![](xdocs/app-created.png)\n\n1. View the App Credentials\n\n   ![](xdocs/app-verificationtoken.png)\n\nWe will need the Client ID, Client Secret and Verification Token in the next steps.\n\nAt this stage, we will put the configuration of the Slack app on hold.\nFor the next app configuration steps to work we need to have our actions up and running.\n\n## Deploy the IBM Cloud Functions\n\n### Get the code\n\n* Clone the app to your local environment from your terminal using the following command:\n\n   ```\n   git clone https://github.com/IBM-Cloud/openwhisk-slackapp.git\n   ```\n\n* or Download and extract the source code from [this archive](https://github.com/IBM-Cloud/openwhisk-slackapp/archive/master.zip)\n\n### Create the IBM Cloud Cloudant service\n\n1. Open the IBM Cloud console\n\n1. Create a Cloudant instance named **cloudant-for-slackapp**.\n\n1. Open the Cloudant service dashboard and create a new database named **registrations**\n\n1. Select the database\n\n1. Create a new document.\n\n1. Replace the default JSON with the content of the file [cloudant-designs.json](cloudant-designs.json)\n\n   ![](xdocs/cloudant-adddesigndoc.png)\n\n### Deploy from Linux or macOS\n\n1. Copy the file named **template.local.env** into **local.env**\n\n   ```\n   cp template.local.env local.env\n   ```\n\n1. Get the service credentials for the Cloudant service created above and set CLOUDANT_url, CLOUDANT_apikey in `local.env` to the corresponding value (url and apikey).\n\n1. Set the values for SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_VERIFICATION_TOKEN - these are the App Credentials we've seen in the previous steps.\n\n1. Ensure your `ibmcloud fn` command line interface is property configured with:\n\n   ```\n   ibmcloud fn list\n   ```\n\n   This shows the packages, actions, triggers and rules currently deployed in your namespace.\n\n1. Create the actions:\n\n   ```\n   ./deploy.sh --install\n   ```\n\n   If all goes well it outputs:\n\n   ```\n   Creating slackapp package\n   ok: created package slackapp\n   Adding app registration command\n   ok: created action slackapp/slackapp-register\n   Adding app event processing\n   ok: created action slackapp/slackapp-event\n   Adding app command processing\n   ok: created action slackapp/slackapp-command\n   OAuth URL:\n   https://us-south.functions.cloud.ibm.com/api/v1/web/\u003cyour-namespace-id\u003e/slackapp/slackapp-register\n   Command URL:\n   https://us-south.functions.cloud.ibm.com/api/v1/web/\u003cyour-namespace-id\u003e/slackapp/slackapp-command\n   Event Subscription Request URL:\n   https://us-south.functions.cloud.ibm.com/api/v1/web/\u003cyour-namespace-id\u003e/slackapp/slackapp-event\n   ```\n\n   \u003e Note: the script can also be used to *--uninstall* the Cloud Functions artifacts to *--update* the artifacts if you change the action code, or simply with *--env* to show the environment variables set in **local.env**.\n\n### Deploy from Windows\n\n1. Copy the file named **template.local.cmd** into **local.cmd**\n\n   ```\n   copy template.local.cmd local.cmd\n   ```\n\n1. Get the service credentials for the Cloudant service created above and set CLOUDANT_url\nin `local.cmd` to the corresponding value (url). Make sure you take the full url including the username and password https://username:password@hostname.cloudant.com.\n\n1. Set the values for SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_VERIFICATION_TOKEN - these are the App Credentials we've seen in the previous steps.\n\n1. Ensure your `ibmcloud fn` command line interface is property configured with:\n\n   ```\n   ibmcloud fn list\n   ```\n\n   This shows the packages, actions, triggers and rules currently deployed in your namespace.\n\n1. Create the actions:\n\n   ```\n   deploy.cmd --install\n   ```\n\n   If all goes well it outputs:\n\n   ```\n   Creating slackapp package\n   ok: created package slackapp\n   Adding app registration command\n   ok: created action slackapp/slackapp-register\n   Adding app event processing\n   ok: created action slackapp/slackapp-event\n   Adding app command processing\n   ok: created action slackapp/slackapp-command\n   ```\n\n   \u003e Note: the script can also be used to *--uninstall* the Cloud Functions artifacts to *--update* the artifacts if you change the action code, or simply with *--env* to show the environment variables set in **local.cmd**.\n\nOur actions are ready. Back to the Slack app configuration.\n\n## Complete the Slack app configuration\n\n### Add an Event Subscription\n\n1. Go to the **Event Subscriptions** section of your app\n\n1. Enable Events\n\n1. Set the Request URL to the URL of the `slack-event` web action. The URL should look like `https://us-south.functions.cloud.ibm.com/api/v1/web/your-namespace-id/slackapp/slackapp-event`\n\n   ![](xdocs/app-challengeaccepted.png)\n\n   \u003e Slack will contact this URL immediately. It should turn to **Verified** if the Cloud Functions configuration steps worked.\n\n### Listen to Bot messages\n\n1. Add a new Bot User Event for **message.im**\n\n   ![](xdocs/app-addbotevent.png)\n\n   \u003e This allows us to react to direct messages sent to a bot. We could select more event type but for our simple app will only deal with this one today.\n\n1. Save the changes\n\n### Set the callback URL for authentication\n\n1. Under OAuth and Permissions, add a new Redirect URL. This URL will be called when a user installs your application in a team. It should point to the `slackapp-register` web action. The URL should look like `https://us-south.functions.cloud.ibm.com/api/v1/web/your-namespace-id/slackapp/slackapp-register`\n\n   ![](xdocs/app-setoauth.png)\n\n1. Click **Save URLs**\n\n### Create a new command\n\n1. Under Slash Commands, **Create New Command**\n\n   ![](xdocs/app-newcommand.png)\n\n1. Set the values\n\n   1. Command: **/myserverlessapp**\n\n   1. Request URL: URL of the `slackapp-command` web action. The URL should look like `https://us-south.functions.cloud.ibm.com/api/v1/web/your-namespace-id/slackapp/slackapp-command`\n\n   1. Short Description: **A test command**\n\n   1. Usage Hint: **[param1] [param2]**\n\n   ![](xdocs/app-commandsettings.png)\n\n1. Save. This automatically creates a bot for the app.\n\n### Give the bot the permission to talk\n\n1. Go to **OAuth \u0026 Permissions**.\n1. Under **Scopes** / **Bot Token Scopes**, add the two OAuth Scopes: **chat:write** and **users:read**\n\nOur app is finally ready to be installed!\n\n## Add the app to your team\n\n1. To see what's happening behind the scene as Slack calls our actions, open a new command prompt and run\n\n   ```\n   ibmcloud fn activation poll\n   ```\n\n   \u003e Leave it running. Actions triggered by Slack will show up there\n\n1. Go to **Manage Distribution**\n\n   ![](xdocs/app-managedistribution.png)\n\n1. Click the **Add the Slack** button\n\n1. Authorize the app\n\n   ![](xdocs/app-authorize.png)\n\n   After a few seconds, the app is installed. You should see logs appearing in the activation   polling as Slack will be sending the registration info we will use later to interact with Slack channels and users.\n\n   In your web browser, you should see `Registration was successful. You can try the command in Slack or send a direct message to the bot.`\n\n   Ideally you would redirect to another page once the registration is completed.\n\n## Test the integration\n\n1. Go into your team in Slack\n\n1. Send a direct message to our new bot friend\n\n   ![](xdocs/team-newbot.png)\n\n   ![](xdocs/team-startchatwithbot.png)\n\n1. The bot replies\n\n   ![](xdocs/team-botchat.png)\n\n1. Go to the #general channel (although this could work from any place in Slack) and type ```/my``` you should see the custom command\n\n   ![](xdocs/team-customcommand.png)\n\n1. Try the command ```/myserverless two params``` as example\n\n   ![](xdocs/team-customcommandoutput.png)\n\n## Code Structure\n\n### Cloud Functions - Deployment Script\n\n| File | Description |\n| ---- | ----------- |\n|[**deploy.cmd**](deploy.cmd)\u003cbr/\u003e[**deploy.sh**](deploy.sh)|Helper script to install, uninstall, update the actions.|\n\n### Cloud Functions - Actions\n\n| File | Description |\n| ---- | ----------- |\n|[**slackapp-register.js**](actions/slackapp-register.js)|Handles the installation of the app in a team. It stores the authorization token in Cloudant for future use by the bot and commands.|\n|[**slackapp-event.js**](actions/slackapp-event.js)|Handles events triggered by the Events API. In this sample, it handles messages sent to the bot user and simply echoes the message sent by the user.|\n|[**slackapp-command.js**](actions/slackapp-command.js)|Handles custom commands. In this sample, it echoes the command parameters.|\n\n## Contribute\n\nPlease create a pull request with your desired changes.\n\n## Troubleshooting\n\n### Cloud Functions\n\nPolling activations is good start to debug the action execution. Run\n```\nibmcloud fn activation poll\n```\nand send a message to the bot or use a custom command.\n\n## License\n\nSee [License.txt](License.txt) for license information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud%2Fopenwhisk-slackapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibm-cloud%2Fopenwhisk-slackapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibm-cloud%2Fopenwhisk-slackapp/lists"}