Reach is a node.js module for sending notifications focused on simplicity and extensibility. What's unique about this project? In most cases apps traditionally support a limited set of notification methods, such as email, push notifications or sms, but in some cases, users would prefer being notified in some other way, such as Slack, Whatsapp, Telegram or Discord, or even all of them. The Reach SDK lets you or your app users select and configure their own notification methods, without needing to develop or implement each service.
The project was developed to support my various node.js projects, and avoid redeveloping the same functionality in each of them. I built the module to support Changd, which is a website monitoring tool. Using the Reach SDK allows users to select a myriad of notification methods, without the the underlying project having to implement, manage or maintain these options. I was inspired by Apprise (which is written in python) and used Uptime Kuma as a starting point.
If you would like to test out the concept, check out the Reach UI. It is a basic web app that lets you configure and send test notifications for each provider using your own parameters.
npm install --save reach-sdk
All notification providers have one common required parameter, named text. This property is the same across all provider types to ensure that the recipient recieves the same notification on any of their selected platforms.
- Import, create, and instantiate an instance of Reach.
const { Reach } = require('reach-sdk');
Reach.init();
- Send a notification (E.g. Slack)
const text = "Your order has been received!";
const slack_notification = {
name: "slack",
required: {
slackwebhookURL: "The users webhook URL",
text: text
}
}
const discord_notification = {
name: "discord",
required: {
discordWebhookUrl: "The users discord webhook URL",
text: text
},
}
console.log(Reach.send(slack_notification));
Notification providers are services which the Reach SDK can send messages to. The Reach SDK has been designed to allow developers and contributors to create or add their own custom providers. If you would like to improve, or create a provider for a service not currently offered, check out the _template in the resources folder, and please submit a pull request.
Below is a list of notification providers the Reach SDK currently supports. Open each to view additional details.
Alerta
required: {
alertaApiKey: "",
alertaApiEndpoint: "",
alertaEnvironment: "",
group: "",
event: "",
resource: "",
text: ""
},
optional: {
value: "",
tags: [""],
origin: "",
type: "",
service: [""],
correlate: [""],
severity: ""
}
In Alerta open the menu on the left, select API Keys and create a new API key. The key will need the write:alerts scope. The API Endpoint can be found in the About menu screen.
Amazon SES
required: {
accessKeyId: "accessKeyId",
secretAccessKey: "secretAccessKey",
from: "",
to: "",
subject : "",
text: ""
},
optional: {
cc: "",
bcc: "",
html: "",
attachments: ""
}
Please follow this document to setup SES: Guide
Bark
required: {
barkApiUrl: "",
deviceKey: "",
title: "",
text: ""
},
optional: {}
In order to use Bark push notifications with their iOS app, you need a Bark server. You can set one up using their guide and Docker is a quick and easy option. Once you have the server running, you will need the Server URL and the Device Key parameters, you can find the Device Key in the mobile app in the "Server List" screen (Alphpa numeric code) below the server address.
Click Send SMS
required: {
clicksendsmsLogin: "",
clicksendsmsApiKey: "",
clicksendsmsToNumber: "",
clicksendsmsSenderName: "",
text: ""
},
optional: {
source: ""
}
In the Click Send admin panel, you can get your SMS login and API Key from the Developers, API Credentials screen.
Discord
required: {
discordWebhookUrl: "",
text: ""
},
optional: {
discordUsername: ""
}
In Discord, open the channel settings and select Integrations. Create a new webhook and Copy the Webhook URL into the discordWebhookUrl parameter. The discordUsername can be any string, if empty, it will be the bots name that was provided when creating the webhook.
Gitter
required: {
accessToken: "",
roomId: "",
text: ""
},
optional: {}
Gitter notifications require a Personal Access Token, this can be created from their developer site. Messages can be sent to rooms you are already a member of. In order to get the room ID, you will need to use something like Chrome Developer Tools to view network requests. Open Chrome dev tools and select the Network requests tab, clear the history (if needed) and open the room, this should show the API call to the chatMessages endpoint which will include the room ID. E.g. https://gitter.im/api/v1/rooms/62d804996da03739849a4d67/chatMessages
Google Chat
required: {
googleChatWebhookUrl: "",
text: ""
},
optional: {}
Important: webhooks are only enabled for Google Workspace accounts, not personal Gmail accounts. Please follow this document to setup a incoming webhook and get the URL: Guide
IFTTT
required: {
iftttServiceKey: "",
eventName: "",
text: ""
},
optional: {}
Setup a webhook in IFTTT using this URL. Next create a new applet and note its name as this needs to be specified in the eventName parameter, use a "Webhook" as the "If" trigger. You can find the iftttServiceKey in Documentation from the webhooks page.
Line
required: {
lineChannelAccessToken: "",
lineUserID: "",
text: ""
},
optional: {}
Open Developer Console, create a provider. Open the new provider and create a new Messaging API channel. Complete the required fields and navigate to the new channel. On the Basic Settings screen, scroll to the bottom and note your Line User ID, use this in the required parameter field and where you will recieve your messages. To get a access token, select the "Message API" tab, and create a channel access token at the bottom of the screen.
Mailgun
required: {
smtpUsername: "",
smtpPassword: "",
smtpFrom: "",
smtpTo: "",
subject : "",
text: ""
},
optional: {
smtpCC: "",
smtpBCC: "",
html: "",
attachments: ""
}
Once you have your mailgun account setup, you can get your username and password from the SMTP page on your domain.
SMTP
required: {
smtpHost: "Server Host",
smtpPort: "Server Port",
smtpFrom: "",
smtpTo: "",
subject : "",
text: ""
},
optional: {
smtpIgnoreTLSError: "True/False - Boolean",
smtpDkimDomain: "",
smtpDkimKeySelector: "",
smtpDkimPrivateKey: "",
smtpDkimHashAlgo: "",
smtpDkimheaderFieldNames: "",
smtpDkimskipFields: "",
smtpUsername: "",
smtpPassword: "",
smtpSecure: "TLS?",
smtpCC: "",
smtpBCC: "",
html: "",
attachments: ""
}
Please follow your hosting providers' instructions for setting up and getting the above parameters.
Signal
required: {
signalUrl: "",
signalNumber: "",
signalRecipients: "",
text: ""
},
optional: {}
Signal requires that a middleware Rest API is in place before it can be used with the reach API. Please see this guide for setting up a middleware layer using docker, you can then use this endpoint as the signalUrl.
Slack
required: {
slackwebhookURL: "",
text: ""
},
optional: {}
Follow this guide to create a webhook: Guide. TL;DR - Open your workspace settings, create a new app and get the webhook details from the Incoming Webhooks page.
SendGrid
required: {
sendgridApiKey: "",
from: "",
to: "",
subject: "",
text: ""
},
optional: {}
Setup a API Key with access to the "Mail Send" role, using the Settings menu from the SendGrid Dashboard/
Telegram
required: {
telegramBotToken: "Bot token",
telegramChatID: "Chat Id",
text: "Text"
},
optional: {}
Create a bot using the @botfather channel. Take note of the Access Token. To get the chat_id parameter, create a new group chat and add your new bot, also add @RawDataBot. This will print out the chat object, and in the object will be the TelegramChatID.
Matrix
required: {
matrixHomeServerUrl: "",
matrixAccessToken: "",
matrixRoomId: "",
text: ""
},
optional: {}
In order to send notifications to Matrix, Reach requires the Homeserver Url, a access token and the room ID. In the Element Webclient you can get the Homeserver URL and Access Token from the "All Settings" menu and Help and About screen in the Advanced section. The room ID can be viewed in the Room settings, under the Advanced screen.
Mattermost
required: {
mattermostWebhookUrl: "",
text: ""
},
optional: {}
In order to send notifications to Mattermost, you will need to enable incoming webhooks for your instance. You can do this from the Main Menu, under integrations. Copy the URL and use this in the mattermostWebhookUrl parameter.
Microsoft Teams
required: {
teamsWebhookUrl: "",
text: ""
},
optional: {}
In order to receive notifications in MS Teams, you need to enable a incoming webhook for the channel. Open the channel settings menu using the three dots next to the channel name in Channels list, and select connectors. Select Add for the incoming webhook. Once added, select configure, provide the name and press Create. You will then receive the webhook Url. For more information, see this: Guide
OneSignal
required: {
onesignalAppId: "",
onesignalApiKey: "",
text: ""
},
optional: {
title: ""
}
OneSignal requires that you create a setup a API Key.
PagerDuty
required: {
pagerDutyApiKey: "",
pagerDutyRoutingKey: "",
eventAction: "", (trigger, acknowldge or resolve)
source: "",
severity: "", (critical, warning, error or info)
text: ""
},
optional: {
dedup_key: "",
timestamp: "",
component: "",
group: "",
class: "",
custom_details: {}
}
To setup PagerDuty to work with Reach, you will need a Api Key and Routing Key (aka Integration Key). The Api Key can be found in the Integrations Menu, then API Access and Keys page. The Routng Key will be provided when you create a new Service, the service will need to haev the Events API v2 Integration selected, after creating you will be provided with the Routing/Integration key.