This sample shows how to build a serverless Slack app using Slack Events API to receive events, with IBM Cloud Functions to process these events.
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 to view the code using API Connect.
Built using IBM Cloud, the app uses:
When 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.
From 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.
In this sample, we will:
To deploy this app, you need:
Your own Slack team is recommended if you want to play with the integration without impacting others.
Proceed to the new app creation in Slack
Type a name for your app, select your Slack team.
Click Create
View the App Credentials
We will need the Client ID, Client Secret and Verification Token in the next steps.
At this stage, we will put the configuration of the Slack app on hold. For the next app configuration steps to work we need to have our actions up and running.
Clone the app to your local environment from your terminal using the following command:
git clone https://github.com/IBM-Cloud/openwhisk-slackapp.git
or Download and extract the source code from this archive
Open the IBM Cloud console
Create a Cloudant instance named cloudant-for-slackapp.
Open the Cloudant service dashboard and create a new database named registrations
Select the database
Create a new document.
Replace the default JSON with the content of the file cloudant-designs.json
Copy the file named template.local.env into local.env
cp template.local.env local.env
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).
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.
Ensure your ibmcloud fn
command line interface is property configured with:
ibmcloud fn list
This shows the packages, actions, triggers and rules currently deployed in your namespace.
Create the actions:
./deploy.sh --install
If all goes well it outputs:
Creating slackapp package
ok: created package slackapp
Adding app registration command
ok: created action slackapp/slackapp-register
Adding app event processing
ok: created action slackapp/slackapp-event
Adding app command processing
ok: created action slackapp/slackapp-command
OAuth URL:
https://us-south.functions.cloud.ibm.com/api/v1/web/<your-namespace-id>/slackapp/slackapp-register
Command URL:
https://us-south.functions.cloud.ibm.com/api/v1/web/<your-namespace-id>/slackapp/slackapp-command
Event Subscription Request URL:
https://us-south.functions.cloud.ibm.com/api/v1/web/<your-namespace-id>/slackapp/slackapp-event
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.
Copy the file named template.local.cmd into local.cmd
copy template.local.cmd local.cmd
Get the service credentials for the Cloudant service created above and set CLOUDANT_url
in 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.
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.
Ensure your ibmcloud fn
command line interface is property configured with:
ibmcloud fn list
This shows the packages, actions, triggers and rules currently deployed in your namespace.
Create the actions:
deploy.cmd --install
If all goes well it outputs:
Creating slackapp package
ok: created package slackapp
Adding app registration command
ok: created action slackapp/slackapp-register
Adding app event processing
ok: created action slackapp/slackapp-event
Adding app command processing
ok: created action slackapp/slackapp-command
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.
Our actions are ready. Back to the Slack app configuration.
Go to the Event Subscriptions section of your app
Enable Events
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
Slack will contact this URL immediately. It should turn to Verified if the Cloud Functions configuration steps worked.
Add a new Bot User Event for message.im
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.
Save the changes
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
Click Save URLs
Under Slash Commands, Create New Command
Set the values
Command: /myserverlessapp
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
Short Description: A test command
Usage Hint: [param1] [param2]
Save. This automatically creates a bot for the app.
Our app is finally ready to be installed!
To see what's happening behind the scene as Slack calls our actions, open a new command prompt and run
ibmcloud fn activation poll
Leave it running. Actions triggered by Slack will show up there
Go to Manage Distribution
Click the Add the Slack button
Authorize the app
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.
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.
Ideally you would redirect to another page once the registration is completed.
Go into your team in Slack
Send a direct message to our new bot friend
The bot replies
Go to the #general channel (although this could work from any place in Slack) and type /my
you should see the custom command
Try the command /myserverless two params
as example
File | Description |
---|---|
deploy.cmd deploy.sh |
Helper script to install, uninstall, update the actions. |
File | Description |
---|---|
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. |
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. |
slackapp-command.js | Handles custom commands. In this sample, it echoes the command parameters. |
Please create a pull request with your desired changes.
Polling activations is good start to debug the action execution. Run
ibmcloud fn activation poll
and send a message to the bot or use a custom command.
See License.txt for license information.