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?

General Usage

This is a Twilio Labs project

This means this project is 100% open-source. You can find its source code in the Twilio Labs GitHub organization.

We currently don't support the projects through our official support channels. But you are welcome to reach out to us on GitHub for any questions, issues or suggestions or to contribute to this project.

Learn more about Twilio Labs.

There are two ways you can use the toolkit. If you are already using the Twilio CLI, you can install it via a plugin. Alternatively, you can use the toolkit as a standalone using twilio-run via npm or another Node.js package manager.

Throughout the docs we'll reference the Twilio CLI commands.

Create a Project

There's a variety of ways you can get started with a Twilio Serverless project. If you are intending to use the Twilio Serverless Toolkit, you'll have to have a project that adheres to a certain structure (more below). The toolkit actually supports scaffolding projects to get some example Functions and the right folder structure.


        Project Structure

        By default the Twilio Serverless Toolkit uses the filesystem structure of your project to make conclusions of what to do. If you use the toolkit to create your project, you'll already have a valid structure like this:

        ├── .env
        ├── .gitignore
        ├── .nvmrc
        ├── assets
        ├── functions
        │   └── example.js
        ├── package-lock.json
        └── package.json

        Project Dependencies

        Anything that will be found in the dependencies field of your package.json in your project directory will be available both for local development as well as installed in your deployed project.

        You can add new dependencies by using any Node.js package manager that writes to the package.json like npm to install dependencies.

        Dependencies that are installed locally but are not under dependencies, like anything installed as devDependencies, might be available during local development but will not be available during deployment. The deploy command will list all dependencies that are being installed upon deployment.

        Environment Variables

        We use .env files for all environment variables. By default we will not make any other environment variables available for your local development. We'll use the same file to determine the values that should be uploaded for deployment. You can change the location of your .env file using the --env flag. For example: --env=./.env.staging

        Learn more about .env files:


        All Functions have to be under a common root directory. By default this will be functions/ but you can alternatively use src/. If neither of them works, there's a flag --functions-folder that you can use to specify a different directory as the root directory for your Functions.

        Anything under that root directory will be uploaded as a Twilio Function. The path for each function is relative to the root directory with the .js strapped away.

        For example a functions/ directory like this:

        ├── functions
        │   ├── example.js
        │   └── sms
        │       └── reply.js

        Would result in two Functions being created at the paths /example and /sms/reply.

        If you would deploy these files both of these Functions would be publicly accessible. If you want to lock them down to only be accessible by Twilio, for example to use them as a webhook, you can mark a Function as protected. This can be done renaming your file to have an extension of .protected.js.

        Note: This will not influence the path of the Function. Meaning a file functions/example.js and functions/example.protected.js will both result in a path of /example but the second one will make sure to enforce a valid Twilio request signature.


        Creating Assets works similar to creating Functions. By default the toolkit will look for an assets/ or alternatively static/ folder. With the --assets-folder flag you can change this directory to any other root directory.

        However, Assets will preserve their extensions for the path. So for example a file under assets/index.html would result in a path of /index.html.

        Assets are a great way for you to also host resources that you want to access from your Functions that are not other Functions or should not be available to the public. For example configuration files or other JavaScript files you want to require(). You can store those as private Assets.

        To mark an Asset as private, include .private. in the filename. This will create a private Asset but the .private. annotation will be removed during upload. In order to accessing a private asset you'll have to use the global Runtime.getAssets() function. You can learn more about it in the Runtime documentation.

        Start developing locally

        The Twilio Serverless Toolkit allows you to develop locally to test out your Functions and Assets before deploying them to Twilio. It also allows you to attach a debugger to debug your Function logic or even spin up an ngrok tunnel to test your Functions directly with Twilio.

        There's a variety of options that you can use when kicking off the local development command but the quick way to get started is to run it without any arguments.


              Create a new Twilio Function

              Since any JavaScript file inside your functions directory of your project will turn into a Function, creating a new Twilio Function can be as quick as creating a new file with this content:

              exports.handler = function(context, event, callback) {
                const twiml = new Twilio.twiml.VoiceResponse();
                twiml.say("Hello World!");
                callback(null, twiml);

              If you want to learn more about the different variables passed into this Function during the execution or other things that will be available during the exection, make sure to check out the documentation of the Twilio Function Runtime.

              To make creating a new Twilio Function more convenient and get you started quicker, we added another command that lets you create a new Function and pick from a collection of existing templates.


                    These templates are dynamically loaded from our Function Templates repository on GitHub and we always welcome new contributions.

                    If you want to see a list of available templates with a short description directly in you terminal, you can use the serverless:list-templates command to list all templates.


                          Deploy a project

                          Once you have your project setup, you are just one command away from deploying your Twilio Serverless project. To make this as easy as possible, the deploy command will set some defaults based on your filesystem:

                          • The toolkit will create a Twilio Serverless service for you. By default it will read the name entry in your package.json. You can use the --service-name flag to override this name
                          • Twilio Serverless introduces the concept of Environments. By default the toolkit will deploy to an environment with the domain suffix dev and the name dev-environment. This can be changed through the --environment flag.
                          • The toolkit will upload all variables set in your .env file for your deployment. You can change it to use a different .env file using the --env flag.
                          • Any dependency that is listed in the dependencies field in your package.json will automatically be installed in your deployment.

                                What's next?

                                Now that you were able to deploy your first Twilio Serverless project, it's time to learn more about some of the other options that you have.

                                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.