Skip to content

Commit 0bfca34

Browse files
mtojekmtojek
committed
docs: use Slack notifications
1 parent d8ddd07 commit 0bfca34

File tree

1 file changed

+204
-0
lines changed

1 file changed

+204
-0
lines changed

‎docs/admin/notifications/slack.md

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Slack Notifications
2+
3+
[Slack](https://slack.com/) is a popular messaging platform designed for teams
4+
and businesses, enabling real-time collaboration through channels, direct
5+
messages, and integrations with external tools. With Coder's integration, you
6+
can enable automated notifications directly within a self-hosted
7+
[Slack app](https://api.slack.com/apps), keeping your team updated on key events
8+
in your Coder environment.
9+
10+
Administrators can configure Coder to send notifications via an incoming webhook
11+
endpoint. These notifications appear as conversation with a custom Slack app.
12+
13+
## Requirements
14+
15+
Before setting up Slack notifications, ensure that you have the following:
16+
17+
- Administrator access to the Slack platform to create apps
18+
- Coder platform with notifications enabled
19+
20+
## Create Slack Application
21+
22+
To integrate Slack with Coder, follow these steps to create a Slack application:
23+
24+
1. Go to the [Slack Apps](https://api.slack.com/apps) dashboard and create a new
25+
Slack App.
26+
27+
2. Under "Basic Information," you'll find a "Signing Secret." Keep it safe for
28+
verification if needed.
29+
30+
3. Under "OAuth & Permissions", add the following OAuth scopes:
31+
32+
- `chat:write`: To send messages as the app.
33+
- `users:read`: To find the user details.
34+
- `users:read.email`: To find user emails.
35+
36+
4. Install the app to your workspace and note down the **Bot User OAuth Token**
37+
from the "OAuth & Permissions" section.
38+
39+
## Build a Webserver to Receive Webhooks
40+
41+
The Slack bot for Coder runs as a _Bolt application_, which is a framework
42+
designed for building Slack apps using the Slack API.
43+
[Bolt for JavaScript](https://github.com/slackapi/bolt-js) provides an
44+
easy-to-use API for responding to events, commands, and interactions from Slack.
45+
46+
To build the server to receive webhooks and interact with Slack:
47+
48+
1. Initialize your project by running:
49+
50+
```bash
51+
npm init -y
52+
```
53+
54+
2. Install the Bolt library:
55+
56+
```bash
57+
npm install @slack/bolt
58+
```
59+
60+
3. Create and edit the `app.js` file. Below is an example of the basic
61+
structure:
62+
63+
```js
64+
const { App, LogLevel, ExpressReceiver } = require("@slack/bolt");
65+
const bodyParser = require("body-parser");
66+
67+
const port = process.env.PORT || 6000;
68+
69+
// Create a Bolt Receiver
70+
const receiver = new ExpressReceiver({
71+
signingSecret: process.env.SLACK_SIGNING_SECRET,
72+
});
73+
receiver.router.use(bodyParser.json());
74+
75+
// Create the Bolt App, using the receiver
76+
const app = new App({
77+
token: process.env.SLACK_BOT_TOKEN,
78+
logLevel: LogLevel.DEBUG,
79+
receiver,
80+
});
81+
82+
receiver.router.post("/webhook", async (req, res) => {
83+
try {
84+
if (!req.body) {
85+
return res.status(400).send("Error: request body is missing");
86+
}
87+
88+
const { title, body } = req.body;
89+
if (!title || !body) {
90+
return res.status(400).send('Error: missing fields: "title", or "body"');
91+
}
92+
93+
const payload = req.body.payload;
94+
if (!payload) {
95+
return res.status(400).send('Error: missing "payload" field');
96+
}
97+
98+
const { user_email, actions } = payload;
99+
if (!user_email || !actions) {
100+
return res
101+
.status(400)
102+
.send('Error: missing fields: "user_email", "actions"');
103+
}
104+
105+
// Get the user ID using Slack API
106+
const userByEmail = await app.client.users.lookupByEmail({
107+
email: user_email,
108+
});
109+
110+
const slackMessage = {
111+
channel: userByEmail.user.id,
112+
text: body,
113+
blocks: [
114+
{
115+
type: "header",
116+
text: { type: "plain_text", text: title },
117+
},
118+
{
119+
type: "section",
120+
text: { type: "mrkdwn", text: body },
121+
},
122+
],
123+
};
124+
125+
// Add action buttons if they exist
126+
if (actions && actions.length > 0) {
127+
slackMessage.blocks.push({
128+
type: "actions",
129+
elements: actions.map((action) => ({
130+
type: "button",
131+
text: { type: "plain_text", text: action.label },
132+
url: action.url,
133+
})),
134+
});
135+
}
136+
137+
// Post message to the user on Slack
138+
await app.client.chat.postMessage(slackMessage);
139+
140+
res.status(204).send();
141+
} catch (error) {
142+
console.error("Error sending message:", error);
143+
res.status(500).send();
144+
}
145+
});
146+
147+
// Acknowledge clicks on link_button, otherwise Slack UI
148+
// complains about missing events.
149+
app.action("button_click", async ({ body, ack, say }) => {
150+
await ack(); // no specific action needed
151+
});
152+
153+
// Start the Bolt app
154+
(async () => {
155+
await app.start(port);
156+
console.log("⚡️ Coder Slack bot is running!");
157+
})();
158+
```
159+
160+
3. Set environment variables to identify the Slack app:
161+
162+
```bash
163+
export SLACK_BOT_TOKEN=xoxb-...
164+
export SLACK_SIGNING_SECRET=0da4b...
165+
```
166+
167+
4. Start the web application by running:
168+
169+
```bash
170+
node app.js
171+
```
172+
173+
## Enable Interactivity in Slack
174+
175+
Slack requires the bot to acknowledge when a user clicks on a URL action button.
176+
This is handled by setting up interactivity.
177+
178+
1. Under "Interactivity & Shortcuts" in your Slack app settings, set the Request
179+
URL to match the public URL of your web server's endpoint.
180+
181+
> Notice: You can use any public endpoint that accepts and responds to POST
182+
> requests with HTTP 200. For temporary testing, you can set it to
183+
> `https://httpbin.org/status/200`.
184+
185+
Once this is set, Slack will send interaction payloads to your server, which
186+
must respond appropriately.
187+
188+
## Enable Webhook Integration in Coder
189+
190+
To enable webhook integration in Coder, ensure the "notifications" experiment is
191+
activated by running the following command:
192+
193+
```bash
194+
export CODER_EXPERIMENTS=notifications
195+
```
196+
197+
Then, define the POST webhook endpoint matching the deployed Slack bot:
198+
199+
```bash
200+
export CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT=http://localhost:6000/webhook`
201+
```
202+
203+
Finally, go to the **Notification Settings** in Coder and switch the notifier to
204+
**Webhook**.

0 commit comments

Comments
 (0)