Sample - Slack Web API
POST/chat.unfurl

Configure custom link unfurls

Submits custom unfurl behavior for URLs in a user-posted message. Supply the target channel and message ts, then provide URL mappings through unfurls or authentication guidance through the user-authentication fields. The request requires an authentication token with the links:write scope.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 6 body fields
tokenstringrequired
Authentication token with the `links:write` scope.

Required unfurl configuration containing the target message and optional custom unfurl or user-authentication instructions.

channelstringrequired
Channel ID of the message
tsstringrequired
Timestamp of the message to add unfurl behavior to.
unfurlsstringoptional
URL-encoded JSON map with keys set to URLs featured in the the message, pointing to their unfurl blocks or message attachments.
user_auth_messagestringoptional
Provide a simply-formatted string to send as an ephemeral message to the user as invitation to authenticate further and enable full unfurling behavior
user_auth_requiredbooleanoptional
Set to `true` or `1` to indicate the user must install your Slack app to trigger unfurls for this domain
user_auth_urlstringoptional
Send users to this custom URL where they will complete authentication in your app to fully trigger unfurling. Value should be properly URL-encoded.

2 status codes
200Confirms that the custom unfurl behavior was submitted successfully.
okbooleanrequired
Allowed:true
defaultReturned when the URL cannot be unfurled, the target service cannot be found, required unfurl data is missing, or authentication is not valid.
callstackstringoptional
Note: PHP callstack is only visible in dev/qa
errorstringrequired
Allowed:cannot_unfurl_urlcannot_find_servicemissing_unfurlscannot_promptnot_authedinvalid_authaccount_inactivetoken_revokedno_permissionorg_login_requireduser_is_botinvalid_arg_name
okbooleanrequired
Allowed:false

Error handling

channel and ts are required and must identify the message whose unfurl behavior you are configuring. When supplied, unfurls must be a URL-encoded JSON map, and user_auth_url must be properly URL-encoded.