Legacy: An outmoded introduction to messages

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.

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.

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

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

As effective 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.

Basic formatting

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

*Well, this is a bold statement.*

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.

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

Code blocks

If there's a short bit of code you want to appear inline, wrap a grave accent (<code></code>) 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`.

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```

There's even more to learn about message formatting — more ways to express yourself.

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.

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": "Now back in stock!:tada:",
    "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-gov.com/80588/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"
                }
            ]
        }
    ]
}

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

Take action! Visual app interactions

Buttons are excellent ways to let users interact with messages posted by your app, but what about all those other many, many, many (many) messages that weren't?

Here's where actions come in - once you create a custom action and associate it with your app it'll be available to use with practically any message.

These custom actions provide a visual way for people to interact with your app from Slack - perfect for users who aren't comfortable with the verbose nature of slash commands.

Read our comprehensive custom actions docs to find out how to set them up and start using them with your app.

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

It's worth reminding 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

An effective way to send messages is with incoming webhooks.

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

Sending a message could be as easy as:

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.

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.

Message permalinks

Easily generate a permalink URL for any message using chat.getPermalink.