Server-side quickstart for Programmable Voice

This quickstart shows you how to build a server-side application that makes and receives phone calls. The code in this quickstart makes an outbound call with the Twilio Voice API and it handles an inbound call with text-to-speech.

Complete the prerequisites

Select your programming language and complete the prerequisites:

PythonNode.jsPHPC#/.NETJavaGoRuby

Install Python 3.3 or later.
Install and set up ngrok.
Install Flask and Twilio's Python helper library. To install using pip, run:
pip install flask twilio
Create a Twilio account.
Buy a voice-enabled phone number.

Install Node.js 14 or later.
Install and set up ngrok.
Install Express and the Twilio Node.js helper library:
npm install twilio express
Create a Twilio account.
Buy a voice-enabled phone number.

Install PHP 7.2 or later.
Install and set up ngrok.
Install dependencies with Composer:
1. Install Composer globally.
2. Install the Twilio PHP helper library:
  composer require twilio/sdk
Create a Twilio account.
Buy a voice-enabled phone number.

Set environment variables

Follow these steps to get your Twilio account credentials and set them as environment variables.

macOS TerminalWindows command linePowerShell

Go to the Twilio Console.
Copy your Account SID and set it as an environment variable using the following command. Replace YOUR_ACCOUNT_SID with your actual Account SID.
export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
Copy your Auth Token and set it as an environment variable using the following command. Replace YOUR_AUTH_TOKEN with your actual Auth Token.
export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN

Go to the Twilio Console.
Copy your Account SID and set it as an environment variable using the following command. Replace YOUR_ACCOUNT_SID with your actual Account SID.
set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID
Copy your Auth Token and set it as an environment variable using the following command. Replace YOUR_AUTH_TOKEN with your actual Auth Token.
set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN

Go to the Twilio Console.
Copy your Account SID and set it as an environment variable using the following command. Replace YOUR_ACCOUNT_SID with your actual Account SID.
$Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
Copy your Auth Token and set it as an environment variable using the following command. Replace YOUR_AUTH_TOKEN with your actual Auth Token.
$Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN"

Make an outgoing phone call

Follow these steps to make a phone call from your Twilio number.

PythonNode.jsPHPC#/.NETJavaGoRuby

Create a file named make_call.py and add the following code:
Make a phone call using Twilio
1
# Download the helper library from https://www.twilio.com/docs/python/install
2
import os
3
from twilio.rest import Client
4

5
# Find your Account SID and Auth Token at twilio.com/console
6
# and set the environment variables. See http://twil.io/secure
7
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
8
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
9
client = Client(account_sid, auth_token)
10

11
call = client.calls.create(
12
url="http://demo.twilio.com/docs/voice.xml",
13
to="+18005550100",
14
from_="+18005550199",
15
)
16

17
print(call.sid)
Replace the from_ phone number with your Twilio number.
Replace the to phone number with your own phone number.
Save your changes.
Run the script:
python make_call.py
Your phone rings and you hear the short message in the TwiML document that your script links to.

Create a file named make_call.js in the folder where you installed Express and the Twilio helper library.

Add the following code to make_call.js:

Make an outbound call

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createCall() {
11  const call = await client.calls.create({
12    from: "+18005550199",
13    to: "+18005550100",
14    url: "http://demo.twilio.com/docs/voice.xml",
15  });
16
17  console.log(call.sid);
18}
19
20createCall();

Replace the from phone number with your Twilio number.
Replace the to phone number with your own phone number.
Save your changes.
Run the script:
node make_call.js
Your phone rings and you hear the short message in the TwiML document that your script links to.

Create a file named make_call.php in the folder where you installed the Twilio helper library.

Add the following code to make_call.php:

Make a phone call using Twilio

1<?php
2
3// Update the path below to your autoload.php,
4// see https://getcomposer.org/doc/01-basic-usage.md
5require_once "/path/to/vendor/autoload.php";
6
7use Twilio\Rest\Client;
8
9// Find your Account SID and Auth Token at twilio.com/console
10// and set the environment variables. See http://twil.io/secure
11$sid = getenv("TWILIO_ACCOUNT_SID");
12$token = getenv("TWILIO_AUTH_TOKEN");
13$twilio = new Client($sid, $token);
14
15$call = $twilio->calls->create(
16    "+18005550100", // To
17    "+18005550199", // From
18    ["url" => "http://demo.twilio.com/docs/voice.xml"]
19);
20
21print $call->sid;

Update line 5 of make_call.php to require __DIR__ . '/vendor/autoload.php';
Replace the first argument to $twilio->messages->create() with your own phone number.
Replace the second argument to $twilio->messages->create() with your Twilio phone number.
Save your changes.
Run the script:
php make_call.php
Your phone rings and you hear the short message in the TwiML document that your script links to.

Create a directory for this project:
mkdir voice-quickstart
Open that directory in the terminal:
cd voice-quickstart
Initialize your app:
dotnet new web
Install the Twilio .NET helper library:
dotnet add package Twilio

Replace the contents of Program.cs with the following code:

Make a phone call using Twilio

1// Install the C# / .NET helper library from twilio.com/docs/csharp/install
2
3using System;
4using Twilio;
5using Twilio.Rest.Api.V2010.Account;
6using System.Threading.Tasks;
7
8class Program {
9    public static async Task Main(string[] args) {
10        // Find your Account SID and Auth Token at twilio.com/console
11        // and set the environment variables. See http://twil.io/secure
12        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
13        string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
14
15        TwilioClient.Init(accountSid, authToken);
16
17        var call = await CallResource.CreateAsync(
18            url: new Uri("http://demo.twilio.com/docs/voice.xml"),
19            to: new Twilio.Types.PhoneNumber("+18005550100"),
20            from: new Twilio.Types.PhoneNumber("+18005550199"));
21
22        Console.WriteLine(call.Sid);
23    }
24}

Replace the from phone number with your Twilio number.
Replace the to phone number with your own phone number.
Save your changes.
Run the app:
dotnet run
Your phone rings and you hear the short message in the TwiML document that your script links to.

Create a folder for this project:
mkdir voice-quickstart
Go to the project folder:
cd voice-quickstart

Initialize the app:

gradle init --type basic --dsl groovy --use-defaults

Create folders for the project code:
mkdir -p src/main/java
Replace the contents of the build.gradle file with the following code:
1
plugins {
2
id 'java'
3
id 'application'
4
}
5

6
application {
7
mainClass = 'Example'
8
}
9

10
repositories {
11
mavenCentral()
12
}
13

14
dependencies {
15
implementation 'com.twilio.sdk:twilio:10.5.2'
16
implementation 'org.slf4j:slf4j-simple:2.0.16'
17
implementation 'com.sparkjava:spark-core:2.9.4'
18
}
Save the file.

Create a file named Example.java in src/main/java and add the following code:

Make a phone call using Twilio

1// Install the Java helper library from twilio.com/docs/java/install
2
3import java.net.URI;
4import com.twilio.Twilio;
5import com.twilio.rest.api.v2010.account.Call;
6
7public class Example {
8    // Find your Account SID and Auth Token at twilio.com/console
9    // and set the environment variables. See http://twil.io/secure
10    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");
11    public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN");
12
13    public static void main(String[] args) {
14        Twilio.init(ACCOUNT_SID, AUTH_TOKEN);
15        Call call = Call.creator(new com.twilio.type.PhoneNumber("+18005550100"),
16                            new com.twilio.type.PhoneNumber("+18005550199"),
17                            URI.create("http://demo.twilio.com/docs/voice.xml"))
18                        .create();
19
20        System.out.println(call.getSid());
21    }
22}

Replace +18005550199 with your Twilio phone number.
Replace +18005550100 with your own phone number.
Save your changes.
Run the app:
gradle run
Your phone rings and you hear the short message in the TwiML document that your script links to.

Create a folder for this project:
mkdir voice-quickstart
Go to the folder:
cd voice-quickstart
Create a Go module:
go mod init voice-quickstart

Create a file named make_call.go and add the following code:

Make a phone call using Twilio

1// Download the helper library from https://www.twilio.com/docs/go/install
2package main
3
4import (
5	"fmt"
6	"github.com/twilio/twilio-go"
7	api "github.com/twilio/twilio-go/rest/api/v2010"
8	"os"
9)
10
11func main() {
12	// Find your Account SID and Auth Token at twilio.com/console
13	// and set the environment variables. See http://twil.io/secure
14	// Make sure TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN exists in your environment
15	client := twilio.NewRestClient()
16
17	params := &api.CreateCallParams{}
18	params.SetUrl("http://demo.twilio.com/docs/voice.xml")
19	params.SetTo("+18005550100")
20	params.SetFrom("+18005550199")
21
22	resp, err := client.Api.CreateCall(params)
23	if err != nil {
24		fmt.Println(err.Error())
25		os.Exit(1)
26	} else {
27		if resp.Sid != nil {
28			fmt.Println(*resp.Sid)
29		} else {
30			fmt.Println(resp.Sid)
31		}
32	}
33}

Replace the from phone number with your Twilio number.
Replace the to phone number with your own phone number.
Save your changes.
Install dependencies:
go get
Run the script:
go run make_call.go
Your phone rings and you hear the short message in the TwiML document that your script links to.

Create a Gemfile:
bundle init
Install Sinatra and other project dependencies:
bundle add puma twilio-ruby sinatra

Create a file named make_call.rb and add the following code:

Make a phone call using Twilio

1# Download the helper library from https://www.twilio.com/docs/ruby/install
2require 'rubygems'
3require 'twilio-ruby'
4
5# Find your Account SID and Auth Token at twilio.com/console
6# and set the environment variables. See http://twil.io/secure
7account_sid = ENV['TWILIO_ACCOUNT_SID']
8auth_token = ENV['TWILIO_AUTH_TOKEN']
9@client = Twilio::REST::Client.new(account_sid, auth_token)
10
11call = @client
12       .api
13       .v2010
14       .calls
15       .create(
16         url: 'http://demo.twilio.com/docs/voice.xml',
17         to: '+18005550100',
18         from: '+18005550199'
19       )
20
21puts call.sid

Replace the from phone number with your Twilio number.
Replace the to phone number with your own phone number.
Save your changes.
Run the script:
ruby make_call.rb
Your phone rings and you hear the short message in the TwiML document that your script links to.

Receive a phone call with your Twilio number

Follow these steps to receive a phone call with your Twilio number and respond using text-to-speech.

PythonNode.jsPHPC#/.NETJavaGoRuby

Create a file named answer_phone.py and add the following code:

Generate TwiML to Say a message

1from flask import Flask
2from twilio.twiml.voice_response import VoiceResponse
3
4app = Flask(__name__)
5
6
7@app.route("/", methods=['GET', 'POST'])
8def hello_monkey():
9    """Respond to incoming calls with a simple text message."""
10
11    resp = VoiceResponse()
12    resp.say("Hello from your pals at Twilio! Have fun.")
13    return str(resp)
14
15
16if __name__ == "__main__":
17    app.run(debug=True)

Save the file.
In a new terminal window, run the following command to start the Python development server:
python answer_phone.py
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 5000
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Paste your ngrok public URL in the URL field. For example, if your ngrok console shows Forwarding https://1aaa-123-45-678-910.ngrok-free.app, enter https://1aaa-123-45-678-910.ngrok-free.app.
6. Click Save configuration.
With the Python development server and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in answer_phone.py.

Create a file named answer_phone.js in the same folder as make_call.js and add the following code:

Generate TwiML to Say a message

1const express = require('express');
2const VoiceResponse = require('twilio').twiml.VoiceResponse;
3
4const app = express();
5
6// Create a route that will handle Twilio webhook requests, sent as an
7// HTTP POST to /voice in our application
8app.post('/voice', (request, response) => {
9  // Use the Twilio Node.js SDK to build an XML response
10    const twiml = new VoiceResponse();
11
12    twiml.say('Hello from your pals at Twilio! Have fun.');
13
14  // Render the response as XML in reply to the webhook request
15  response.type('text/xml');
16  response.send(twiml.toString());
17});
18
19// Create an HTTP server and listen for requests on port 1337
20app.listen(1337, () => {
21    console.log('TwiML server running at http://127.0.0.1:1337/');
22});

Save the file.
In a new terminal window, run the following command to start your server:
node answer_phone.js
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 1337
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Append /voice to your ngrok public URL, and then paste the result into the URL field. For example, if your ngrok console shows Forwarding https://1aaa-123-45-678-910.ngrok-free.app, enter https://1aaa-123-45-678-910.ngrok-free.app/voice.
6. Click Save configuration.
With your server and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in answer_phone.js.

Create a file named answer_call.php in the same folder as make_call.php and add the following code:

1<?php
2require __DIR__ . '/vendor/autoload.php';
3use Twilio\TwiML\VoiceResponse;
4
5// Start our TwiML response
6$response = new VoiceResponse();
7
8// Read a message aloud to the caller
9$response->say(
10    "Thank you for calling! Have a great day.",
11    ["voice" => "Polly.Amy"]
12);
13
14echo $response;

Save the file.
In a new terminal window, run the following command to start your PHP development server:
php -S localhost:8000 answer_call.php
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 8000
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Paste your ngrok public URL in the URL field (for example, https://ff4660c91380.ngrok.app).
6. Click Save configuration.
With the PHP development server and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in answer_call.php.

Replace the contents of Program.cs with the following code:

1using Twilio.TwiML;
2var builder = WebApplication.CreateBuilder(args);
3var app = builder.Build();
4
5app.MapMethods("/", ["GET", "POST"], () =>
6{
7 var response = new VoiceResponse()
8     .Say("Thank you for calling! Have a great day.");
9 return Results.Text(response.ToString(), "application/xml");
10});
11
12app.Run("http://localhost:4567");

Save the file.
In a new terminal window, run the following command to start your development server:
dotnet run
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 4567
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Paste your ngrok public URL in the URL field (for example, https://ff4660c91380.ngrok.app).
6. Click Save configuration.
With your development server and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in Program.cs.

Create a file named VoiceApp.java in the src/main/java directory and add the following code:

Generate TwiML to Say a message

1import com.twilio.twiml.VoiceResponse;
2import com.twilio.twiml.voice.Say;
3
4import static spark.Spark.*;
5
6public class VoiceApp {
7    public static void main(String[] args) {
8
9        get("/hello", (req, res) -> "Hello Web");
10
11        post("/", (request, response) -> {
12            Say say  = new Say.Builder(
13                    "Hello from your pals at Twilio! Have fun.")
14                    .build();
15            VoiceResponse voiceResponse = new VoiceResponse.Builder()
16                    .say(say)
17                    .build();
18            return voiceResponse.toXml();
19        });
20    }
21}

Save the file.
Open the build.gradle file and replace Example with VoiceApp. Save the file.
In a new terminal window, run the following command to start your Spark server:
gradle run
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 4567
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Paste your ngrok public URL in the URL field (for example, https://ff4660c91380.ngrok.app).
6. Click Save configuration.
With your Spark server and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in VoiceApp.java.

Create a file named main.go and add the following code:

Generate TwiML to Say a message

1package main
2
3import (
4	"net/http"
5
6	"github.com/gin-gonic/gin"
7	"github.com/twilio/twilio-go/twiml"
8)
9
10func main() {
11	router := gin.Default()
12
13	router.POST("/answer", func(context *gin.Context) {
14		say := &twiml.VoiceSay{
15			Message: "Hello from your pals at Twilio! Have fun.",
16		}
17
18		twimlResult, err := twiml.Voice([]twiml.Element{say})
19		if err != nil {
20			context.String(http.StatusInternalServerError, err.Error())
21		} else {
22			context.Header("Content-Type", "text/xml")
23			context.String(http.StatusOK, twimlResult)
24		}
25	})
26
27	router.Run(":1337")
28}

Save the file.
Install Gin and other dependencies:
go get
In a new terminal window, run the following command to start your Gin app:
go run main.go
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 1337
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Paste your ngrok public URL in the URL field with /answer appended (for example, https://ff4660c91380.ngrok.app/answer).
6. Click Save configuration.
With your Gin app and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in main.go.

Create a file named answer_call.rb in the same folder as make_call.rb and add the following code:

1require 'sinatra'
2require 'twilio-ruby'
3
4configure :development do
5  set :host_authorization, { permitted_hosts: [] }
6end
7
8def self.get_or_post(url,&block)
9  get(url,&block)
10  post(url,&block)
11end
12
13get_or_post '/' do
14  content_type 'text/xml'
15
16  Twilio::TwiML::VoiceResponse.new do | response |
17    response.say(message: "Ahoy world!")
18  end.to_s
19end

Save the file.
In a new terminal window, run the following command to start your Sinatra server:
ruby answer_call.rb
In a new terminal window, run the following command to start ngrok and create a tunnel to your localhost:
ngrok http 4567
Set up a webhook that triggers when your Twilio phone number receives a phone call:
1. Go to the Active Numbers page in the Twilio Console.
2. Click your Twilio phone number.
3. Go to the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option.
5. Paste your ngrok public URL in the URL field (for example, https://ff4660c91380.ngrok.app).
6. Click Save configuration.
With your Sinatra server and ngrok running, call your Twilio phone number. You hear the text-to-speech message defined in answer_call.rb.

Next steps

Browse reference documentation for the Programmable Voice API
Learn about TwiML markup language for responding to voice calls
Browse all voice tutorials by topic