You're viewing the documentation for the 2.X version of the Voice JavaScript SDK. View the Migration Guide to learn how to migrate from 1.X to 2.X or view the 1.x-specific documentation.
Ready to add voice communications to your front-end web applications? When you complete one of these Quickstarts, you'll have a fully running application that can make and receive phone calls from a web browser.
Before you start building, you should familiarize yourself with how the JavaScript SDK works.
While the JavaScript SDK allows you to make calls from your browser, you still need some sort of back-end web server to provide your application with Access Tokens and to provide Twilio with TwiML instructions. The Quickstart repositories listed below include web servers in a variety of frameworks/languages.
Choose your preferred backend framework below:
A Quickstart should serve as a starting point for creating your Twilio-powered application. A Quickstart application is not intended to provide a production-ready application, nor is it intended to cover every business use case.
To learn more about the Voice JavaScript SDK, please refer to the documentation:
If you would like to see the Voice JavaScript SDK in action using Twilio's serverless environment, follow the instructions below.
The Twilio Command Line Interface, CLI, allows you to interact with the Twilio API from your terminal. It allows you to manage and configure all of your Twilio tools, which is what we are going to be using it for in our case.
The suggested way to install twilio-cli
on macOS is to use Homebrew. If you don't already have it installed, visit the Homebrew site for installation instructions and then return here.
Once you have installed Homebrew, run the following command to install twilio-cli
:
brew tap twilio/brew && brew install twilio
For other installation methods, see the Twilio CLI Quickstart.
The Twilio CLI supports plugins, which give you additional control and functionality.
We're going to install the serverless plugin which allows you to seamlessly deploy functions from your local machine to Twilio Functions and Assets, Twilio's serverless environment.
Execute the following command in your terminal:
twilio plugins:install @twilio-labs/plugin-serverless
Make sure you have the latest versions of the Twilio CLI and the Serverless Plugin installed.
The serverless plugin allows you to initialize an application from a template. The template we are going to use has everything we need, which includes the following:
We'll take a look in more detail after we get things up and running.
Create your app by executing the following command in your terminal:
twilio serverless:init quickstart-voice-javascript-sdk --template="voice-javascript-sdk"
This will create a new directory called quickstart-voice-javascript-sdk
that will contain all of your code.
Change directories into that new directory with the following command:
cd quickstart-voice-javascript-sdk
The serverless plugin allows you to deploy code from your local machine to Twilio Functions and Assets. Once the application is deployed, you'll be able to access your hosted application.
To deploy your application, run the following command in your terminal:
twilio serverless:deploy
This command will create a Service, which is a container for your Functions, Assets, and Environments within Twilio Serverless.
The command will output a list of the Twilio Functions and Assets that have been deployed to your development environment.
Run twilio serverless:deploy
any time you want to deploy changes to your application.
When you deployed your application, you were presented with a list of URLs. Make note of the prefix, this is custom to your deployment.
default
(You can change this, we'll do that later)
The initialization process will create and wire up all the necessary tools to make browser-based calling work.
This page will now host a checklist that will validate that your environment is working properly. It also provides handy links to get to the items that were automatically initialized for you.
You should note that there is a failing check, and that's because we haven't yet changed the default password. We'll do that here shortly, but first let's explore your new application.
Your example application is now up and running at /index.html. Open it up in your browser.
You'll see that an Access Token is requested, and you should see a notification when it receives one. It will state your "Twilio.Device is ready!"
Go ahead and use the interface to give yourself a call. You should be asked to grant access to your microphone and speakers.
Note that the example application is using the user name of the_user_id. The Twilio Function we are using to generate the Access Token is not using any sort of authentication check. This is something that you will need to implement with your user management system.
We should definitely change that admin password. On your local machine edit the file named .env.
There is an entry for ADMIN_PASSWORD
, change that to something other than default.
1ADMIN_PASSWORD=SOME-NEW-PASSWORD-HERE2
Save your changes.
Deploy the changes using the following command in your terminal:
1twilio serverless:deploy2
And after it is deployed revisit your /admin/index.html page, use your new password, and you will see that your checks are now all green. You did it!
Anytime you make a change to your example application, remember to save and re-deploy.
Now that you've seen things working, we'd like to invite you to explore how it's working.
First head over to your local folder and take a look at the two client side files assets/index.html and assets/quickstart.js. Note that the index.html file includes the following script tag:
<script src="https://cdn.jsdelivr.net/npm/@twilio/voice-sdk@2.0.1/dist/twilio.min.js"></script>
This is the Voice JavaScript SDK library.
In the quickstart.js file, you'll notice that the Device is initialized with a token. It's pointing to a serverless Function that can be found at /functions/voice-token.js. This file mints an Access Token for you based on a REST API Key and Secret that was generated during initialization. You'll see that it also contains a VoiceGrant
that enables incoming and outgoing calls through a specific TwiML Application. This is the Twilio Voice JavaScript SDK and you can see it in use in the heavily documented assets/quickstart.js.
If you head back over to your admin page, /admin/index.html, you'll see a link to a TwiML Application that was created for you. A TwiML Application allows you to specify what happens when a call is placed and when one is received. TwiML is the Twilio Markup Language that instructs Twilio what to do with your call in that moment.
We provide this TwiML via a Function that can be found in your functions/client-voice-twiml-app.js
. We wired up your TwiML application to run this function on Incoming and Outgoing Voice calls. This function can dial either a client in your same application or a number. When making the outbound call it will use your CALLER_ID
.