Module slack.trigger
ballerinax/slack.trigger Ballerina library
Overview
The Slack Trigger module allows you to listen to Slack Events API events, for example:
- Messages in channels, private channels, direct messages and the app's home (
message) - Mentions of your app (
app_mention), App Home opens and installs - Channel, file, reaction, pin, user group, team and user changes
- Shared channel invites, assistant threads and workflow function executions
This module receives Slack's event deliveries directly - it does not call Slack's Web API on your
behalf. Use the ballerinax/slack
connector for that, for example to reply to a message.
Key features
- Receives 84 Slack Events API events across 27 service types, including messages, mentions, reactions and channel changes
- Verifies every request with the app's signing secret (
X-Slack-Signature) and rejects requests older than five minutes - Answers Slack's
url_verificationchallenge itself, so the Request URL verifies without any code - Acknowledges each delivery before running your handler, so a slow or failing handler doesn't cause retries
- Services can be attached on their own path, so several triggers and HTTP services can share one port
- Trigger services are listed by
bal build --export-endpoints(Ballerina 2201.13.6 or later)
Setup guide
Before using this trigger in your Ballerina application, you need a Slack workspace where you can install apps, a Slack app, and a Ballerina service that Slack can reach over the internet to deliver events to. The two sections below cover both a quick local test setup and a production deployment.
Try it out locally
Use this flow to test your event handling logic on your own machine before deploying anywhere, using ngrok to expose your local listener to the internet.
-
Go to api.slack.com/apps, click Create New App, choose Blank app (or From scratch), give it a name and pick your workspace.
-
On the app's Basic Information page, under App Credentials, click Show next to Signing Secret and copy it. Slack signs every request with this secret, and the listener uses it to reject requests that did not come from Slack.
-
Write your service (see Quickstart below) with the signing secret as
webhookSecret, and run it locally withbal run. Note the port it's listening on (8090by default). -
Expose that port with ngrok:
ngrok http 8090Copy the
ForwardingURL ngrok prints out - this is your temporary public Request URL.
-
Make sure Settings > Socket Mode is turned off. With Socket Mode on, Slack sends events over a WebSocket instead of to your Request URL, and the listener never receives them.
-
Open Features > Event Subscriptions and turn Enable Events on.
-
Paste the ngrok forwarding URL into Request URL. Slack immediately sends a
url_verificationrequest with achallenge, and the listener answers it for you, so the field shows Verified as long as your service is running.
-
Under Subscribe to bot events, click Add Bot User Event and add the events your service handles, for example
message.channelsandapp_mention. Slack adds the OAuth scopes each event needs. Click Save Changes, then reinstall the app to your workspace when Slack asks, so the new scopes take effect.
-
Invite the app to a channel (type
/invite @<your app>in the channel) and post a message. Each delivery shows up in the ngrok console with200 OK, and your handler runs.
message.channels, message.groups, message.im, message.mpim and message.app_home are
subscription names, not separate events: Slack delivers all of them as a message event, so they
all arrive at MessageService.onMessage. Use event.channelType (channel, group, im,
mpim or app_home) to tell them apart.
Production / business integration
For production use, deploy your Ballerina service somewhere with a stable, internet-reachable HTTPS URL. Ballerina doesn't require any specific hosting platform - containers, a VM, a managed PaaS, or anything else that gives you a stable HTTPS endpoint all work equally well.
Rather than hardcoding webhookSecret as shown in the Quickstart, inject it via Config.toml (or
your platform's equivalent configuration/secret mechanism), since it's a configurable value:
[<your_org>.<your_module_name>.userInput] webhookSecret = "<your app's signing secret>"
Then set your production URL as the Request URL on the Event Subscriptions page.
Slack expects a response within three seconds and retries a delivery up to three times
otherwise. The listener responds before it runs your handler, so slow handlers don't cause
retries, but a retry can still arrive after a network problem. Use eventId to skip events you
have already handled.
Compatibility
| Version | |
|---|---|
| Ballerina Language | Ballerina Swan Lake 2201.13.0 |
Quickstart
To use the Slack Trigger in your Ballerina application, update the .bal file as follows:
Step 1: Import the Slack Trigger Ballerina library
import ballerinax/slack.trigger as slack;
Step 2: Initialize the Slack Listener
Initialize the trigger by providing the listener config and a port number/http:Listener object.
configurable slack:ListenerConfig userInput = { webhookSecret: "xxxxxx" }; listener slack:Listener slackListener = new (userInput, 8090);
webhookSecret should always be set to your Slack app's signing secret - this is what the trigger
uses to verify incoming requests actually came from Slack. Without it, the listener rejects every request with 401 Unauthorized.
If you don't provide a port it will use the default port, which is 8090 - webhookSecret should
still always be set.
listener slack:Listener slackListener = new (userInput);
Step 3: Use the correct service type to implement the service
Use the correct service type for the corresponding channel when implementing the service. For
example, if you need to listen to reaction events, use the ReactionService service type as
follows. Every remote function declared on a service type must be implemented - Ballerina requires
a complete implementation, not just the ones you care about.
service slack:ReactionService on slackListener { remote function onReactionAdded(slack:GenericEventWrapper payload) returns error? { return; } remote function onReactionRemoved(slack:GenericEventWrapper payload) returns error? { return; } }
Step 4: Provide remote functions corresponding to the events you're interested in
Remote functions must be implemented inside a service, on the matching service type for the
channel you're listening to - for example, slack:MessageService for messages.
import ballerina/log; service slack:MessageService on slackListener { remote function onMessage(slack:MessageEventWrapper payload) returns error? { log:printInfo("Message received", channel = payload.event.'channel, user = payload.event.user, text = payload.event.text); } remote function onMessageMetadataDeleted(slack:GenericEventWrapper payload) returns error? { } remote function onMessageMetadataPosted(slack:GenericEventWrapper payload) returns error? { } remote function onMessageMetadataUpdated(slack:GenericEventWrapper payload) returns error? { } }
Step 5: Run the service
Use the bal run command to compile and run the Ballerina program.
Step 6: Point your Slack app at your service
See Setup guide above for the full walkthrough (with screenshots) of exposing your service and setting the Request URL, for both local testing and production use.
Examples
The slack.trigger module provides practical examples illustrating usage in various scenarios.
Explore these examples,
covering common event handling use cases.
Report issues
To report bugs, request new features, start new discussions, etc., go to the Ballerina Library repository.
Useful links
- For more information go to the
slack.triggerpackage. - If you're moving from the older
trigger.slackpackage, see the migration notes. - For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.
Import
import ballerinax/slack.trigger;Other versions
0.9.0