Go to Slack

Communicating with users

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read next:Plotting out interactive flows

The message is at the core of how you communicate in Slack and apps also use messages to interact with your team members.

Messages don’t have to be just simple text notifications, though. They can include rich formatting and even complex user interfaces. To create these types of messages, you’ll use a UI framework we call Block Kit. These powerful building blocks for messages allow you to build complete workflows right inside Slack, that work just as well on our mobile devices as they do on your desktop, without any additional code or configuration.


Pushing to Slack

The most common point to start building a Slack app is also one of the most straightforward — pushing messages into a workspace. These can take the form of a simple heads up from another app or system, or they can be richly formatted messages that include images, addtional contextual data, and interactive components like buttons or select menus.

These notifications also make an ideal starting point for your app because they're easily discoverable to everyone on your team. Once your app is installed, configured, and built, notifications will simply start to appear for your users — they won’t have to set anything up to start receiving them.

Because notifications are an easy way to start posting in a workspace, it's important to make sure you're crafting the right notifications and sending them to the right place. Overwhelming your colleagues with alerts is a sure-fire way to get your app uninstalled. We've written a set of guidelines on how your app can effectively communicate with the humans on your team.

You have two options for posting messages via your app — incoming webhooks and the chat.postMessage API method — each with a different level of complexity. The folowing section will help you choose the right option for your app.

Incoming webhooks

The first option -- incoming webhooks -- is the most straightforward to set up but also the least flexible. When you create a Slack app that uses incoming webhooks, the person who installs the app chooses a channel that receives the incoming messages. The app will then generate a unique URL that you will use to post messages into Slack.

This is great for those times when you just want a mechanism for posting without needing to manage state or handle authentication credentials. In fact, it's possible to post via a webhook using nothing more than the standard Unix curl command, like this:

curl https://hooks.slack.com/services/T12345678/B98765432/ABC123DEF456GHI789000XXX
Content-type: application/json
{
    "text": "Hi there!"
}

The URL is completely unique to your workspace and to the channel you specified at install time. The webhook URL is only able to post into the single channel you set up and you can't read data from a Slack workspace using the generated hash. It's important to keep this URL secure since anyone with access to it can post a message into your Slack workspace.

Incoming webhooks include the ability to add message formatting, making it possible to generate fairly sophisticated messages with nothing more than a webhook. A common use cases for incoming webhooks is to set up systems monitoring on remote servers -- a process might run periodically to check overall system health, for example. If there's a problem, it could post a notification into Slack with details and even include a generated chart showing what the issue might be.

Incoming webhooks do have a few key limitations. First, they can only post to a single channel, which is specified when the app is installed.

On their own, incoming webhooks can’t receive responses to the messages they post or process responses from interactive elements like buttons. It’s probably best to think of incoming webhooks as one-way only communication flows that are simple to set up and used for posting notifications into your workspace.

chat.postMessage

For complete control over posting messages across an entire workspace, there's the chat.postMessage Web API method. Using chat.postMessage, your app can:

  • post into any channel it has access to, including threads to individual messages
  • compose sophisticated app-like interfaces using Slack's Block Kit UI framework (more on this a bit later), and
  • receive responses to build true interactivity into your app

These extra powers come with a bit more upfront setup, however. Rather than having a single, automatically generated URL, your app will call the Slack API with an authentication token you receive when the app is installed. These tokens are powerful and should be safeguarded within your app's code.

Similar to incoming webhooks, using chat.postMessage is a matter of making an HTTP call to Slack's API. You can use something like the Unix curl command again but will most likely be using an HTTP library alongside your programming language of choice. Calling the API looks something like this:

curl https://slack.com/api/chat.postMessage —``token xoxp-abc... —``body ...

Formatting messages with Block Kit

Apps have the ability to build richer user interfaces with a UI system we call Block Kit.

As the name implies, you build messages out of individual (or groups of) pre-defined blocks such as text, thumbnail images, dividers, and interactive elements like buttons, dropdown menus, and date pickers. Even with a relatively small number of starting blocks, it's possible to customize interfaces unique to the needs of your workflow.

Block Kit UI's are defined as JSON, which makes them fairly straightforward to build without having to learn a new markup language. We also have a tool called Block Kit Builder for creating sample messages that will generate the corresponding JSON automatically. This is great for letting anyone on your team sketch out some ideas for messages and then copy and paste the resulting JSON.

There are no hard and fast rules on when to choose incoming webhooks vs. chat.postMessage. It really does depend on the needs of your workflow. If you just want a lightweight way to send simple notifications from another system into a Slack channel, without having to worry about managing auth tokens, incoming webhooks are an obvious and easy way to get started.

If you already know you're going to want these messages to go beyond just notifications and make them something people can respond to, or if you want to build a more sophisticated UI, it's worth going through a few extra steps to set your app up using chat.postMessage.

It's also possible to use both options, either in separate contexts or as a way to iteratively build your app. As you and your team are getting started, incoming webhooks are great for getting going quickly. These can be replaced or augmented with more sophisticated messages via chat.postMessage.