Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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:

Cool, I really do want to learn the underlying API!

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.

The UniqueName will form part of your domain name, so choose carefully.

        
        
        
        

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

        OK, I have the SID, what's next?

        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.

                    
                    
                    
                    
                    OK, got an Environment. Now what?

                    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.

                          Done. Let's keep going.

                          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.

                          That's ominous. OK, what now?

                          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.

                                This is a lot of SIDs. OK, next...

                                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.

                                            Yes! I'm 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).

                                                  That's great! Anything else I should know?

                                                  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.

                                                              Rate this page:

                                                              Need some help?

                                                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.