Go to Slack

Attaching content and links to messages

Your messages are vehicles for all kinds of content and experiences. Build distinctive messages referencing images, external websites, and highlight relevant pieces of data. Then simplify team workflows by attaching interactive buttons.

A gorgeous message

Attachments let you add more context to a message, making them more useful and effective.

How message formatting appears

Before you get started with attachments

We recommend starting with our primer on messages. You should also be familiar with the complexities of sometimes not-so-simple message formatting.

Use attachments with intent and purpose. Use our message guidelines to help craft your messages, attachments, and interactive experiences.

When to use attachments

Attachments can be added to messages in different ways:

  • For Incoming Webhooks, send a regular payload, but include an attachments array, where each element is a hash containing an attachment.
  • For the Web API, include an attachments property, containing a JSON-encoded array of attachment hashes.

Attachment limits

Please limit your messages to contain no more than 20 attachments to provide the best user experience. Whenever possible, we'll throw a too_many_attachments error when attempting to include more than 100 attachments. When using incoming webhooks, you'll receive that error as a HTTP 400.

Unfortunately, we are unable to serve you an error when sending messages as part of a slash command or message buttons invocation response.

Use the Message Builder to preview your message formatting and attachments in real time!

Attachment structure

Messages can have zero or more attachments, defined as an array. Each hash in that array will contain multiple properties:

{
    "attachments": [
        {
            "fallback": "Required plain-text summary of the attachment.",
            "color": "#36a64f",
            "pretext": "Optional text that appears above the attachment block",
            "author_name": "Bobby Tables",
            "author_link": "http://flickr.com/bobby/",
            "author_icon": "http://flickr.com/icons/bobby.jpg",
            "title": "Slack API Documentation",
            "title_link": "https://api.slack.com/",
            "text": "Optional text that appears within the attachment",
            "fields": [
                {
                    "title": "Priority",
                    "value": "High",
                    "short": false
                }
            ],
            "image_url": "http://my-website.com/path/to/image.jpg",
            "thumb_url": "http://example.com/path/to/thumb.png",
            "footer": "Slack API",
            "footer_icon": "https://platform.slack-edge.com/img/default_application_icon.png",
            "ts": 123456789
        }
    ]
}

Try it!

Attachment parameters

Use these parameters to customize the appearance of a message attachment:

fallback

A plain-text summary of the attachment. This text will be used in clients that don't show formatted text (eg. IRC, mobile notifications) and should not contain any markup.

color

Like traffic signals, color-coding messages can quickly communicate intent and help separate them from the flow of other messages in the timeline.

An optional value that can either be one of good, warning, danger, or any hex color code (eg. #439FE0). This value is used to color the border along the left side of the message attachment.

Screenshot of attachments with colors

pretext

This is optional text that appears above the message attachment block.

Screenshot of an attachment with pretext

author parameters

The author parameters will display a small section at the top of a message attachment that can contain the following fields:

  • author_name

    Small text used to display the author's name.

  • author_link

    A valid URL that will hyperlink the author_name text mentioned above. Will only work if author_name is present.

  • author_icon

    A valid URL that displays a small 16x16px image to the left of the author_name text. Will only work if author_name is present.

Screenshot of an attachment with an author image and name

title and title_link

The title is displayed as larger, bold text near the top of a message attachment. By passing a valid URL in the title_link parameter (optional), the title text will be hyperlinked.

Screenshot of an attachment with a title

text

This is the main text in a message attachment, and can contain standard message markup. The content will automatically collapse if it contains 700+ characters or 5+ linebreaks, and will display a "Show more..." link to expand the content. Links posted in the text field will not unfurl.

Screenshot of an attachment with a formatted text

fields

Fields are defined as an array, and hashes contained within it will be displayed in a table inside the message attachment.

  • title

    Shown as a bold heading above the value text. It cannot contain markup and will be escaped for you.

  • value

    The text value of the field. It may contain standard message markup and must be escaped as normal. May be multi-line.

  • short

    An optional flag indicating whether the value is short enough to be displayed side-by-side with other values.

Screenshot of an attachment with some attachment fields

image_url

A valid URL to an image file that will be displayed inside a message attachment. We currently support the following formats: GIF, JPEG, PNG, and BMP.

Large images will be resized to a maximum width of 400px or a maximum height of 500px, while still maintaining the original aspect ratio.

Screenshot of an attachment with a large image

thumb_url

A valid URL to an image file that will be displayed as a thumbnail on the right side of a message attachment. We currently support the following formats: GIF, JPEG, PNG, and BMP.

The thumbnail's longest dimension will be scaled down to 75px while maintaining the aspect ratio of the image. The filesize of the image must also be less than 500 KB.

For best results, please use images that are already 75px by 75px.

Screenshot of an attachment with a thumbnail image

Creating attachment footers

Your message attachments may also contain a subtle footer, which is especially useful when citing content in conjunction with author parameters.

footer

Add some brief text to help contextualize and identify an attachment. Limited to 300 characters, and may be truncated further when displayed to users in environments with limited screen real estate.

Screenshot of rendered footer, footer_icon, and ts fields

Example: "Slack API"

footer_icon

To render a small icon beside your footer text, provide a publicly accessible URL string in the footer_icon field. You must also provide a footer for the field to be recognized.

We'll render what you provide at 16px by 16px. It's best to use an image that is similarly sized.

Example: "https://platform.slack-edge.com/img/default_application_icon.png"

ts (timestamp)

Does your attachment relate to something happening at a specific time?

By providing the ts field with an integer value in "epoch time", the attachment will display an additional timestamp value as part of the attachment's footer.

Use ts when referencing articles or happenings. Your message will have its own timestamp when published.

Example: Providing 123456789 would result in a rendered timestamp of Nov 29th, 1973.

Do you have a Slack app and want your messages to offers users more interactive experiences? Learn about a special kind of attachment, message buttons.


Putting it all together

Using a combination of the provided message attachment parameters, you can create a variety of message layouts to suit your needs. Here are a few examples of what's possible:

Example: Groove

Screenshot of a groove message

{
    "attachments": [
        {
            "fallback": "New ticket from Andrea Lee - Ticket #1943: Can't rest my password - https://groove.hq/path/to/ticket/1943",
            "pretext": "New ticket from Andrea Lee",
            "title": "Ticket #1943: Can't reset my password",
            "title_link": "https://groove.hq/path/to/ticket/1943",
            "text": "Help! I tried to reset my password but nothing happened!",
            "color": "#7CD197"
        }
    ]
}

Try it!

Example: Honeybadger

Screenshot of a honeybadger message

{
    "attachments": [
        {
            "fallback": "ReferenceError - UI is not defined: https://honeybadger.io/path/to/event/",
            "text": "<https://honeybadger.io/path/to/event/|ReferenceError> - UI is not defined",
            "fields": [
                {
                    "title": "Project",
                    "value": "Awesome Project",
                    "short": true
                },
                {
                    "title": "Environment",
                    "value": "production",
                    "short": true
                }
            ],
            "color": "#F35A00"
        }
    ]
}

Try it!

Example: Datadog

Screenshot of a datadog message

{
    "attachments": [
        {
            "fallback": "Network traffic (kb/s): How does this look? @slack-ops - Sent by Julie Dodd - https://datadog.com/path/to/event",
            "title": "Network traffic (kb/s)",
            "title_link": "https://datadog.com/path/to/event",
            "text": "How does this look? @slack-ops - Sent by Julie Dodd",
            "image_url": "https://datadoghq.com/snapshot/path/to/snapshot.png",
            "color": "#764FA5"
        }
    ]
}

Try it!


Attaching buttons to messages

If you're managing workflows with a Slack app that posts messages, you'll want to use buttons to help streamline user interactions.

First interaction with message buttons

Read all about message buttons.

Attaching links to messages

How links unfurl to display summary content

Slack can also automatically create attachments based on the contents of URLs in the message.

Here's how to have some control over what we display to users.

Unfurling

Slack can automatically find URLs in a message and create attachments based on the content of those URLs. We call this functionality "unfurling".

Anatomy of an unfurl

When deciding whether to unfurl a link we consider the type of content that has been linked to. We treat "media" -- that is images, tweets, videos, or audio -- differently to pages that are primarily text-content.

Here are some examples of media content:

While these are examples of text-based content:

By default we unfurl all links in any messages posted by users. For messages posted via incoming webhooks or the chat.postMessage API method, we will unfurl links to media, but not other links.

If you'd like to override these defaults on a per-message basis you can pass unfurl_links or unfurl_media while posting that message. unfurl_links applies to text based content, unfurl_media applies to media based content. These flags are mutually exclusive, the unfurl_links flag has no effect on media content.

There is one notable exception to these rules: we never unfurl links where the label is a complete substring of your URL minus the protocol. This is so a paragraph of text can contain domain names or abbreviated URLs that are treated as a simple reference, and not a link to be unfurled. For example, if a message contains a link to http://example.com with the label example.com then that link will not be unfurled. There are more examples of this rule below.

Note that our servers need to fetch every URL in a message in order to determine what kind of content it references. If you'd like to stop this from happening, set both unfurl_links and unfurl_media to false when posting the message.

Want to know more about unfurling? Find out everything you ever wanted to know about unfurling but were afraid to ask.

Examples

All of these examples are for incoming webhooks, but similar rules apply to our other APIs:

api.slack.com is text-based, so this link will not unfurl:

{
    "text": "<https://api.slack.com>"
}

Passing "unfurl_links": true means the link will unfurl:

{
    "text": "<https://api.slack.com>",
    "unfurl_links": true
}

This xkcd link is an image, so the content will be unfurled by default:

{
    "text": "<http://imgs.xkcd.com/comics/regex_golf.png>"
}

We can then disable that using the unfurl_media flag:

{
    "text": "<http://imgs.xkcd.com/comics/regex_golf.png>",
    "unfurl_media": false
}

Even though unfurl_links is true, this link has a label that matches the URL minus the protocol, so the link will not unfurl:

{
    "text": "<https://api.slack.com|api.slack.com>",
    "unfurl_links": true
}

The label for this link does not match the URL minus the protocol, so this link will unfurl:

{
    "text": "<https://api.slack.com|Slack API>",
    "unfurl_links": true
}