Menu

Expand
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?

Browser Calls with Java and Spark

This Spark web application shows how you can use Twilio Client to make browser-to-phone and browser-to-browser calls.

This application powers the support site for the Birchwood Bicycle Polo Co., which sells equipment to those who play "the sport of kings." It has three main features:

  • Unsatisfied customers can submit support tickets with their phone number and their problem.
  • Support agents can call customers' phones from their browser to follow up on support tickets.
  • Customers can also use their browser to speak with support agents live when available.

In this tutorial, we'll point out the key bits of code that make this application work. Check out the project README on GitHub to see how to run the code yourself.

Learn how Zendesk uses Twilio Client to make phone support available in 40+ countries.

Let's get started!

Submit a support ticket

The home page of our app displays a form for customers to submit support tickets. We use Mustache Template Engine to power the page, and this controller to create the ticket.

        
        
        
        
        src/main/java/com/twilio/browsercalls/controllers/TicketController.java

        Create a Ticket

        src/main/java/com/twilio/browsercalls/controllers/TicketController.java

        Let's look at the model.

        The Support Ticket Model

        The Support Ticket Model

        A support ticket has just a few fields - a name for the end user, a description of the trouble they're having, and a phone number we can use to call them back.

              
              
              
              
              src/main/java/com/twilio/browsercalls/models/Ticket.java

              Support Ticket Model

              src/main/java/com/twilio/browsercalls/models/Ticket.java

              Now we can create a ticket. Next up, let's work on the dashboard for the support agent.

              Make a Dashboard for our Support Agents

              The support dashboard

              When a support agent visits /dashboard, they see all the support tickets which have been submitted.

              Each ticket also has a "Call Customer" button which invokes a JavaScript function we wrote named callCustomer(). That function kicks off a Twilio Client call to the phone number passed as its sole parameter.

                    
                    
                    
                    
                    src/main/resources/templates/dashboard.mustache

                    Support Agent's Dashboard

                    src/main/resources/templates/dashboard.mustache

                    Great, now we have an interface good enough for our support agents. Next up, in order to let our agents make calls to their customers through the browser, we need to provide them a capability token.

                    Let's learn how to generate a Capability Token

                    Generate a capability token

                    We use the Twilio Java helper library to generate and configure our capability tokens. To allow our support agents to call the phone numbers on our tickets, we use an OutgoingClientScope.

                    That method requires an identifier for a TwiML Application. Twilio will send a POST request to our backend every time a user makes a Twilio Client call — the TwiML Application tells Twilio which URL to send that request to.

                          
                          
                          
                          
                          src/main/java/com/twilio/browsercalls/lib/CapabilityTokenGenerator.java

                          Generate a capability token

                          src/main/java/com/twilio/browsercalls/lib/CapabilityTokenGenerator.java

                          Once we are equipped with our Capability Token, the next step is to set up the Twilio Device Client in the browser.

                          Time for some JavaScript!

                          Set up a Twilio Device Client

                          To use the Twilio Device Client in a web browser we use the twilio.js library.

                          We start by retrieving a capability token from the view we defined in the previous step with a POST request through AJAX. Then we enable the Twilio Device Client for this page by passing our token to Twilio.Device.setup().

                          After that the Twilio.Device.ready() callback will let us know when the browser is ready to make and receive calls.

                                
                                
                                
                                
                                src/main/resources/public/js/browser-calls.js

                                Set up a Twilio Device

                                src/main/resources/public/js/browser-calls.js

                                Now that we have almost everything in place, it's time to see the core of this tutorial. Let's look at how we can let our agents start a call from their browsers.

                                Call a customer's phone from your browser

                                Calling a Customer (browser-to-phone)

                                When our support agents click on the Call Customer button on a support ticket, the function highlighted on the code snippet will initiate the call.

                                We use Twilio.Device.connect() to begin a new outgoing call. Our backend will tell Twilio how to handle this call, so we include a phoneNumber parameter that we'll use on our call view.

                                      
                                      
                                      
                                      
                                      src/main/resources/public/js/browser-calls.js

                                      Call a Customer

                                      src/main/resources/public/js/browser-calls.js

                                      Great! Now our agents are able to make calls to their customers. Next up, let's look at how to connect that call to a phone number.

                                      Connect the Call to a Phone Number

                                      Connect the call to a phone number

                                      Whenever one of our users makes a call, Twilio will send a POST request to the URL we set on our TwiML Application - in this case, /call/connect.

                                      We use TwiML to respond to the request and tell Twilio how to handle the call. Twilio will pass along the phoneNumber parameter from the previous step in its request, which we will then Dial in our TwiML.

                                            
                                            
                                            
                                            
                                            src/main/java/com/twilio/browsercalls/controllers/CallController.java

                                            Connect the call to a phone number

                                            src/main/java/com/twilio/browsercalls/controllers/CallController.java

                                            After our call view responds, Twilio completes the connection between our support agent's browser and the customer's phone. Let's go back to the browser and see how this is handled.

                                            Learn how to indicate a live call

                                            The call is live

                                            We use the Twilio.Device.connect() callback to update some UI elements to notify our users that they are in a call. This function receives a Connection object, which offers some additional details about the call.

                                                  
                                                  
                                                  
                                                  
                                                  src/main/resources/public/js/browser-calls.js

                                                  Indicate a live call

                                                  src/main/resources/public/js/browser-calls.js

                                                  And that's all for our browser-to-phone example. Next up, we will go even further and show a browser-to-browser example.

                                                  Have the customer start a call from their browser

                                                  Call a support agent (browser-to-browser)

                                                  Support tickets are useful, but sometimes a customer needs help right now. With just a little more work we let customers speak with a support agent live via a browser-to-browser call.

                                                  When a customer clicks the Call support button on the home page we again use Twilio.Device.connect() to initiate the call. This time we don't pass any additional parameters — our backend will route this call to our support agent.

                                                        
                                                        
                                                        
                                                        
                                                        src/main/resources/public/js/browser-calls.js

                                                        Call a Support Agent

                                                        src/main/resources/public/js/browser-calls.js

                                                        Setting up the browser-to-browser call was rather simple right? Now let's look at how our backend will route this call to our support agent.

                                                        Connect an Incoming Call from the Customer

                                                        Connect the call to the support agent's client

                                                        To allow our support agents to accept incoming calls we use an IncomingClientScope when generating their capability token, passing support_agent as the client's name.

                                                        When Twilio sends a POST request to our /call/connect endpoint, we can connect the call to our support agent by responding with a <Client> TwiML noun and the support_agent name.

                                                              
                                                              
                                                              
                                                              
                                                              What does this thing do?

                                                              Connect Incoming Calls

                                                              What does this thing do?

                                                              That's how we prepare everything for accepting incoming calls. Now we should go back in the browser and see how to handle the connection this time.

                                                              Answer the call

                                                              Answer the call

                                                              When our support agent's client receives an incoming call, it will trigger the function we defined on the Twilio.Device.incoming() callback.

                                                              The incoming connection will be in a pending state until we invoke its .accept() method, which we do in a function bound to the Answer Call button.

                                                              We also set a .accept() callback to update the UI once the call is live.

                                                                    
                                                                    
                                                                    
                                                                    
                                                                    src/main/resources/public/js/browser-calls.js

                                                                    Answer the call

                                                                    src/main/resources/public/js/browser-calls.js

                                                                    Great! Now we know how to work on both cases: browser-to-phone and browser-to-browser calls! Next up, we will see what happens when they decide to hang up the call.

                                                                    Hanging up the Call

                                                                    Hang up the Call

                                                                    In order to finish a call we invoke Twilio.Device.disconnectAll(), which we wired to the Hang up button in our UI.

                                                                    We also pass a callback function to Twilio.Device.disconnect() above, to reset some UI elements.

                                                                          
                                                                          
                                                                          
                                                                          
                                                                          src/main/resources/public/js/browser-calls.js

                                                                          Hang up the Call

                                                                          src/main/resources/public/js/browser-calls.js

                                                                          That's it! Our Spark application now powers browser-to-phone and browser-to-browser calls using Twilio Client.

                                                                          Where to Next?

                                                                          Where to next?

                                                                          If you're a Java developer working with Twilio, you might also enjoy these tutorials:

                                                                          Appointment Reminders

                                                                          Schedule appointment reminders to be sent via sms

                                                                          SMS and MMS Notifications

                                                                          Alert all administrators via SMS when a server outage occurs.

                                                                          Did this help?

                                                                          Thanks for checking this tutorial out! If you have any feedback to share with us please contact us on Twitter, we'd love to hear it.

                                                                          Mario Celi Jose Oliveros Agustin Camino Andrew Baker David Prothero Kat King
                                                                          Rate this page:

                                                                          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.