chat.unfurl method
We're still building and not all features are available quite yet. Enjoy this peek into the future!
Not ready for the future? Return to the past at api.slack.com.
Usage info
This method unfurls a link—either in the message composer or in a posted message.
Ensure that the links:write scope is added to your app settings for apps that will be performing app unfurling.
This method supports both granular bot and user tokens. The bot token is recommended.
Both unfurl_id and source must be provided together, or channel and ts must be provided together.
The first time this method is executed with a particular ts and channel (or unfurl_id and source) combination, the valid unfurls attachments you provide will be attached to the message. Subsequent attempts with the same ts and channel values will modify the same attachments, rather than adding more.
The ts value you supply must correspond to a message in the specified channel. Also, the message must contain a fully-qualified URL pointing to a domain that is already registered and associated with your Slack app.
The unfurls parameter expects a URL-encoded string of JSON. Unlike chat.postMessage's attachments parameter, it does not expect a JSON array but instead, a hash keyed on the specific URLs you're offering an unfurl for. Each URL can have a single attachment, including message buttons.
You can define your own preview for a link that you're unfurling inside the message composer by passing the preview field:
"unfurls": {
"https://example.com": {
"blocks": [...],
"preview": {
"title": {
"type": "plain_text",
"text": "custom preview"
},
"icon_url":
"https://images.pexels.com/photos/774731/pexels-photo-774731.jpeg?auto=compress&cs=tinysrgb&dpr=1&w=500"
}
}
}
This preview field is optional, however, if preview and title are not provided, Canvas app unfurls will be unable to render title text. In the absence of preview for uses outside of Canvas, we will generate the preview based on the blocks layout or legacy attachment. If the preview is provided in an unfurl for a posted message, rather than a link inside the message composer, we will simply ignore this property.
Read the unfurling docs for more guidance on this parameter.
For use specifically with a file unfurl, you can set the hide_color field to true to remove the color bar from a message as in the following example:
"unfurls": {
"https://example.com": {
"hide_color": true,
"blocks": [{
"type": "file",
"external_id": "ABCD1",
"source": "remote",
}]
}
}
This property works only with a file block; if this property is included along with other blocks (for example, a section block), this method will throw an error.
The user_auth_required parameter is optional. By providing a 1 or true value, it will require the user posting the link first authenticate themselves with your app. See also the authenticated unfurling docs.
If you'd rather directly point users to a specific page on your server to authenticate, pass a valid URL using the user_auth_url parameter. When sending this parameter via application/x-www-form-urlencoded GETs or POSTs, values must be URL-encoded such that https://example.com/onboarding?user_id=xxx becomes https%3A%2F%2Fexample.com%2Fonboarding%3Fuser_id%3Dxxx.
Or, you can send an ephemeral message to that user by providing a simple string-based user_auth_message value or JSON array of blocks using user_auth_blocks. Simple slack message formatting like *bold*, _italics_, and linking is supported, so you can wrap your custom URLs in a blanket of situationally accurate, actionable text.
user_auth_message offers two default buttons, Not now and Never ask me again which allows your app to prompt a user multiple times before opting out of an install. To make your ephemeral message extra fancy, you can also use user_auth_blocks which will override the default buttons. Using both properties shows the user_auth_message in a notification and the user_auth_blocks in the ephemeral message.
Specifying user_auth_url or user_auth_message will automatically imply user_auth_required being set to true. If both user_auth_url and user_auth_message are provided, user_auth_message takes precedence.
Response
As you can see, we provide a minimal positive response when your unfurl attempt is successful. When it is not, you'll receive one of the errors below and ok will be false.