Go to Slack

Sending messages

Apps that only 'listen' can be useful, but there's so much more utility to explore by transforming a monologue into a conversation.

Give your app the gift of dialogue by setting it up to send Slack messages.

This guide will help you learn a basic way to accomplish this, and show you the paths you can take to make things complex and interactive.


Getting started with sending messages

One thing you'll need before starting is a Slack app. If you don't have one yet, here's a very quick guide to help you create one. Make sure you create the app in a workspace that won't mind you posting lots of test messages!

After you've done that, come back here and keep reading.

Requesting the necessary permissions

Each Slack app starts off without permission to do very much at all. You will have to grant your app the correct scopes that are required in order for you to publish messages.

There are lots of scopes available, and you can read our OAuth guide for more information on why they're needed, and what they do.

For the purposes of this guide, however, we'll skip over that and just tell you the permissions we need right now.

The first is channels:read. That scope lets your app retrieve a list of all the public channels in a workspace so that you can pick one to publish a message to. If you already know the ID of the channel you wish to send messages to, you can skip out on requesting channels:read.

The second is chat:write:bot. This one grants permission for your app to send messages as itself (apps can send messages as users or bot users, but we'll cover that later).

Requesting these permissions is easy:

  1. Load up the settings for your app from the app management page.
  2. In the navigation menu, choose the OAuth & Permissions feature.
  3. Scroll down to the Scopes section, and pick channels:read and chat:write:bot from the drop down menu.
  4. Click save changes.
  5. Scroll back to the top of this page and look for the button that says Install App to Workspace (or Reinstall App if you've done this before). Click it.

You'll now see a permission request screen to install your app to its original workspace.

If you had already installed your app to its original workspace before, you might still see the permissions screen if the scopes you just added weren't previously granted to your app.

Authorize your app and you should see a success message. On the OAuth & Permissions settings page you're brought back to, you should now see an OAuth access token available.

Grab this token and store it for later, as we'll use that token to make some Web API calls.

Picking the right conversation

Now we need to find somewhere within your workspace that we'll send a message. This could be any Slack conversation, but we'll use a public channel in this guide.

We'll remind you again - it's not a good idea to attempt the instructions in this guide with a real, living workspace. If you really have to, then at least create a new, empty public channel within the workspace, for testing purposes.

Have a public channel that's suitable? Then hop over to our guide to retrieving messages and read the section about finding conversations.

When you've found the matching channel, make note of the id value, as we'll need that when publishing our message.

Dynamically picking conversations

This method works when you're sending only to one specific conversation, but a production app would likely be publishing messages in response to an invocation from a user. For example, a slash command or a custom action.

In those cases, you would receive a request payload upon invocation that would contain the source conversation ID. Read the docs for those features to see what the relevant request payload might look like.

Now that we've picked a destination, we need to decide what our message will look like.

Composing your message

Designing a message is a complicated topic, so we've broken it out into its own section that you can read at your leisure.

For this guide, we're going to bypass that and just publish a very simple plain-text message. Here's the message payload we're going to send:

{
  "channel": "YOUR_CHANNEL_ID",
  "text": "Hello, world"
}

That seems appropriate, right? Let's get down to the actual business of sending this message.

Publishing your message

We're nearly there, we just need to make one more API call, this time to chat.postMessage. Again substitute in the values of the token and conversation ID that you noted earlier:

POST https://slack.com/api/chat.postMessage
Content-type: application/json
Authorization: Bearer YOUR_TOKEN_HERE
{
  "channel": "YOUR_CHANNEL_ID",
  "text": "Hello, world"
}

Note that this time we're using a POST request, so your token from before has to be included in the header of the request as a bearer token.

Submit the request and unlike a typical mail service, your message should be delivered instantly. You'll get back a response payload containing an ok confirmation value of true, and other data such as the channel the message was posted to. One very important piece of information in this response is the ts value, which is essentially the ID of the message, which you'll need if you want to reply to this message.

Locate the Slack conversation the message was sent to and it should be waiting for you, like this:

Message in Slack conversation that says Hello, world

Amazing work - you've now implemented one of the core pieces of functionality for any Slack app. Keep reading to see how you can add some complexity.


Replying to your message

In some cases, you might find it more useful for your app to reply to another message, creating a thread. For example, if your app is sending a message in response to being mentioned, then it makes sense to add a threaded reply to the source of the mention.

First, make sure the message you want to reply to isn't a reply itself, as shown in our retrieving messages guide.

For this guide, let's assume the message is an unthreaded one. In fact, let's reply to the message you just published.

You need three pieces of information to reply in a thread:

  • An access token with the right permissions, like the token created earlier.
  • The channel that the parent message lives in.
  • The ts value of the parent message.

You should still have the last two pieces of info from the response payload you received after publishing the parent message.

In more generic terms, you can also find the ts value of messages by following our guide to retrieving individual messages.

Pulling all that data together, we can make another chat.postMessage API call to publish a reply:

POST https://slack.com/api/chat.postMessage
Content-type: application/json
Authorization: Bearer YOUR_TOKEN_HERE
{
  "channel": "YOUR_CHANNEL_ID",
  "thread_ts": "PARENT_MESSAGE_TS",
  "text": "Hello again!"
}

You'll see another API response payload containing info about the newly published threaded reply. Go back to the same conversation in Slack, and you'll see your original message now has a reply:

Message in Slack conversation that says Hello, world with a reply saying Hello again!

When publishing threaded reply messages, you can also supply a reply_broadcast boolean parameter, as listed in the relevant API docs. This parameter, if set to true, will 'broadcast' a reference to the threaded reply to the parent conversation. Read more about the Slack user-facing equivalent of this feature here.


Sending messages as other entities

All of the examples we've shown you so far have involved a message being posted as the app. But there are other options for apps when publishing that will make it appear that the message has been posted by a user or a bot.

Impersonating users

Apps can publish messages that appear to have been created by a user in the conversation. The message will be attributed to the user and show their profile photo beside it.

This is where we give the power and responsibility speech - this ability should only be used when the user themselves gives permission to do so.

The first part of this is that it's impossible to post as the user unless your app requests an additional permission scope called chat:write:user.

The second part is that your app should only use this feature in response to an inciting user action. It should never be unexpected or surprising to the user that a message was posted on their behalf, and it should be heavily signposted in advance.

Okay, with that all said, the act of posting as the user is relatively simple. Once you've gathered the aforementioned permission scope, you'll be able to make calls to chat.postMessage on behalf of the user, using a field called as_user. Here's our first example adjusted to post as the user instead:

POST https://slack.com/api/chat.postMessage
Content-type: application/json
Authorization: Bearer YOUR_TOKEN_HERE
{
  "channel": "YOUR_CHANNEL_ID",
  "text": "Hello, world",
  "as_user": true
}

Note that this impersonation method will only work with user tokens.

Bot users

Within your app you can generate bot users that can have their own distinct identities - such as their own profile photos and display names. It will still be identified as an app within Slack.

To post a message as a bot, rather than your app, simply call the publishing method you're using with the bot user token, and as_user set to true as above.


Many ways to send messages

In this guide, we've shown you one way your app can publish messages to Slack, but there are many other ways to accomplish the same task.

Below we have collected links to the guides for each of the various methods that allow for the publishing of messages:

Method Description
chat.postMessage A Web API method that sends a message to a conversation. We used this above.
chat.postEphemeral A Web API method that sends an ephemeral message to a conversation.
Incoming webhooks A uniquely generated URL that is tied to a specific conversation. Send an HTTP POST to one to publish a message.
response_url An incoming webhook that is generated because of an interaction in a message. You're going to use this a lot if you publish interactive messages.
Real Time Messaging API This API does not support layout blocks or attachments. We don't recommend you use it for messaging, but it does exist, so we'd be remiss if we didn't mention it.