Skip to content
This repository has been archived by the owner on Nov 27, 2023. It is now read-only.

Latest commit

 

History

History
73 lines (53 loc) · 3.5 KB

page_unfurling.md

File metadata and controls

73 lines (53 loc) · 3.5 KB
Raw

Unfurling

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

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

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

Custom Attachments

If you'd like more control over the format of the attachments, you can create a custom attachment when posting a message to Slack. Our attachments documentation gives more details on the available options.