Quickstart

A quick public service announcement

We now have an API for managing Functions & Asset deployment. Functions & Assets created via the existing UI continue to work as normal, but are not available via the API. And vice versa: Functions & Assets created via the API aren't available in the existing editor UIs.

Quickest possible start:

If you want to quickly deploy some functions/assets from the command line, you can do so with our CLI and a plugin we've written:

npm install twilio-cli -g
twilio plugins:install @twilio-labs/plugin-serverless
twilio login
twilio serverless:init example
cd example
twilio serverless:start
<do awesome code>
twilio serverless:deploy

Another cool thing to try after init:
twilio serverless:new 
 -- gives you a templated function with code pre-written!

To learn more, visit the Serverless Toolkit documentation. If you are having trouble installing the CLI, check out the CLI docs.

If you want to work through the underlying API (for example if you want to write your own deployment tools), keep following this quickstart.

Get an overview of the API and the Serverless Toolkit by watching our overview video from Twilio Signal 2019:

Great. Let's have a look at how to deploy a single function via the API.

Deploying a single function

Create a Service

First, we'll create a Service, which serves as our container for the environments we set up.

We'll get back a Service SID, in the format ZSxxx.

Create an Environment

We'll use that Service SID, to create a "dev" Environment next.

This will give us an empty environment, e.g. demo-X4HX-dev.twil.io. To see the domain name for your environment, you can fetch your environment using the ZExxx SID output from the prior code sample.

Create a Function

Now let's create our Function. We create the Function at the service level, not inside a particular environment (we'll deploy our function to an environment later on). Also, we only set the name for the function at this step. We'll choose a path, visibility, and upload the code for the function in later steps.

Save the Function SID for the next step where we create a Version.

With a Function created, we're ready to create our first Version. Versions of Functions or Assets are where you add the path, visibilty (public, protected or private), and the file content itself. Versions are created at a different URL to allow uploading the file content.

First, we need a function file to upload. Lets write a simple function that decides the fate of the universe:

exports.handler = function(context, event, callback) {
  const sparedByThanos = Math.random() > 0.5;

  callback(null, {
    sparedByThanos,
    quote: 'You should have gone for the head.'
  });
};

Now we have a function worth uploading. Save this as a file on your computer named firstfunc.js.

Now we can actually upload that file. The create API action is not currently represented in the helper libraries, so you have to do a manual file upload in the language of your choice. See examples below.

With that upload complete, save the resulting SID for the newly created Version.

Create a Build

Now, we need to to create a Build. A Build will compile Function and Asset Versions into a single, deployable package. It lives in the Twilio cloud, so you just need the Build SID to reference it -- there's no files to keep track of.

You'll receive a return straight away, but note that there's a status property. We need to wait until the status returns completed before continuing. The best way to handle the status changes is to poll every second or two:

When we have a completed build, we're ready to deploy.

Create a Deployment

Let's do the final step, associating the Build we just did with the Environment we created at the start of our tutorial. This is called a Deployment.

Your function is now live! You can test it out by going to a URL like https://demo-X4HX-dev.twil.io/thanos (be sure to replace demo-X4HX-dev.twil.io with the unique domain name for your Environment, created above).

Adding dependencies

We can specify dependencies when creating a build.

Handling Asset uploads

The pattern we used above for uploading Functions is exactly the same as it for Assets. We create an /Asset, we create the /Assets/[AssetSid]/Versions via a POST to the serverless-uploads.twilio.com domain, and then we add the "AssetVersions" we want to include in the Build alongside FunctionVersions and any dependencies we might need.

What's next?

Definitely take a look at the API reference section for all of the API resources below. You might be particularly interested in Variables to allow setting environment variables for a given Environment.

• Service
• Environment
• Function
• Function Version
• Asset
• Asset Version
• Variable
• Build
• Deployment