Go to Slack

An introduction to messages

The simplest Slack messages are brief statements, authored by users and bots, and broadcast to channels for one or many members to read. Messages are the basic building block of all conversations on Slack.

Messages notify, communicate, and motivate. They invite response. To have their buttons pressed. Their wit awarded. Sometimes messages even inspire people to do the best work of their lives.

A gorgeous message

Slack messages are part message, part medium. Posting messages means sending not only a bundle of words, but also a series of attributes both describing and containing content.

We have a lot to say about messages. This particular document is a primer, a jumping off point for further adventures in messaging.

Composing messages

A local comic book store uses Slack to keep its staff informed and engaged in their collective hobby turned vocation. The owner set up an incoming webhook to notify employees when new issues hit the shelves.

A short message from a comic book shop

To send this formatted text as an incoming webhook, the owner followed these very docs you're reading now to construct a JSON hash in our message builder that formatted the important notification with distinctive italics.

{
  "text": "New comic book alert! _The Further Adventures of Slackbot_, Volume 1, Issue 3."
}

You can try that out in message builder too.

As effective and simple as that notification is, Slack messages are capable of more unobtrusive ornamentation and interaction opportunities.

If you're wondering how to compose truly great messages — check out our message guidelines.

Formatting messages

Get your point across with bold, italics, and other markup-fu. If you're familiar with similar markup formats like Markdown, you'll be sending beautiful messages in no time.

Simple formatting

Make text bold by wrapping it in asterisks (*) like this: 

*Well, this is a bold statement.*

(Message Builder example)

Italics adds emphasis without the gaudiness of being bold. Wrap your text in underscores to italicize.

My _spidey sense_ tells me I'll have to skip lunch today.

(Message Builder example)

Some times you want a line break to appear in your text. Perhaps you're writing poetry about your business' bottom line. Use the special control character \n to denote a new line. Yes, that's technically two characters.

The spent cents are tails\nI'll never see wag again

(Message Builder example)

Code blocks

If there's a short bit of code you want to appear inline, wrap a grave accent (`) around it.

Slack will render this kind of text in a readable monotype font.

We should be concerned if the variable value for `radioactive` is `true`.

(Message Builder example)

Finally, if you want to share a larger code block, you'll want to wrap it in multiple grave accents, which sounds like a bad accident waiting to happen but it's not.

Use three accents ``` before and after your code block, which likely will contain new line characters represented as \n as suggested above.

```\n{\n  "text":"A short self-referential message we're sending in `JSON`."\n}\n```

(Message Builder example)


There's even more to learn about message formatting — more ways to express yourself, and of course some complications that may arise.

Continue on in message formatting.

Simplify complex interactions with buttons

Users already can read, respond, and react to messages. There are so many interactive possibilities within those capabilities alone.

But if you really want to solicit specific answers from users, buttons are the way to go.

Messages containing buttons become even more interactive, as each clicked button sends a request to your servers where you get to decide what happens next:

  • Respond with additional messages, even more buttons.
  • Using chat.update, your messages can evolve as the consequences of users pressing buttons emerge.
  • Each button press sends an identifiable request to your servers where you decide what happens next.

You'll need a Slack app to use message buttons, as they are not supported when sending messages with custom integrations.

Be sure and read all about message buttons and how actions are invoked.

Meanwhile, back at work

Back at the comic shop, the manager has been busy developing a deeper Slack integration with their inventory management software.

Now when a comic book that's sold out comes back into stock, it's announced to employees and even gives them the opportunity to recommend it.

Looks like a great comic book is back in stock and it's time to ask employees what they think

This message highlights a number of message features. It includes a text field with a brief message and an emoji reference. It also contains four message attachments. The final attachment has been assigned a blue bar and contains two buttons, encouraging comic shop employees to click and share their opinion.

Here's the JSON message definition used to create a message like this:

{
    "text": "New comic book alert!",
    "attachments": [
        {
            "title": "The Further Adventures of Slackbot",
            "fields": [
                {
                    "title": "Volume",
                    "value": "1",
                    "short": true
                },
                {
                    "title": "Issue",
                    "value": "3",
            "short": true
                }
            ],
            "author_name": "Stanford S. Strickland",
            "author_icon": "http://a.slack-edge.com/7f18https://a.slack-edge.com/bfaba/img/api/homepage_custom_integrations-2x.png",
            "image_url": "http://i.imgur.com/OJkaVOI.jpg?1"
        },
        {
            "title": "Synopsis",
            "text": "After @episod pushed exciting changes to a devious new branch back in Issue 1, Slackbot notifies @don about an unexpected deploy..."
        },
        {
            "fallback": "Would you recommend it to customers?",
            "title": "Would you recommend it to customers?",
            "callback_id": "comic_1234_xyz",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "recommend",
                    "text": "Recommend",
                    "type": "button",
                    "value": "recommend"
                },
                {
                    "name": "no",
                    "text": "No",
                    "type": "button",
                    "value": "bad"
                }
            ]
        }
    ]
}

Try it!

Read all about how to simplify workflows with action-invoking buttons.

How to send messages

All this talk about writing a Slack message but so few words on how slipping missives into the system.

Messages enter Slack by way of many avenues, some with differing capabilities and approaches.

Users typing in a Slack app

Sure, it seems obvious and this is developer documentation after all, but it's worth pointing out that users type messages in Slack. They even follow some of the conventions documented here. But applications are capable of quite a few more messaging tricks.

Maybe users add some light formatting or an @mention. After pressing enter, their profound message is delivered to Slack and sent along to all the right members and bot users listening in from afar.

Typically when users post messages, they're sending them via the Real Time Messaging API.

Using incoming webhooks

A simple and effective way to send messages is with incoming webhooks.

Incoming webhooks are capable of handling the most simple or the most richly formatted messages with parades of interactive buttons.

Sending a message could be as easy as:

curl example
curl -X POST -H 'Content-type: application/json' \
--data '{"text":"This is a line of text.\nAnd this is another one."}' \
 https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Incoming webhooks are ideal for sending notifications.

Find out more in the incoming webhooks and preview your messages with the message builder.

Using the Web API

Use chat.postMessage to send messages or chat.postEphemeral to send ephemeral messages using the web API. The token you use will need the chat:write:bot or chat:write:user token scope applied to it.

Unfortunately, you can't send messages to this method with JSON directly. However, it does support an attachments HTTP parameter that accepts a URL-encoded string of a JSON hash. Which sounds like gibberish but isn't too difficult to pull off.

Read more about posting messages with the Web API.

Using the Real Time Messaging API

To send messages on behalf of the user owning a specific token, post message JSON directly into an open websocket connection in the Real Time Messaging API.

You cannot provide attachments nor buttons to messages posted over the RTM API. If your bot user needs to send more complex messages, use the web API's chat.postMessage or chat.postEphemeral.

Responding to slash commands

Slash commands are powerful way for users to demonstrate intent. When your command URL is invoked, you can respond with your message in JSON, including attachments or interactive buttons. You can even wait until later to respond by following up with posting more JSON to the invocation's response_url. Implementation is very similar to incoming webhooks.

Message buttons complement the slash command workflow well, especially when using ephemeral messages.

Responding to message button actions

Each time a message button is clicked, we send a request to your server and you can take that opportunity to add additional messages or replace the original. As with slash commands, you can also delay your response and perform follow up transformations and new messages.

Threading messages

Our documentation on message threads describes how messages knit together.