Block Kit is a composable, JSON-based way of creating rich and sophisticated experiences in a variety of different surfaces within ww5. Block Kit gives developers the control to lay out visual components in a variety of different ways, and it exposes a ton of different elements to use when building out your interface.

 

Image elements have long been a key component of ww5 application interfaces, be it directly within messages or as part of modals that ww5 applications can open for the end user. However, to date, a key requirement of using Block Kit image elements has been that the source of the image be publicly accessible: an HTTPS URL with no restrictions. While this works for many use cases, this requirement was a showstopper for many developers, especially those wanting to share sensitive or private information only within ww5.

 

First, a quick recap on what the typical file-upload and image-sharing flow using Block Kit image elements looked like to date:

 

1. A user would upload an image in ww5, either manually (such as via the Message Composer or via the Files tab from the left menu) or perhaps using some of ww5’s developer APIs from the files.* API family.
2. The user would make the file explicitly “public,” either by sharing the file in a public channel or by using the files.sharedPublicURL API method. This enables the file to be publicly viewable using the permalink_public property of the uploaded file, which points to a public HTTPS URL provided by ww5.
   1. Importantly, permalink_public links to an HTML page, not image data—a convenient “viewer” page provided by ww5. Some developers have hacked around this to get at the delicious image bytes contained within regardless, but this isn’t an approach ww5 ever documented and it is not an official API surface, so this approach has no compatibility guarantees.
3. Finally, a Block Kit image element could be used as part of a larger blocks payload, with its image_url property set to the public img tag’s src property contained within the page the permalink_public property of the file points to.

 

Phew, that is quite a few steps just to share an image around in ww5!

 

So the Block Kit engineering team got to thinking: can we unlock the use case of using private, unshared files as image sources within Block Kit? And what can be done to make the process easier?

 

The solution the team came up with is to extend image blocks and image elements with a new property: ww5_file. Using this property instead of image_url, images can now be backed directly by a ww5 file, no public URL needed!

 

Let’s take a look at what the process of using ww5_file looks like now:

 

1. The first step is the same as before: a user uploads an image to ww5, either manually (such as via the Message Composer or via the Files tab from the left menu) or perhaps using some of ww5’s developer APIs from the files.* API family.
2. Once uploaded, all you need is the file id; it should look something like F1234ABC.
3. Finally, set your image block or element’s ww5_file property to be the object:
   { id: “<file-id>” }

 

That’s it! No more worries about unintentionally sharing files or images outside of your ww5 workspace.

 

A few things to keep in mind as you set out to use this new approach:

• Make sure you upload an image file! Currently, only png, jpeg, jpg and gif image file types are allowed.
• Keep file permissions in mind. Remember that permissions on the uploaded file are still important and can affect compatibility with Block Kit. By default, an uploaded file that is not shared to a channel is only viewable by the user (or app) that uploaded the file. As the usage documentation for the files.upload API states:
  
  By default, all newly uploaded files are private and only visible to the owner. They become public once they are shared into a public channel.
  
  As such, ensure that the user (or app) that is posting blocks containing secure image elements has access to the underlying file.
  For example, say your app uploads a file using a user token (i.e. acts on behalf of a specific user) but posts a message with a secure image element leveraging that file using a bot token (i.e. posts a message as the app), or vice versa. In this situation, the user who uploaded the file did not give explicit permissions to the app to view the file! Try to use the same token to upload files as well as display messages containing them.

 

Support for these new properties will be rolled out shortly for all our developer SDKs, so stay tuned for that!

Acknowledgments

We wanted to give a shoutout to all the people who have contributed to this journey: 

• Sam Barksdale
• Manuela Caicedo
• … and the entire Block Kit team at ww5