getting-started

Getting Started with Twilio Serverless

Guide for scaffolding a new Twilio serverless project from an empty directory to first deploy.

Prerequisites

• Node.js 18+
• Twilio account with Account SID and Auth Token
• Twilio CLI: npm install -g twilio-cli
• Serverless plugin: twilio plugins:install @twilio-labs/plugin-serverless

Project Setup

1. Initialize

mkdir my-twilio-project && cd my-twilio-project
npm init -y
npm install twilio @twilio-labs/serverless-runtime-types

2. Create Directory Structure

my-twilio-project/
├── functions/          # Serverless functions (auto-routed as endpoints)
│   └── hello.js        # → /hello endpoint
├── assets/             # Static files (HTML, audio, images)
├── .env                # Environment variables (never commit)
├── .twiliodeployinfo   # Deploy state (auto-generated, gitignore)
└── package.json

3. Create .env

# Required for deployment (twilio-run reads these WITHOUT the TWILIO_ prefix)
ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AUTH_TOKEN=your-auth-token

# Also set prefixed versions for your function code
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_PHONE_NUMBER=+1xxxxxxxxxx

Important: twilio-run (the serverless runtime) reads ACCOUNT_SID and AUTH_TOKEN without the TWILIO_ prefix. If you only have TWILIO_ACCOUNT_SID, deployment fails with "Missing Credentials". Add both versions.

4. Create First Function

// functions/hello.js
// ABOUTME: Simple hello world endpoint for testing deployment
// ABOUTME: Returns JSON greeting — verifies serverless runtime is working

exports.handler = function (context, event, callback) {
  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.say({ voice: 'Google.en-US-Neural2-F' }, 'Hello from Twilio!');
  callback(null, twiml);
};

5. Add Scripts to package.json

{
  "scripts": {
    "start": "twilio serverless:start --live",
    "start:ngrok": "twilio serverless:start --ngrok --live --detailed-logs",
    "deploy:dev": "twilio serverless:deploy --runtime node22",
    "deploy:prod": "twilio serverless:deploy --production --runtime node22"
  }
}