Slack Video Block: Which URLs Work, Tested With Real Errors

A Slack video block is a Block Kit block of "type": "video" that plays an embedded video player inside a message, modal or App Home. It needs four fields, video_url, thumbnail_url, title and alt_text, and Slack only accepts a video_url on a domain your app has claimed as an unfurl domain. On 7 November 2026 we made 26 test posts from an app on a Free workspace. One case surprised us: a YouTube /embed/ URL worked with no domain set up at all, while a normal YouTube watch link failed. Everything below comes from those posts, with the exact error text Slack sent back.

A video block that works

This is the block that posted and played, sent with chat.postMessage and a bot token:

{
  "type": "video",
  "title": { "type": "plain_text", "text": "Big Buck Bunny (Blender open movie)" },
  "title_url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
  "description": { "type": "plain_text", "text": "Posted by a bot with a Block Kit video block" },
  "video_url": "https://www.youtube.com/embed/aqz-KE-bpKQ?autoplay=1",
  "thumbnail_url": "https://i.ytimg.com/vi/aqz-KE-bpKQ/hqdefault.jpg",
  "alt_text": "Big Buck Bunny trailer",
  "provider_name": "YouTube",
  "author_name": "Blender"
}

Slack shows the thumbnail with a Video button. provider_name and author_name become the grey "YouTube | Blender" line, description sits under it, and title_url turns the title into a link:

Clicking the thumbnail played the video inline, in the message itself. The player is an iframe whose source is https://slack-files.com/video_embed?url= followed by your encoded video_url, so Slack wraps your player page rather than linking out:

The thumbnail is not checked against the video. In our first test we paired one YouTube video with a different video's thumbnail, and Slack posted it and showed the wrong image. Pick the thumbnail yourself.

Which video URLs Slack accepted

Same bot, same channel, no unfurl domains in the app at first:

So YouTube's /embed/ path is the only form that worked out of the box. The watch, short-link and Shorts URLs of the same video were refused, which is why copying a link from the browser bar fails. Use https://www.youtube.com/embed/VIDEO_ID. A raw .mp4 is refused too: video_url must be a page that plays the video, not the file.

Missing fields and limits

Each of these returned invalid_blocks with a JSON pointer to the problem:

Our page on the invalid_blocks error explains how to read these pointers when a message has many blocks.

Videos from Vimeo, Loom or your own site

For any host other than YouTube's embed path, the app must claim the domain. Adding unfurl_domains to the manifest was not enough on its own. Slack rejected our first manifest with two errors: Unfurl Domains requires links:read bot scope and Unfurl Domains requires link_shared bot event subscription, which also needs a request URL that answers Slack's challenge. The manifest section that passed:

"features": { "unfurl_domains": ["vimeo.com", "loom.com"] },
"oauth_config": { "scopes": { "bot": ["chat:write", "links:read", "links.embed:write"] } },
"settings": {
  "event_subscriptions": {
    "request_url": "https://example.com/slack/events",
    "bot_events": ["link_shared"]
  }
}

After apps.manifest.update saved it, the Vimeo and Loom URLs still failed with the same "not a valid unfurl domain" error. They posted only after we reinstalled the app to the workspace. If you add a domain and nothing changes, reinstall. The app setup itself is the same as for link unfurling, which uses the same domain list.

Webhooks and other surfaces

An incoming webhook accepted the same YouTube embed block and answered ok, so you do not need a bot token to post a video. Slack's docs list the video block for messages, modals and App Home. We tested messages only. To try a layout before writing code, paste the JSON above into the Block Kit Builder.

FAQ

Why does my YouTube link fail in a video block?

Most likely it is a watch link (youtube.com/watch?v=), a youtu.be link or a Shorts link. In our test only youtube.com/embed/VIDEO_ID passed without claimed domains. Take the video ID and build the embed URL.

Can a video block play an MP4 file?

No. A direct .mp4 URL got the "not a valid unfurl domain" error. To show a video file, upload it as a file instead; our page on video formats Slack plays covers what plays inline.

Does the video block need the links.embed:write scope?

Slack's reference lists links.embed:write for apps that post video blocks. Our app had it in every test, so we did not see what happens without it.