Quickstart
In addition to the Console UI and the Serverless Toolkit, you have the option of directly using the Serverless API to create and manage your Services, Functions, and Assets. This empowers you to create custom build and deployment automations to suit your specific needs.
Warning
Functions and Assets created via Functions(Classic) and Assets(Classic) are not available via the API. Similarly, Functions and Assets created via the API aren't available in the Functions(Classic) and Assets(Classic) interface.
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.
First, we'll create a Service, which serves as our container for the environments we set up.
Warning
The uniqueName will form part of your domain name, so choose carefully.
_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20async function createService() {
_20 const service = await client.serverless.v1.services.create({
_20 friendlyName: "testing",
_20 includeCredentials: true,
_20 console.log(service.sid);
_18 "sid": "ZS00000000000000000000000000000000",
_18 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "friendly_name": "testing",
_18 "unique_name": "demo",
_18 "include_credentials": true,
_18 "ui_editable": false,
_18 "domain_base": "service-unique-1234",
_18 "date_created": "2018-11-10T20:00:00Z",
_18 "date_updated": "2018-11-10T20:00:00Z",
_18 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000",
_18 "environments": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments",
_18 "functions": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Functions",
_18 "assets": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Assets",
_18 "builds": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds"
We'll get back a Service SID, in the format ZSxxx
.
Next, we'll use that Service SID to create a "dev" Environment.
_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21// Find your Account SID and Auth Token at twilio.com/console
_21// and set the environment variables. See http://twil.io/secure
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21async function createEnvironment() {
_21 const environment = await client.serverless.v1
_21 .services("ServiceSid")
_21 .environments.create({
_21 uniqueName: "dev-environment",
_21 console.log(environment.sid);
_18 "sid": "ZE00000000000000000000000000000000",
_18 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "service_sid": "ServiceSid",
_18 "unique_name": "dev-environment",
_18 "domain_suffix": "dev",
_18 "domain_name": "foobar-1234-stage.twil.io",
_18 "custom_domain_name": null,
_18 "date_created": "2018-11-10T20:00:00Z",
_18 "date_updated": "2018-11-10T20:00:00Z",
_18 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000",
_18 "variables": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Variables",
_18 "deployments": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Deployments",
_18 "logs": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Logs"
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.
_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19async function fetchEnvironment() {
_19 const environment = await client.serverless.v1
_19 .services("ServiceSid")
_19 .environments("ZEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19 console.log(environment.domainName);
_18 "sid": "ZEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_18 "service_sid": "ServiceSid",
_18 "build_sid": "ZB00000000000000000000000000000000",
_18 "unique_name": "testing-environment",
_18 "domain_suffix": "testing",
_18 "domain_name": "foobar-1234-testing.twil.io",
_18 "custom_domain_name": null,
_18 "date_created": "2018-11-10T20:00:00Z",
_18 "date_updated": "2018-11-10T20:00:00Z",
_18 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000",
_18 "variables": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Variables",
_18 "deployments": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Deployments",
_18 "logs": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Logs"
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.
_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18async function createFunction() {
_18 const func = await client.serverless.v1
_18 .services("ServiceSid")
_18 .functions.create({ friendlyName: "firstfunc" });
_18 console.log(func.sid);
_12 "sid": "ZH00000000000000000000000000000000",
_12 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_12 "service_sid": "ServiceSid",
_12 "friendly_name": "firstfunc",
_12 "date_created": "2018-11-10T20:00:00Z",
_12 "date_updated": "2018-11-10T20:00:00Z",
_12 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Functions/ZH00000000000000000000000000000000",
_12 "function_versions": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Functions/ZH00000000000000000000000000000000/Versions"
You will get back a Function SID in the format ZHxxx
. Save this Function SID for the next step, where we'll create a Version for this Function.
With a Function created, we're ready to create our first Version. Versions of Functions or Assets are where you add the path, visibility (public, protected or private), and the file content itself.
First, we need some code upload. Let's write a simple Function that decides the fate of the universe:
_10exports.handler = (context, event, callback) => {
_10 const sparedByThanos = Math.random() > 0.5;
_10 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 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 an example below using Node.js.
Remember to replace ZSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
with your Service SID, and ZHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
with the SID of the newly created Function (from this step).
_36const fs = require('fs');
_36// Before running this code, install "form-data" and "axios" using `npm install form-data axios`
_36const FormData = require('form-data');
_36const axios = require('axios');
_36// Provision API Keys at twilio.com/console/runtime/api-keys
_36// and set the environment variables. See http://twil.io/secure
_36const apiKey = process.env.TWILIO_API_KEY;
_36const apiSecret = process.env.TWILIO_API_SECRET;
_36const serviceSid = 'ZSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
_36const functionSid = 'ZHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
_36const serviceUrl = `https://serverless-upload.twilio.com/v1/Services/${serviceSid}`;
_36const uploadUrl = `${serviceUrl}/Functions/${functionSid}/Versions`;
_36const form = new FormData();
_36form.append('Path', '/thanos');
_36form.append('Visibility', 'public');
_36form.append('Content', fs.createReadStream('firstfunc.js'), {
_36 contentType: 'application/javascript',
_36// Create a new Function Version
_36 .post(uploadUrl, form, {
_36 headers: form.getHeaders(),
_36 .then((response) => {
_36 const newVersionSid = response.data.sid;
_36 console.log(newVersionSid);
With the upload complete, you will see a SID logged to your terminal. Save this Version SID for the next step.
Now, we need to create a Build. A Build will compile Function and Asset Versions into a single, deployable package. This build will live in the Twilio cloud, so you just need the Build SID to reference it — there are no files to keep track of.
_20// Download the helper library from https://www.twilio.com/docs/node/install
_20const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_20// Find your Account SID and Auth Token at twilio.com/console
_20// and set the environment variables. See http://twil.io/secure
_20const accountSid = process.env.TWILIO_ACCOUNT_SID;
_20const authToken = process.env.TWILIO_AUTH_TOKEN;
_20const client = twilio(accountSid, authToken);
_20async function createBuild() {
_20 const build = await client.serverless.v1
_20 .services("ServiceSid")
_20 functionVersions: ["ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
_20 console.log(build.sid);
_45 "sid": "ZB00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ServiceSid",
_45 "sid": "ZN00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "asset_sid": "ZH00000000000000000000000000000000",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/asset-path",
_45 "visibility": "PUBLIC"
_45 "function_versions": [
_45 "sid": "ZN00000000000000000000000000000001",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "function_sid": "ZH00000000000000000000000000000001",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/function-path",
_45 "visibility": "PUBLIC"
_45 "name": "@twilio/runtime-handler",
_45 "status": "building",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "date_updated": "2018-11-10T20:00:00Z",
_45 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
_45 "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
You'll receive a result straight away, but note the 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. Here is some sample code to get the current status
of a Build:
_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19async function fetchBuild() {
_19 const build = await client.serverless.v1
_19 .services("ServiceSid")
_19 .builds("ZBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19 console.log(build.status);
_45 "sid": "ZBaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ServiceSid",
_45 "sid": "ZN00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "asset_sid": "ZH00000000000000000000000000000000",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/asset-path",
_45 "visibility": "PUBLIC"
_45 "function_versions": [
_45 "sid": "ZN00000000000000000000000000000001",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "function_sid": "ZH00000000000000000000000000000001",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/function-path",
_45 "visibility": "PUBLIC"
_45 "name": "@twilio/runtime-handler",
_45 "status": "building",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "date_updated": "2018-11-10T20:00:00Z",
_45 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
_45 "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
When the build is completed
, we're ready to deploy!
For the final step, you must associate the Build we just created with the Environment we created earlier in this tutorial. (Remember the Environment SID!) This is called a Deployment.
_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19async function createDeployment() {
_19 const deployment = await client.serverless.v1
_19 .services("ServiceSid")
_19 .environments("ZEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19 .deployments.create();
_19 console.log(deployment.sid);
_10 "sid": "ZD00000000000000000000000000000000",
_10 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "service_sid": "ServiceSid",
_10 "environment_sid": "ZEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10 "build_sid": "ZB00000000000000000000000000000000",
_10 "date_created": "2018-11-10T20:00:00Z",
_10 "date_updated": "2018-11-10T20:00:00Z",
_10 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Deployments/ZD00000000000000000000000000000000"
Your Function will now be live and accessible via URL! You can test it out by going to its URL, such as https://demo-X4HX-dev.twil.io/thanos
(be sure to replace demo-X4HX-dev.twil.io
with the unique domain name for your Environment, which you fetched earlier).
When creating a build, you can also specify any dependencies that your code may have.
To do so, include the dependencies
property, which must be a JSON stringified array of package name
s and version
s.
_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21// Find your Account SID and Auth Token at twilio.com/console
_21// and set the environment variables. See http://twil.io/secure
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21async function createBuild() {
_21 const build = await client.serverless.v1
_21 .services("ServiceSid")
_21 dependencies: JSON.stringify([{ name: "randomcolor", version: "0.5.4" }]),
_21 functionVersions: ["ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
_21 console.log(build.sid);
_45 "sid": "ZB00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ServiceSid",
_45 "sid": "ZN00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "asset_sid": "ZH00000000000000000000000000000000",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/asset-path",
_45 "visibility": "PUBLIC"
_45 "function_versions": [
_45 "sid": "ZN00000000000000000000000000000001",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "function_sid": "ZH00000000000000000000000000000001",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/function-path",
_45 "visibility": "PUBLIC"
_45 "name": "@twilio/runtime-handler",
_45 "status": "building",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "date_updated": "2018-11-10T20:00:00Z",
_45 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
_45 "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
The pattern we used above for uploading Functions is exactly the same as it for Assets.
-
Create an
Asset
-
Create the
Asset Version
via a
POST
request to the
serverless-uploads.twilio.com
domain
-
Include the
AssetVersion
SID(s) we want to be a part of the Build, alongside any
functionVersions
and dependencies we might need.
_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21// Find your Account SID and Auth Token at twilio.com/console
_21// and set the environment variables. See http://twil.io/secure
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21async function createBuild() {
_21 const build = await client.serverless.v1
_21 .services("ServiceSid")
_21 assetVersions: ["ZNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
_21 functionVersions: ["ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
_21 console.log(build.sid);
_45 "sid": "ZB00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ServiceSid",
_45 "sid": "ZN00000000000000000000000000000000",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "asset_sid": "ZH00000000000000000000000000000000",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/asset-path",
_45 "visibility": "PUBLIC"
_45 "function_versions": [
_45 "sid": "ZN00000000000000000000000000000001",
_45 "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_45 "service_sid": "ZS00000000000000000000000000000000",
_45 "function_sid": "ZH00000000000000000000000000000001",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "path": "/function-path",
_45 "visibility": "PUBLIC"
_45 "name": "@twilio/runtime-handler",
_45 "status": "building",
_45 "date_created": "2018-11-10T20:00:00Z",
_45 "date_updated": "2018-11-10T20:00:00Z",
_45 "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
_45 "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
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.