Announcing the Assets Plugin for the Twilio CLI

Announcing the Assets Plugin for the Twilio CLI

The Twilio CLI is a powerful tool for Twilio developers. Not only does it give you access to all the Twilio APIs from the comfort of your command line, there are advanced features like phone number management, magic webhook tunnels, and the plugin system. CLI plugins extend the functionality of the CLI core and allow you to do things like build and manage Flex plugins, generate access tokens, build with Twilio Functions, and now upload assets to a Twilio Assets service with the Assets Plugin.

In this post I'm going to show you how to use the Assets Plugin and then go into a bit of detail about why we built it.

What is the Assets Plugin?

The Assets Plugin allows you to create an Assets service that you can use as a bucket as a destination for assets, like images or audio files, that you want to upload. You can then use these assets in your Twilio applications. For example, you can upload audio files that you then use in a <Play> verb during a Twilio Voice call, or upload images that you can send to your users via MMS or WhatsApp media messages.

How to use the Assets Plugin

As the Assets Plugin is a Twilio CLI plugin, you will need the Twilio CLI first. If you have Node.js installed, you can install the CLI with:

For more in depth instructions or alternative installation options. check out the Twilio CLI Quickstart.

Once you've installed the CLI make sure to log in to your Twilio account too, with:

Now install the Assets Plugin:

Initialise the plugin

The Assets Plugin has three commands: init, upload and list. The first thing you should do is run the init command.

This will call the Twilio Functions and Assets API to create a new service and store the details about that service so that we can use it later. This service will be used by the plugin as a bucket where you can upload and access your assets.

Upload an asset

Now we have initialised the plugin, we can upload our first asset.

When the asset has been uploaded the details will be displayed, including the asset's URL. You can now open that URL in a browser and see or download the asset.

Upload protected assets

If you want to use your assets during a Twilio Voice call, but you don't want just anyone to access them, you can upload them as protected assets. Protected assets will only respond to requests that are signed with an X-Twilio-Signature header, as all Twilio webhooks are. You can upload a protected asset using the --protected flag.

List your assets

The final command for this version of the plugin is a way to list all the assets you have uploaded to your bucket. Run it with:

You will see a table showing the details of all the assets you have uploaded to your service so far, including SIDs, URLs, and the visibility. As this is a Twilio CLI plugin you can show the properties of your choice by passing them to the command:

Or you can output all the properties as JSON:

That is the current functionality of the plugin. If there is more you wished it could do, please post ideas to this issue in the Twilio Serverless Toolkit repo. If you want to build features yourself, pull requests are welcome!

Why do you need the Assets Plugin?

The Assets Plugin seeks to abstract away the Twilio Functions and Assets API to make it simple to upload and use a static asset.

The Twilio Functions and Assets service are really useful for building applications in which you create a collection of functions and assets that you bundle together and deploy as a complete application. The API has the concept of:

• services which encapsulate everything I'm about to describe
• environments which allow you to deploy your applications to separate subdomains for testing or production
• function and asset resources
• function versions and asset versions which contain the content for a function or asset
• variables which you can access in your functions
• builds which are bundles of functions, assets and variables, along with npm dependencies
• and deployments, which is the combination of a build and an environment that puts the functions and assets in a build live in that environment

These provide a powerful basis for tooling and integrations to build on top of Twilio Functions and Assets, but the chances are that you don't want to interact with these APIs directly when you are building a regular application on Twilio. The Twilio Serverless Toolkit is built on top of these APIs and is recommended if you want to build and deploy an application to the Twilio runtime. As a tool it gives you commands that abstract the process of uploading content, creating a build and deploying that build to an environment.

The Assets Plugin seeks to abstract even more of this away to make it easy to treat an Assets Service as a bucket for content. When uploading an asset, you don't need functions or variables and you don't need to know that in the background you are creating a new asset, uploading the content to a new asset version, collecting all the assets in the service in a new build and deploying that build to an environment, but that is what twilio assets:upload FILE is doing behind the scenes. The plugin abstracts it all away so that you can upload an asset with a single command.

When should you not use the Asset Plugin?

If you are building a Flex plugin, it is not recommended to use the Assets Plugin to upload assets for your plugin. Instead you should build and release your plugin using the Flex Plugins CLI.

Please use the plugin and send in your feedback

That's the new Assets Plugin; use it to upload your static assets to Twilio's infrastructure from your terminal. Then you can use your assets in your Twilio applications or just to share access to an image. Here's an example of how to use the Assets Plugin to store audio files you can then use in a Studio IVR.

The Assets Plugin is open source and part of the Twilio Serverless Toolkit and you can check out all the code here on GitHub. If you have bug reports or feature requests, please open an issue or send in a pull request. And if you have any other feedback, just drop me an email at philnash@twilio.com.