DEV Community: Suhas Deshpande

Building a Slack Integration for Your SaaS Notification System

Suhas Deshpande — Thu, 04 Aug 2022 18:32:43 +0000

For many organizations, Slack is the software of choice for business communication. Slack’s ubiquity in modern companies makes it one of the first notification integrations a SaaS company might want to build, possibly after email and mobile push notifications.

In our experience, Slack notifications are a great way to reach business users (as Slack is mostly used in a business context) with time-sensitive alerts or action items while they’re at work. Because the users are already in work mode, Slack notifications are suitable for anything from collaboration on documents and spreadsheets to workflows like approval requests or data access permissions. Slack is less suited for notifications outside of a work context or out of working hours.

To be able to send messages in Slack, a software system must integrate with Slack’s API. The resulting integration will allow your application to send Slack messages with helpful information to a Slack channel or a direct message thread. Here’s an example of a Slack message coming from GitHub’s Slack integration:

Here’s another example of a Slack integration from Salesforce:

Many organizations don’t quite know what to expect when building an integration for sending messages from their SaaS product to a Slack channel or a direct message. In this post, we offer details for developers who are planning to build a Slack integration for their product.

Technical aspects of a Slack integration

From a technical perspective, Slack offers a fairly conventional HTTP REST API, which will be straightforward to understand for developers who deal with web systems. The functionality made available through the API is extensive, and there are complex parts to it, but most Slack integrations for SaaS will likely only need to send messages. Messages are the core of Slack’s functionality, but we cover other actions that your app might need to take in Slack below.

For sending messages, the Sending Messages guide in the Slack API documentation is a helpful starting point. The steps required to send a message are:

Create a Slack app.
Request the correct permissions from the user.
Compose the message using one of Slack’s message types (or blocks).
Send the message via an API call.

The main way to send a message is the POST chat.postMessage endpoint, but it’s also possible to use other endpoints with slightly different functionality: the chat.postEphemeral endpoint, for example, sends messages that are only visible temporarily and for a specific user (helpful for things like error messages). It’s also possible, and in some cases easier, to send messages using an incoming webhook.

Beyond sending messages, other functionality that you can implement with Slack’s API includes:

Slash commands — simple chatbot functionality via commands in Slack DMs or channels
Editing messages that have already been sent — for example, if information has been updated
Bots that respond to direct mentions and interactions — for example, Hubot is an implementation of such a bot used by hundreds of teams
Bots that monitor all message traffic in a specific Slack channel or direct message thread (less common due to how inefficient it is to scan all messages in high-volume Slack channels)

Many software teams choose to develop all functionality relating to Slack or another messaging service either in a dedicated microservice (if you use microservice architecture) or at least in a separate section of your monolithic app. The reason to do this is to avoid tightly coupling the way you think about notifications to Slack’s API — doing so could cause issues when the time comes to add support for other messaging APIs. Another reason to use a separate service or namespace for the Slack integration is to implement message retries and other reliability-focused tweaks. Such code would be too complex to include inside your business logic.

In our experience, there are a few points that developers might not be thinking about when building a Slack integration, and we encourage you to consider them:

Many of our users run into Slack API rate limits at some point during their usage cycle. So it’s likely that you will need to retry sending a message at some point because of rate limits. Consider including retry functionality from the very beginning.
Messages sent by integrations might need to include images or other files, so consider how you’ll handle attachments. Slack offers convenient file upload functionality via the API that you can use, and it comes with built-in access controls. But you might prefer to use your own storage. In that case, authenticating requests to files can become painful because you won’t have Slack’s access control mechanism to rely on.
Make sure that your system is compliant with relevant regulations, in case you’re sending notifications that include PII or other sensitive data. We wrote about this recently in The Developer's Guide to SaaS Compliance — check it out.

User experience of a Slack integration: Our recommendations

When we advise our customers about Slack integrations, most of our advice centers less on the implementation details and more on the product functionality and customer experience side. We see teams who are building Slack notification functionality for their SaaS focus too much on sending Slack messages and not enough on the value those notifications deliver to their users.

In this section, we offer a few recommendations on designing a helpful Slack notification experience.

Use Slack status information for optimal notification experience

Something that we find useful for many customers is keeping track of Slack statuses (the little “active” and ”away” indicators you see on people’s profiles). Consider whether you even want to send Slack notifications if someone is marked as being away in Slack — they might not be on their computer, or they might have intentionally changed their status. Is the notification you’re sending in Slack going to be actionable for someone on their phone? For many SaaS applications, the answer is no.

Our recommendation on handling status is to send Slack notifications when the user is active in Slack, and when they are not active, using a different channel like email or mobile push. We cover the topic of notification routing in Building a Routing and Preferences Service for Notifications.

Create message templates and have a workflow for updating them

In a SaaS product, it’s very unlikely that you’ll need just one type of Slack message. An app can require tens or hundreds of different notifications to be sent via Slack — and managing such large numbers of messages in your codebase can get tricky.

We recommend using templates instead of hard-coding messages in your application. It’s likely that your message templates will change over time, and you might want to add new notification types as you develop your product. By relying more on templates you can simplify the code review process — it’s easier for a peer to review a template change in a separate file than to jump between templates and code.

Another recommendation is to make templates editable outside of the code review process. This capability will enable colleagues outside of the development team to change and tweak notification templates themselves without the need to commit directly to the codebase.

Translation and language preferences

Are you going to only offer notifications in one language, or multiple? If you’re offering multiple languages, how does a user configure their preferences? You might want to add functionality within the Slack app that allows users to configure their language settings, or have a section within your web app (outside of Slack) with notification preferences. In any case, you need to store language preferences for each user and, eventually, have a good way to store translated versions of notification text as well.

We also recommend that you consider the translation workflow for notification text — the translators will likely not be able to navigate your codebase due to limited permissions or lack of technical context. Making it straightforward for the translators to work with your notification text will make it faster to implement new notification languages.

Slack integrations made easier with Courier

In this article, we’ve covered our recommendations for building a successful Slack integration for your SaaS product.

Prefer not to implement the integration yourself?

With Courier, sending a Slack message only requires one API call to Courier’s send endpoint. As part of that endpoint, Courier uses profile information to customize notifications, from individual preferences and personal information to language settings. Courier also offers templates that can be created in a well-designed web user interface (with a translation workflow built-in) and automations to define more advanced notification logic. And, by the way, once you integrate Courier, you can send other message types — like Microsoft Teams, Discord, email, SMS, and more.

If you’re interested in offloading building a strong Slack integration for your SaaS notification system, explore Courier and see if buying might be a better option than building in this case!

Illustration by Rebekka Dunlap

How I Used Raspberry Pi to Detect Water Leaks in My Home

Suhas Deshpande — Thu, 21 Apr 2022 17:44:33 +0000

When I realized there was a leak in my home, I knew it was time to put my expertise to work. I needed to call on my years of experience and passion for my job - as a software engineer? While at first glance, it may appear that a plumber would have been a better option, my argument is that there is a step to be taken before a plumber is even involved to fix a leak. And that is to detect the leak when it first happens.

Sure, I could have a plumber on call who checks for leaks every day, but seeing as that’s not an effective use of time or money, we needed to find an alternative to waiting for the problem to become bad enough to become a major problem. So if a 24/7 plumber-butler wasn’t an option, I thought some kind of automated system would be more realistic.

As it turns out, I had been thinking for some time about how to use a Raspberry Pi with Courier to bring notifications to life. This happened to be a perfect use case to try it out, so I decided to invest in the appropriate hardware and make use of my own software development skills to make sure that I would get a notification any time there was even a small leak in my home. This way, I’d know to call the plumber and handle the problem before it became too big to handle.

A leak can become an expensive problem

I myself had a water leak in my apartment some time ago. Because I didn’t know there was a problem until it was already too late, I had to call for a plumber when the damage was already done. Even for a simple leak like this, I ended up spending more than $500 to fix it.

But things could have been much worse. Major damage is often caused by mold spores.
Water leaks may also cause structural damage to property. Walls start swelling and warping, leading to cracks and holes in them. Furthermore, water leaks may negatively impact the value of a home.

I never wanted to deal with the complications, so I decided to take matters into my own hands. But of course, it was important to find a solution that would be fun and interesting as well as useful.

Building alerts for water leaks using Raspberry Pi

During my research for a solution in the form of alerts for water leaks, I found that I could use a small, affordable Raspberry Pi single-board computer to achieve my goal. With this tiny computer, I could read signals from my water sensor and then send those signals to my monitor.

To develop the project, which I called potential-octo-lamp, I first got all the hardware I needed to detect water leaks and connect to my computer. These devices included:

Raspberry Pi 4 Model B
Floor Water Sensor for Flood and Leak Detection
SanDisk 128GB Ultra MicroSDXC UHS-I Memory Card with Adapter
GPIO Breakout Expansion Kit for Raspberry Pi 4B The next step was to build “potential-octo-lamp” to send alerts for any detected water leaks. I built the project to check for leaks from the sensor using JavaScript and TypeScript programming languages. When potential-octo-lamp detects one, it then sends the result to my phone using Courier and Twilio.

With Courier, I could create custom alerts and define their titles and body text. I could also specify the communication channels through which the alerts should go and the recipients of these alerts. I also added a Twilio integration on Courier to deliver the contents of my alerts through the channels I specified — in this case, SMS and email.

How to use potential-octo-lamp to get alerts

Luckily, I’m a really nice guy and have made potential-octo-lamp open source. You can use my program to protect your own home from water leaks. Once you have all the hardware requirements listed above, connect your Raspberry to your water sensor. If you need help setting them up, this tutorial will help. Then you can begin using potential-octo-lamp to receive alerts for water leaks in five easy steps:

1. Create Your Courier and Twilio Accounts

If you don’t already have Courier and
Twilio accounts, you’ll need to sign up for both to configure your alert system. You may sign up for free on Courier and Twilio using an email address. Courier also allows you to use your Google or GitHub account to create an account.

2. Add Your Twilio Integration in Courier

Start by getting your Account SID, Auth Token, and messaging service SID from Twilio. Then log into your Courier account and go to Integrations. Add the Twilio info to their corresponding fields in Courier.

3. Retrieve Your Courier Authorization Token

When you create an account with Courier, you get an Auth Token so that you can safely make requests to and from Courier. Once logged in, you may retrieve your Courier Auth Token from the API keys page in Settings.

4. Clone potential-octo-lamp and Add Your Courier Auth Token

Next, go to GitHub and clone potential-octo-lamp. Because it’s unsafe to input your Courier Auth Token directly in your code, create a .env file and add it there. That way, it’s only visible to you.

5. Start the App

Finally, run the following commands one after the other to install dependencies and start checking for water leaks:

npm install

npm run build

npm run start

Loom Video

As soon as your floor water sensor detects leaks, potential-octo-lamp sends alerts for water leaks to the recipients you added on Courier. Then you can quickly repair the leak to prevent further damage.

Alerts are your answer to urgent situations

Potential-octo-lamp is open-source, so you can clone it and use it yourself. Any improvements or suggestions you may have are also welcome. You can raise an issue or reach out to me if you’d like to contribute to the project!

Why You Can't Replace REST with GraphQL

Suhas Deshpande — Fri, 09 Jul 2021 18:49:25 +0000

When I Googled “what is GraphQL” to learn more about the network protocols, all I saw was a comparison between REST and GraphQL. Most of the conclusions said, “use GraphQL.” It felt very binary (and trendy, for that matter), which is a problem because each product and use-case is unique. The fact is, whatever is newest and shiniest gets recommended more loudly. But you have to weigh the trade-offs and come up with a solution that is best for your situation.

There is a general understanding that either REST is better than GraphQL or vice versa. But the truth is they both address different problems and have different strengths and weaknesses. The question isn’t necessarily which one is better to use, but which one is better to use for specific circumstances. The best way to evaluate GraphQL, REST, or any other technology is to figure out your constraints based on the problem you are going to solve.

REST is a familiar option that can be implemented quickly
REST is the popular option, and for good reason: it’s quick to learn and implement. No one wants to write complex code if they don’t have to, so it’s not hard to see why quick and easy REST beats complex and clever GraphQL in most situations.

Two aspects of REST really shine. The first is that most ORMs (object–relational mapping) are optimized to work with REST, so that is not a problem you will have to solve. The second is REST is ideal for quick transactional requests, like the following:

Hey Courier, here is the payload (data), and I want to send a notification.

Hey Courier, what is the status of the last message I sent? Here is the ID since you don’t remember anything (stateless protocol so every request would provide precise input to query the state).

Additionally, with REST, you share the complexity between client and server. It has the benefit of proven patterns on how to do something, and it is definitely a well-proven, time-tested way of writing applications.

GraphQL is a different approach entirely, and it takes time and effort to create harmony. A system that is ideal for all your use cases will demand a lot of your time and will require your team to learn a lot of new concepts. It will force you to think in a certain way. We knew the cost of implementing GraphQL was probably going to be exhaustive — we expected the move was not going to be a do-it-once-and-forget-it thing.

The default option would be REST, and it’s a good one. Not just because it’s easy, but because there is an expectation of shared familiarity. Developers are likely to already know REST, whereas the same is not true for GraphQL. Unless you’ve identified needs that GraphQL is especially good at solving, REST is the default choice for a good reason. We would rather rest easy with REST, build something that both excites and helps our users, and get their product in the hands of their friends and family with time-tested methods.

REST vs. GraphQL

Let’s get right into it. With REST, there’s a lot of back and forth and manual work. Calls can result in either over-fetching or under-fetching based on the API contract. For example, if you end up with URIs (uniform resource identifiers) and not the specific data you’re looking for, the network calls you need to make on your client to get what you need escalate quickly.

Whereas GraphQL gets exactly the data you want on an API call. You have control over the query on a granular level, which is not something you can not easily do with REST since it’s not made for that specific purpose. Having this granular control will allow you to have fewer network calls and will require fewer developmental changes on client applications, since responsibility has been shifted to backends.

Applications can be informationally and visually heavy and also need to retrieve a variety of interconnected data. Fewer network calls in this scenario can be crucial for performance when this data needs to be retrieved in what are potentially many different and unknown situations. With the right implementation of GraphQL, you can eliminate the ability to over-fetch.

If your application is reading 1MB of data locally, it can finish the job in 0.4 milliseconds — as opposed to reading it over the network, which can take 150 milliseconds — a drastic difference. The point here is you want to optimize for fewer network requests. REST doesn’t give you those affordances. If optimizing for network requests is the most important factor, GraphQL would work better for you.

With GraphQL, you’ll get only the information you need. This is due to a self-documenting schema that’s easier to consume and has better tooling around consuming your endpoint.

GraphQL is more than just making queries

Writing GraphQL queries is just the tip of the iceberg. Implementing a brand new solution with GraphQL comes with challenges to overcome and problems to solve. The GraphQL stack might appear to be simple to get started with, but it gets complex quickly. It requires a lot of upfront learning and can be intimidating for newcomers to figure out how all these pieces fit together. Before you move to GraphQL, you need to understand what you’re signing up for.

Since GraphQL is not built into an ORM, it means there’s a lot of architectural choices that need to be made for your stack that will require extra effort to set up. It also comes with a steep learning curve. Part of that learning curve is control. GraphQL inverts control and hands it over to the client. Any amount of information can be requested, which means building a third-party API can become burdensome if you have expensive queries.

We all know naming things is hard, and GraphQL makes this a little harder. The GraphQL schema is a list of object types. It’s more than just a catalog; it’s a snapshot of the API. In a very large codebase, this could lead to naming collisions, so thoughtful naming conventions are a must.

In addition to the learning curves we’ve found ourselves dealing with, caching, one of the most loved and hated topics in computer science, is a whole lot more adventurous with GraphQL. Caching can happen on the client or on the server. REST uses headers to control the caching. However, GraphQL doesn’t have this affordance at the HTTP level.

All POST requests in GraphQL automatically opted out of the free HTTP caching you get in the browser. That means you have to bring your own cache when you’re in GraphQL land. Not only is this caching solution something you have to build, but you also have to maintain it — a consideration that should be thought about thoroughly.

In the end, you want to build something useful. GraphQL and REST can get you there, but be mindful about what either option means for you and your team long term. We identified that GraphQL was a great solution for some of our needs.

The REST and GraphQL partnership

The general wisdom is to choose either REST or GraphQL for your needs, but in reality, neither one covers all the bases. Our biggest motivation when building something is to evaluate how a developer would like using it. We started gradually introducing GraphQL first in our own internal APIs. We converted those endpoints to see how they worked for us internally before we exposed them externally.

But for Courier’s studio application, we went with GraphQL. Even though REST would allow us to build it, it wasn’t necessarily the best solution. It would require us to either implement (or add more) logic to handle new information and endpoints every time we decide to have new info on a page. Because the application has a growing need for data and information, and GraphQL solves this problem better for us.

Our backend data objects and business objects are rapidly becoming more interconnected, and GraphQL is a good way to relate each business object within our ecosystem. Managing all that in REST would be quite a task. And it comes with the downside of additional network requests.

GraphQL solved our constraints fairly well. So while conventional wisdom states we should move to GraphQL entirely, the fact is, for customer-facing APIs, we need REST. For our own frontends, however, GraphQL is the answer.

The GraphQL journey at Courier

We decided to tackle the learning curve even though learning has uncertain pay-offs. Everything we do has opportunity cost, and early adoption of something like GraphQL can feel like cargo cult-like behavior. But in the end, GraphQL works for us, with our circumstances.

Courier frontend is growing rapidly with the need to present rich information coming from various sources. REST could work, but GraphQL would work even better because of the query-able, type-safe nature of GraphQL.

Let’s take a look:

type Notification implements Node {
   archived: Boolean
   brandEnabled: Boolean
   brandId: String
   categoryId: String
   created: DateTime! @iso8601
   draftId: String
   draft: TemplateDraft
   eventMaps: EventMapConnection
   id: ID!
   name: String!
   tagIds: [String]
   templateId: String!
   updated: DateTime @iso8601
}

Here is a type defined in our GraphQL. We know in the future this Notification node will have more information needed. Say, a use-case to present all the collaborators involved in building this notification. With GraphQL (based on our existing pattern), we can easily extend the Notification node and add an edge or connect it to User (collaborator), so this extensibility works out great for our use case.

Another big advantage of GraphQL is the fact we can choose what data to get from our backend. Let’s steal this analogy from Dan Abramov where he explains the new React 18 batch rendering feature. Let’s say you need to go shopping for breakfast items at the store. Not only would you ideally like to come up with a reasonable list of items before going to the store, but you’d also want to optimize the number of trips you need to take.

The grocery scenario is quite similar to client applications needing to make additional network calls to the backend, like every time there’s a need for additional fields. GraphQL solves this by providing a declarative, type-safe mechanism to query data from your backend.

It’s fairly easy to look at the query below and figure out what information you can get.

query {
   user {
       role {
           label
           key
       }
       signature
           workspace {
               created
               id
               name
               usage
           }
       userId
       firstName
       lastActive
   }
 }

And tooling like introspection allows us to go even further! Introspection lets you gather information about supported queries in the GraphQL schema — you can get autocomplete schema definitions with type information. Beyond that, strong-typing makes introspection easier. This can be accomplished using TypeScript interfaces and is what will allow you to specify what your data is as well as automate a lot of the documentation.

This declarative approach to query information resonated with us about why GraphQL is compelling to use. So we chose GraphQL for our client applications because it provides strong typing and structured queries. GraphQL has a specification that makes it intuitive to build applications.

We haven’t given up REST altogether, though — we’re still using REST for our external APIs. This is because they’re transactional in nature, and it isn’t advantageous for us to expose an external GraphQL endpoint just yet based on the simplicity of our REST endpoints.
These are some of the reasons we love GraphQL at Courier.

What we’ve learned

Since we are a developer API product, it’s expected that we support all formats, REST obviously included. REST is widely used, popular, easy to maintain, and has an easy triage way of exposing endpoints. We know how and what to measure in our REST endpoints. We have pretty decent tooling built around the REST ecosystem, and moving it to GraphQL won’t add much value to the user or the business right away.

But GraphQL works best for us moving forward with our client applications. Exposing Courier’s functionality to external developers, we will still be resting on REST. And we still have a decent amount (if not most) of Courier’s functionality exposed via REST endpoints.

We have been running GraphQL on NodeJS for more than one year at this point. It has increased our velocity to push new features as well as given us a significant performance boost in our Studio application. We get the advantage of the high bandwidth on the server side to pull data from GraphQL’s middle layer, which is responsible for stitching data from various data sources.

So what’s right for you?

GraphQL is an exciting field — with a learning curve! But once you get the hang of it, specifications provide great tooling out of the box and saves a lot of code. Finding the balance between getting features out the door and adopting new technology can be a challenge. Finding the iterative approach that gives you time to adopt new technology would help you gradually increase your chances of success.

So there is no silver bullet that solves all the problems. New solutions are inspired by shortcomings in existing technology, but they come with new sets of challenges. Everyone’s situation is different, and contextualizing the solutions based on your problem space is the way to think when making these fun decisions.