Menu

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?

Click To Call with Java and Spring

Download the Code

Wish your users could get in touch as easily as they can surf? It's your lucky day!

Let's go over the steps necessary to implement click-to-call in a Java and Spring application.

Click to Call

  1. A website visitor submits a web form with a phone number.
  2. Your web application receives the submission and initiates an HTTP request to Twilio asking to initiate an outbound call.
  3. Twilio receives the request and initiates a call to the user's phone number.
  4. The user picks up the call.
  5. After the call connects, we provide TwiML instructions to connect the user to our sales or support teams.

What you will learn

This tutorial demonstrates how to initialize a call using the Twilio REST API and how to create a call using the TwiML Say verb.

Let's get started! Click the button below to move to the next step of the tutorial.

Next

Set up your environment

Before we create our click-to-call application, we need to set up our environment first.

Let's put our Twilio credentials in a place where our application can access them. We'll store them as environment variables that our application can read.

# Twilio API credentials
export TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export TWILIO_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Twilio phone number
export TWILIO_NUMBER=+15552737123

Replace the Account_SID, Auth_Token, and Twilio_Number placeholder values with your unique values, which you can find in the Twilio Console. You can use an existing Twilio phone number or obtain a new number.

Twilio Console Credentials Location

Loading Code Sample...
      
      
      
      
      .env.example

      Next, let's look at making a friendly web form.

      Next

      The web form

      For our solution, we'll need a form where the user can enter a phone number.

      No need to overthink this step as the real goal is to POST the user's phone number to your controller.

      What information does this form need?

      • An input for the User's phone number
      • An input for the sales team phone number
      • A submit button
      Loading Code Sample...
          
          
          
          
          src/main/resources/templates/index.html

          User facing web form

          src/main/resources/templates/index.html

          Since the page doesn't need to render new content after clicking on submit, we decided to implement the POST action via AJAX using jQuery. Let's take a look at that code next.

          Next

          Submit the form

          To make the click to call feature more seamless we used Ajax to send the form asynchronously.

          This code shows one way you could implement this functionality using jQuery:

          • Watch for the user "submitting" the form element
          • Submit the form data to our controller
          • Let the user know if the submission was successful or not

          This is a common implementation of jQuery's $.ajax() method. Notice that we are returning the response message when the call has connected.

          Loading Code Sample...
              
              
              
              
              src/main/resources/static/js/clicktocall.js

              Submit the form with AJAX

              src/main/resources/static/js/clicktocall.js

              Now that we have the front end done let's build the back end that will receive this data. We'll start our exploration in the next step.

              Next

              Instantiate a client object

              First, we instantiate a twilioRestClient object with our Account SID and Auth Token. This is essentially our Java REST API handler, which we could use to send SMSes (or a myriad of other things).

              In this example, we're defining it as a Spring Bean. This way we can use the framework Dependency Injection capabilities later.

              Loading Code Sample...
                  
                  
                  
                  
                  src/main/java/com/twilio/clicktocall/Application.java

                  Instantiate a twilioRestClient object

                  src/main/java/com/twilio/clicktocall/Application.java

                  Next, we'll look at making a phone call.

                  Next

                  Make a phone call

                  We'll use the CallCreator object to make an outgoing phone call which requires us to pass a From number, a To number and the URL parameter that tells Twilio what to do after it connects the call to our user. In this case, Twilio needs to DIAL the Agent once the call has been placed. We'll discuss this more in future steps.

                  Loading Code Sample...
                      
                      
                      
                      
                      src/main/java/com/twilio/clicktocall/twilio/TwilioLine.java

                      Call Controller

                      src/main/java/com/twilio/clicktocall/twilio/TwilioLine.java

                      Next, let's look at the endpoint we'll expose to Twilio.

                      Next

                      The Connect endpoint

                      Twilio makes a request to our application when the call is created using the REST API. We'll need to create an endpoint that is publicly available for internet requests: we'll walk through a way to make your localhost accessible via ngrok a little later in this tutorial.

                      Loading Code Sample...
                          
                          
                          
                          
                          src/main/java/com/twilio/clicktocall/ConnectController.java

                          Call Connect Controller

                          src/main/java/com/twilio/clicktocall/ConnectController.java

                          A publicly exposed URL has some drawbacks. Next, we'll look at making sure we don't leak any sensitive data.

                          Next

                          Validate the Twilio request

                          Twilio makes a request to our application when the call is created using the REST API. That means we've got an endpoint that is publicly available for internet requests.

                          Since TwiML sometimes contains sensitive information such as phone numbers, we don't want just anybody accessing the TwiML.

                          Twilio request validator

                          With that in mind, let's first check if the request originated from Twilio before we return any TwiML. The validate method provides a mechanism to confirm that the request your application is receiving is coming from Twilio. We'll use an instance of RequestValidator and call the validate method using the required parameters.

                          Loading Code Sample...
                              
                              
                              
                              
                              src/main/java/com/twilio/clicktocall/twilio/TwilioRequestValidator.java

                              Twilio Request Validator

                              src/main/java/com/twilio/clicktocall/twilio/TwilioRequestValidator.java

                              Now that we know a request originates from Twilio let's move on and look at the TwiML response we'll send.

                              Next

                              Generate TwiML

                              TwiML is a set of verbs and nouns written in XML that Twilio reads as instructions.

                              In this case, our instructions inform Twilio to SAY something to the user and then DIAL the support agent's number so the customer can talk to him or her.

                              To make writing TwiML easier, the helper libraries have methods that generate TwiML for you. We use twilio-java to create a TwiML response that will instruct Twilio to SAY something.

                              Loading Code Sample...
                                  
                                  
                                  
                                  
                                  src/main/java/com/twilio/clicktocall/twilio/TwiMLUtil.java

                                  Generate a TwiML response

                                  src/main/java/com/twilio/clicktocall/twilio/TwiMLUtil.java

                                  And with that, you've helped us get a working click-to-call form, ready to be integrated into your application.

                                  Next

                                  Testing your app locally

                                  Now you can run and test your Twilio app.

                                  However, you probably want to test it using a publicly available endpoint without having to go "public" with your app. The best option is to use ngrok.

                                  Note: For more information about running the application, see the readme file in the app github repository.

                                  About ngrok

                                  ngrok generates a secure URL that forwards traffic to a port, usually 5000, on your localhost server. It allows you to run applications locally but make them a publicly available endpoint via secure tunneling. This allows you to test your application and do all the things you want your app to do but in a safe public space.

                                  ngrok is an executable (ngrok.exe) that you run on the command line or terminal.

                                  Setting Up ngrok

                                  Head over to ngrok's website, download the ngrok.zip file for your OS of choice, then unzip the file into an easily accessible location.

                                  For example, on Windows, you can place it in your \Users directory in \AppData\Roaming\<ngrok-directory-name>\ngrok.exe. Then, update your PATH environment variables to the location of the ngrok executable. On Linux or OSX follow the installation instructions on the ngrok site.

                                  And that's it.

                                  Accessing your app from an endpoint using ngrok

                                  Before you start ngrok, it might be a good idea to have your Twilio Console open.

                                  For Mac and Linux, open a terminal and run this command to start ngrok:

                                  $ ./ngrok http 4040

                                  On Windows, open a command prompt and run this command to start ngrok:

                                  $ Path-to-ngrok> ngrok http 4040

                                  Alternately, you can start ngrok using the following command:

                                  $ ngrok http 4040 -host-header="localhost:4040"

                                  The port number "4040" is arbitrary. If your local server is running on another port, replace "4040" in the command with the appropriate port number.

                                  This will start ngrok. A running instance of ngrok will appear in the terminal showing the local web interface (in this case http://127.0.0.1:4040) and the public URL (in this case, https://28dd499b.ngrok.io).

                                  ngrok-running

                                  The forwarding public URL needs to be set in the Twilio Console. In the Console, select the active phone number you set in the environment configuration file and enter the public URL from ngrok (shown above) in the "A Call Comes In" field under Voice & Fax. Be sure to select Webhook from the dropdown list.

                                  Each time you restart ngrok a new public URL will be generated. You will need to update this URL in the Console any time you restart ngrok.

                                  Twilio Console Webhook Setting

                                  You now have a publicly available endpoint for your app. Now you can take a look at your running app and enter the phone numbers using your ngrok address: https://xxxxxx.ngrok.io

                                  What Else Can I Build?

                                  Where to next?

                                  Did this help?

                                  Thanks for checking this tutorial out! Tweet to us @twilio and let us know what you're building!

                                  Kevin Whinnery Agustin Camino Andrew Baker Paul Kamp Kat King Glenn Lea

                                  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.

                                  Loading Code Sample...