--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/voice/tutorials/how-to-respond-to-incoming-phone-calls#article headline: Respond to Incoming Phone Calls description: Respond to incoming phone calls with Twilio Programmable Voice by handling incoming webhooks with TwiML responses for voice apps and notifications. url: https://www.twilio.com/docs/voice/tutorials/how-to-respond-to-incoming-phone-calls inLanguage: en dateModified: 2026-06-22T10:15:32.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Respond to Incoming Phone Calls Learn to handle and answer inbound calls with Twilio Programmable Voice by serving a TwiML document in response to the Twilio HTTP webhook request when a call is received. You can use this guide to create self-service automation and build inbound contact centers. See [Related reference documentation](#related-reference-documentation) to learn more about the TwiML elements used in this guide. ## Complete the prerequisites ### Complete the Twilio prerequisites * [Create a Twilio account][]. * In the *Twilio Console*, create a [compliance profile][1c-comply-docs], then [buy a voice-enabled phone number][1c-buy-tn]. * In the *legacy Console*, [buy a voice-enabled phone number][lc-buy-tn]. Only Messaging-enabled phone numbers need a compliance profile. ### Complete the language prerequisites Select your programming language and complete the prerequisites: ## Python * [Install Python 3.3 or later][install-py]. * Install [Flask][] and the [Twilio Python Helper Library][tw-py]. Using [pip][], run the following command: ```bash pip install flask twilio ``` * Install and set up [ngrok][]. ## Node.js * [Install Node.js 20 or later][install-node]. * Install [Express][] with [body-parser][], and the [Twilio Node.js helper library][tw-node]: ```bash npm install twilio express ``` * Install and set up [ngrok][]. ## PHP * [Install PHP 7.2 or later][install-php]. * Install the [Composer][] dependency manager [globally][Composer-global]. * Install the [Twilio PHP Helper Library][tw-php]: ```bash composer require twilio/sdk ``` * Install and set up [ngrok][]. ## C# or .NET * [Install .NET 6 or later][install-net]. * Install the [Twilio C# Helper Library][tw-net]. * Install and set up [ngrok][]. ## Java * [Install Java 8 or later][install-java]. * Install the [Twilio Java Helper Library][tw-java]. * Install [Gradle][install-gradle] or [Maven][install-maven]. * Install and set up [ngrok][]. ## Ruby * [Install Ruby 2.6 or later][install-rb]. * Install [Sinatra][] and the [Twilio Ruby Helper Library][tw-rb]: ```bash gem install sinatra rackup puma twilio-ruby ``` * Install and set up [ngrok][]. ### Get credentials and set as environment variables Extract your credentials from your Twilio account then save these credentials as environment variables. ## Twilio Console 1. Go to the [Twilio Console][1c]. The **Let's get building** page appears. 2. Click **API keys and Auth tokens**. The **API keys & auth tokens** page appears with the **Auth Tokens** tab selected. 3. Scroll to your **Account SID**. 4. Click the copy button next to your **Account SID**. 5. Run the following command, replacing `YOUR_ACCOUNT_SID` with *your* Account SID. ## macOS Terminal ```bash export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## Windows command line ```bash set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## PowerShell ```bash $Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID" ``` This command creates an environment variable on your development system for your account SID. 6. To display the Auth Token, click the eye button in the **Primary auth token** box. 7. Highlight and copy the Auth Token. 8. Run the following command, replacing `YOUR_AUTH_TOKEN` with *your* Authentication Token. ## macOS Terminal ```bash export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## Windows command line ```bash set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## PowerShell ```bash $Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN" ``` This command creates an environment variable on your development system for your auth token. ## macOS Terminal ```bash export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## Windows command line ```bash set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## PowerShell ```bash $Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID" ``` ## macOS Terminal ```bash export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## Windows command line ```bash set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## PowerShell ```bash $Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN" ``` ## Legacy Console 1. Go to the [Twilio Console][lc]. The **Get Started with Twilio** page appears. 2. Scroll to the **Account Info** block. 3. Click the copy button next to your **Account SID**. 4. Run the following command, replacing `YOUR_ACCOUNT_SID` with *your* Account SID. ## macOS Terminal ```bash export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## Windows command line ```bash set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## PowerShell ```bash $Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID" ``` 5. Click the copy button next to your **Auth Token**. 6. Run the following command, replacing `YOUR_AUTH_TOKEN` with *your* Authentication Token. ## macOS Terminal ```bash export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## Windows command line ```bash set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## PowerShell ```bash $Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN" ``` This command creates an environment variable on your development system for your auth token. ## macOS Terminal ```bash export TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## Windows command line ```bash set TWILIO_ACCOUNT_SID=YOUR_ACCOUNT_SID ``` ## PowerShell ```bash $Env:TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID" ``` ## macOS Terminal ```bash export TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## Windows command line ```bash set TWILIO_AUTH_TOKEN=YOUR_AUTH_TOKEN ``` ## PowerShell ```bash $Env:TWILIO_AUTH_TOKEN="YOUR_AUTH_TOKEN" ``` [1c-buy-tn]: https://1console.twilio.com/go?to=/account/__account__/us1/senders-hub/list/phone-numbers/inventory [lc-buy-tn]: https://console.twilio.com/us1/develop/phone-numbers/manage/search [Create a Twilio account]: https://www.twilio.com/try-twilio [Express]: https://expressjs.com [Flask]: http://flask.pocoo.org [Composer]: https://getcomposer.org/doc/00-intro.md [Composer-global]: https://getcomposer.org/doc/00-intro.md#globally [Sinatra]: http://www.sinatrarb.com [install-gradle]: https://gradle.org/install [install-maven]: https://maven.apache.org/install.html [install-java]: https://www.oracle.com/java/technologies/downloads [install-node]: https://nodejs.org [install-php]: http://php.net/manual/en/install.php [install-py]: https://www.python.org/downloads [install-rb]: https://www.ruby-lang.org/en/documentation/installation [install-net]: https://dotnet.microsoft.com/en-us/download [ngrok]: https://ngrok.com/docs/getting-started [pip]: https://pip.pypa.io/en/latest [tw-java]: https://github.com/twilio/twilio-java [tw-net]: https://github.com/twilio/twilio-csharp [tw-node]: https://github.com/twilio/twilio-node [tw-php]: https://github.com/twilio/twilio-php [tw-py]: https://github.com/twilio/twilio-python [tw-rb]: https://github.com/twilio/twilio-ruby [1c-comply-docs]: /docs/trust-hub/registrations/regulatory-compliance [lc]: https://console.twilio.com [1c]: https://1console.twilio.com/go?to=/account/__account__ [body-parser]: https://github.com/expressjs/body-parser ## Respond to an incoming call When a Twilio phone number receives an incoming call, Twilio sends an HTTP request to your web app. This request asks for instructions on how you want the call handled. Your web app responds with an [TwiML][] document. Twilio takes the instruction set from that document and performs an action. This might include saying some arbitrary text, playing an MP3 file, or recording the call audio. To respond to an inbound call, send a response request to Twilio using one of these helper libraries. ## Python Python only requires the Twilio Python helper library as noted in the [prerequisites][lang-prereq]. Respond to an incoming call with TwiML ```py from flask import Flask from twilio.twiml.voice_response import VoiceResponse app = Flask(__name__) @app.route("/voice", methods=['GET', 'POST']) def voice(): """Respond to incoming phone calls with a 'Hello world' message""" # Start our TwiML response resp = VoiceResponse() # Read a message aloud to the caller resp.say("Hello world!") return str(resp) if __name__ == "__main__": app.run(debug=True) ``` ## Node.js Node.js requires Express and the Twilio Node.js helper library as noted in the [prerequisites][lang-prereq]. Respond to an incoming call with TwiML ```js const express = require('express'); const VoiceResponse = require('twilio').twiml.VoiceResponse; const app = express(); // Create a route that will handle Twilio webhook requests, sent as an // HTTP POST to /voice in our application app.post('/voice', (request, response) => { // Use the Twilio Node.js SDK to build an XML response const twiml = new VoiceResponse(); twiml.say('Hello world!'); // Render the response as XML in reply to the webhook request response.type('text/xml'); response.send(twiml.toString()); }); // Create an HTTP server and listen for requests on port 3000 app.listen(3000, () => { console.log( 'Now listening on port 3000. ' + 'Be sure to restart when you make code changes!' ); }); ``` ## PHP PHP only requires the Twilio PHP helper library as noted in the [prerequisites][lang-prereq]. Respond to an incoming call with TwiML ```php say("Hello world!"); print $response; ``` ## C# or .NET C# requires the .NET 6 framework and the Twilio C# helper library as noted in the [prerequisites][lang-prereq]. Respond to an incoming call with TwiML ```cs // In Package Manager, run: // Install-Package Twilio.AspNet.Mvc -DependencyVersion HighestMinor using System.Web.Mvc; using Twilio.AspNet.Mvc; using Twilio.TwiML; public class VoiceController : TwilioController { [HttpPost] public ActionResult Index() { var response = new VoiceResponse(); response.Say("Hello world!"); return TwiML(response); } } ``` ## Java Java requires Gradle or Maven and the Twilio Java helper library as noted in the [prerequisites][lang-prereq]. Respond to an incoming call with TwiML ```java import java.io.IOException; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.twilio.twiml.voice.Say; import com.twilio.twiml.TwiMLException; import com.twilio.twiml.VoiceResponse; @SuppressWarnings("serial") @WebServlet("/voice") public class IncomingCallServlet extends HttpServlet { // Handle HTTP POST to /voice protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { Say say = new Say.Builder("Hello world!").build(); VoiceResponse twiml = new VoiceResponse.Builder().say(say).build(); // Render TwiML as XML response.setContentType("text/xml"); try { response.getWriter().print(twiml.toXml()); } catch (TwiMLException e) { e.printStackTrace(); } } } ``` ## Ruby Ruby requires Sinatra and the Twilio Ruby helper library as noted in the [prerequisites][lang-prereq]. Respond to an incoming call with TwiML ```rb # Get twilio-ruby from twilio.com/docs/ruby/install require 'sinatra' require 'twilio-ruby' post '/twiml' do # Start our TwiML response Twilio::TwiML::VoiceResponse.new do |r| # Use to give the caller some instructions r.say(message: 'Hello world!') end.to_s end ``` ```xml {title="TwiML response document"} Hello world! ``` ## Create dynamic responses to incoming calls The previous section provided code that responds to an incoming call with a pre-defined TwiML document. Using the [data Twilio sends to your app][tw-info-sent] through webhooks, you can change what gets presented to the user on the other end of the phone call. You can write custom code that gathers additional server-side data that builds your response to your user. To create a custom response to an inbound call, send a response request to Twilio using one of these helper libraries. ## Python Python only requires the Twilio Python helper library as noted in the [prerequisites][lang-prereq]. Create a dynamic response to an incoming call ```py from flask import Flask, request from twilio.twiml.voice_response import VoiceResponse app = Flask(__name__) @app.route("/voice", methods=['GET', 'POST']) def voice(): """Respond to incoming phone calls and mention the caller's city""" # Get the caller's city from Twilio's request to our app city = request.values['FromCity'] # Start our TwiML response resp = VoiceResponse() # Read a message aloud to the caller resp.say('Never gonna give you up, {}!'.format(city)) # Play an audio file for the caller resp.play('https://demo.twilio.com/docs/classic.mp3') return str(resp) if __name__ == "__main__": app.run(debug=True) ``` ## Node.js Node.js requires Express and the Twilio Node.js helper library as noted in the [prerequisites][lang-prereq]. Create a dynamic response to an incoming call ```js const express = require('express'); const VoiceResponse = require('twilio').twiml.VoiceResponse; const urlencoded = require('body-parser').urlencoded; const app = express(); // Parse incoming POST params with Express middleware app.use(urlencoded({ extended: false })); // Create a route that will handle Twilio webhook requests, sent as an // HTTP POST to /voice in our application app.post('/voice', (request, response) => { // Get information about the incoming call, like the city associated // with the phone number (if Twilio can discover it) const city = request.body.FromCity; // Use the Twilio Node.js SDK to build an XML response const twiml = new VoiceResponse(); twiml.say(`Never gonna give you up ${city}.`); twiml.play({}, 'https://demo.twilio.com/docs/classic.mp3'); // Render the response as XML in reply to the webhook request response.type('text/xml'); response.send(twiml.toString()); }); // Create an HTTP server and listen for requests on port 3000 app.listen(3000); ``` ## PHP PHP only requires the Twilio PHP helper library as noted in the [prerequisites][lang-prereq]. Create a dynamic response to an incoming call ```php say("Never gonna give you up, {$city}!"); $response->play("https://demo.twilio.com/docs/classic.mp3"); echo $response; ``` ## C# or .NET C# requires the .NET 6 framework and the Twilio C# helper library as noted in the [prerequisites][lang-prereq]. Create a dynamic response to an incoming call ```cs // In Package Manager, run: // Install-Package Twilio.AspNet.Mvc -DependencyVersion HighestMinor using System.Web.Mvc; using Twilio.AspNet.Mvc; using Twilio.TwiML; public class VoiceController : TwilioController { [HttpPost] public ActionResult Index(string fromCity) { // Get information about the incoming call, like the city associated // with the phone number (if Twilio can discover it) var city = fromCity; var response = new VoiceResponse(); response.Say($"Never gonna give you up {city}"); response.Play("https://demo.twilio.com/docs/classic.mp3"); return TwiML(response) } } ``` ## Java Java requires Gradle or Maven and the Twilio Java helper library as noted in the [prerequisites][lang-prereq]. Create a dynamic response to an incoming call ```java import java.io.IOException; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.twilio.twiml.voice.Play; import com.twilio.twiml.voice.Say; import com.twilio.twiml.TwiMLException; import com.twilio.twiml.VoiceResponse; @SuppressWarnings("serial") @WebServlet("/voice") public class IncomingCallServlet extends HttpServlet { // Handle HTTP POST to /voice protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Get the city from the incoming call (if available) String fromCity = request.getParameter("FromCity"); if (fromCity == null) { fromCity = "home slice"; } Say say = new Say.Builder(String.format("Never gonna give you up, %s!", fromCity)).build(); Play play = new Play.Builder("https://demo.twilio.com/docs/classic.mp3").build(); VoiceResponse response = new VoiceResponse.Builder().say(say).play(play).build(); // Render TwiML as XML response.setContentType("text/xml"); try { response.getWriter().print(twiml.toXml()); } catch (TwiMLException e) { e.printStackTrace(); } } } ``` ## Ruby Ruby requires Sinatra and the Twilio Ruby helper library as noted in the [prerequisites][lang-prereq]. Create a dynamic response to an incoming call ```rb # Get twilio-ruby from twilio.com/docs/ruby/install require 'sinatra' require 'twilio-ruby' post '/voice' do city = params['FromCity'] # Start our TwiML response Twilio::TwiML::VoiceResponse.new do |r| # Use to give the caller some instructions r.say("Never gonna give you up #{city}.") r.play(url: 'https://demo.twilio.com/docs/classic.mp3') end.to_s end ``` ## Expose your local dev environment to Twilio with ngrok To use the webhooks in this code sample, Twilio must communicate with your web app. These communications consist of HTTP requests sent between URLs accessible over the internet. Twilio requires access to Internet-addressable, or *public*, URLs. > \[!WARNING] > > Twilio supports HTTP Basic and Digest Authentication. This type of authentication protects your TwiML URLs on your web server with an Auth Token. This limits access to the URLs to you and Twilio. Protect your auth tokens as you would your passwords. To learn more, see [HTTP authentication][http-secure]. ### Create a public URL for your app Most production systems have a public URL, but development systems might not. To permit Twilio to access your local dev app, use `ngrok`. To create a public URL for your app, run `ngrok` at the command line: ```bash ngrok http 3000 --url https://.ngrok.dev ``` This command creates a public URL `https://.ngrok.dev`. that forwards HTTP requests to your web app listening on `localhost:3000`. #### View the command output ```bash # !mark(7:8) ngrok by @inconshreveable Tunnel Status online Version 3.x.x Region us Web Interface http://127.0.0.1:3000 Forwarding http://.ngrok.io -> http://localhost:3000 Forwarding https://.ngrok.io -> http://localhost:3000 Connections ttl opn rt1 rt5 p50 p90 0 0 0.00 0.00 0.00 0.00 ``` ### Configure Twilio connection to your web app With your public URL created, configure its connection to Twilio using a webhook. [http-secure]: /docs/usage/security#http-authentication ## Twilio Console If you use the new Twilio Console, follow these steps: 1. Go to [**Numbers & senders**][1c-phones]. 2. Click your Twilio phone number you want for your app. * If you don't have any phone numbers, click [**Set up a new phone number**][1c-new]. * If Twilio needs your compliance data, create a [compliance profile][1c-comply-docs] first. 3. Click the **Configuration details** tab. 4. Click **Messaging** > **Edit details**. 5. On the **Edit messaging configuration** dialog, select the **Webhook, TwiML Bin, Function, Studio Flow, Proxy Service** option. 6. Under **How do you want to set up your primary method?**, select **Webhook**. 7. Paste your ngrok public URL in the **URL** box.\ If your `ngrok` console shows `Forwarding https://.ngrok.dev`, paste `https://.ngrok.dev` to the **URL** box. ## Legacy Console If you use the legacy Console, follow these steps: 1. Go to [**Active Numbers**][lc-phones]. 2. Click your Twilio phone number. * If you don't have any phone numbers, click [**Buy a number**][lc-new]. 3. Click **Configure** next to your phone number. Twilio opens the Phone Number page with the **Configure** tab selected. 4. Go to the **Voice Configuration** section. 5. In the **A call comes in** dropdown menu, select **Webhook**. 6. In the **URL** box, paste your ngrok public URL.\ For example, `https://.ngrok.dev`). 7. Leave the other boxes and menus with their default values. 8. At the end of the page, click **Save configuration**. [lc-phones]: https://console.twilio.com/us1/develop/phone-numbers/manage/incoming [lc-new]: https://console.twilio.com/US1/develop/phone-numbers/manage/search [1c-phones]: https://1console.twilio.com/go?to=/account/__account__/us1/senders-hub/list/phone-numbers/inventory [1c-new]: https://1console.twilio.com/go?to=/account/__account__/us1/senders-onboarding?setupGuide=true [1c-comply-docs]: /docs/trust-hub/registrations/regulatory-compliance ## Use cases for incoming calls with Twilio Programmable Voice This guide teaches the basics required for the following use cases: ### Create self-service automation with Twilio Programmable Voice You can use this guide to intercept incoming customer calls and immediately present resolution paths. When Twilio triggers a webhook request to your server, you can return a structured TwiML script that handles inquiries without the intervention of human agents, like checking delivery statuses or updating user records. To learn more advanced features that you can use with self-service automation, see [Voice self-service automation](/docs/voice/guides/self-service-automation). ### Create an inbound contact center with Twilio Programmable Voice You can use this guide as the fundamental entry point for routing and managing callers seeking live assistance. By responding to incoming call webhooks dynamically, your backend application can inspect customer details, query your CRM database, and use intelligent call distribution to pass the caller to the correct department queue. To learn more advanced features that you can use with inbound contact centers, see [Voice inbound contact center](/docs/voice/guides/inbound-call-center). ## Result After following this guide, your web application can successfully listen for, receive, and respond to incoming webhooks triggered by inbound phone calls directed to your Twilio numbers. You can verify that your logic is operational by dialing your provisioned Twilio phone number from a mobile device and confirming that your server executes your specific TwiML voice commands. ## Next steps Explore the following guides to build on what you've learned in this guide: * [Gather user input using Keypad (DTMF Tones)](/docs/voice/tutorials/how-to-gather-user-input-via-keypad): Learn how to extend your inbound call handlers to collect digits pressed on a phone keypad. * [Build an Interactive Voice Response (IVR) phone tree](/docs/voice/tutorials/build-interactive-voice-response-ivr-phone-tree): Construct multi-level menus to intelligently segment and guide your incoming callers. * [How to record phone calls](/docs/voice/tutorials/how-to-record-phone-calls): Capture call audio programmatically for quality assurance, compliance, or storage. * [How to create conference calls](/docs/voice/tutorials/how-to-create-conference-calls): Connect multiple callers together into a centralized, hosted audio conference room. ## Related reference documentation Find reference documentation for the topics on this page. * [TwiML™ for Programmable Voice](/docs/voice/twiml) * [TwiML™ Voice: ``](/docs/voice/twiml/say) * [TwiML™ Voice: ``](/docs/voice/twiml/play) * [TwiML™ Voice: ``](/docs/voice/twiml/gather) * [TwiML™ Voice: ``](/docs/voice/twiml/record) * [TwiML™ Voice: ``](/docs/voice/twiml/redirect) [user-input]: /docs/voice/tutorials/how-to-gather-user-input-via-keypad [record-calls]: /docs/voice/tutorials/how-to-record-phone-calls [create-cc]: /docs/voice/tutorials/how-to-create-conference-calls [click-call-node]: /docs/voice/sdks/javascript/get-started [survey-node]: https://www.twilio.com/blog/automated-survey-nodejs-express [calls-leads-node]: https://www.twilio.com/blog/call-tracking-nodejs-express [server-servlets]: https://www.twilio.com/blog/automated-survey-java-servlets [server-spark]: https://www.twilio.com/blog/automated-survey-java-spark [server-spring]: https://www.twilio.com/blog/automated-survey-java-spring [calls-servlets]: /docs/messaging/tutorials/masked-numbers/java [calls-leads-servlets]: https://www.twilio.com/blog/call-tracking-java-servlets [ngrok]: https://ngrok.com [lc-phone]: https://console.twilio.com/phone-numbers/incoming [1c-phone]: https://1console.twilio.com/go?to=/account/__account__/us1/senders-hub/list/phone-numbers/inventory [lang-prereq]: #complete-the-language-prerequisites [TwiML]: /docs/voice/twiml [Programmable Voice]: https://www.twilio.com/en-us/voice [tw-info-sent]: /docs/voice/twiml#twilios-request-to-your-application