Voice JavaScript SDK Reference Components

While the quickstarts enable you to quickly set up a functional application for making and receiving phone calls via a web browser in just a few minutes, the reference components offer flexible building blocks for your Twilio Voice applications. Designed around common Twilio Voice use cases, these components leverage Web Components to showcase integrated backend and frontend implementations. You can easily incorporate these components into your application or use them as a foundation for your development needs.

These components might reference third-party services or open source software outside of Twilio. Twilio provides these references as-is without any warranties. You must review, comply with, and maintain appropriate licenses for any such third-party services or open source tools. Twilio possesses no liability whatsoever for any such third-party services or open source software.

Before proceeding, familiarize yourself with key concepts: how the JavaScript SDK works and getting started.

Use cases

The reference components demonstrate several common Twilio Voice use cases. To review detailed implementations, see the Twilio Voice JavaScript Reference Components repository. These use cases include:

Dialer
- Place outgoing calls
- Receive incoming calls
Basic call control (uses Conference)
- Perform cold or warm transfers
- Add or remove participants
- Hold and Resume a call
- Mute and Unmute a call
Monitoring (uses Conference)
- Observe call progress
- Track conference call status
- View quality metrics
- Receive warnings
- View errors
Voice AI Conversation
- Place an outbound call and connect to an agent
- Provide a WebSocket server
- Basic OpenAI integration
Noise Cancellation
- Apply RNNoise noise suppression to outgoing microphone audio
- Apply RNNoise noise suppression to incoming call audio
- Independently enable or disable noise suppression for each audio direction during an active call

Installation

Clone the Twilio Voice JavaScript Reference Components GitHub repository.
git clone https://github.com/twilio/twilio-voice-js-reference-components.git
Install the dependencies.
npm install
Copy example.env to .env, then supply the required values. To learn about each variable, see the quickstart.
View an example .env file
1
# Port number to run the server on
2
PORT=3030
3

4
# Twilio account sid
5
ACCOUNT_SID=ACxxxxxxxxxxxxxx
6

7
# Twilio API key
8
API_KEY_SID=SKxxxxxxxxxxxxxx
9

10
# Twilio API secret
11
API_KEY_SECRET=xxxxxxxxxxxxxx
12

13
# Twilio TwiML App SID
14
# The Voice Request URL must point to one of the /twiml endpoints listed later in this guide.
15
# For details, see https://www.twilio.com/docs/voice/sdks/javascript#twiml-applications
16
APP_SID=APxxxxxxxxxxxxxx
17

18
# Twilio auth token
19
AUTH_TOKEN=xxxxxxxxxxxxxx
20

21
# Caller ID
22
CALLER_ID=+11234567890
23

24
# Public base URL that Twilio can reach.
25
# If you run the components locally, use a tunneling service such as ngrok.
26
# Do not include the scheme (https:// or wss://) in the URL.
27
CALLBACK_BASE_URL=foo.ngrok.dev
28

29
# Default identity to use
30
DEFAULT_IDENTITY=alice
31

32
# twilio-voice-ai-conversation
33
# See https://platform.openai.com/settings/organization/api-keys
34
OPENAI_API_KEY="sk-proj......."
Expose your local server to the public internet so Twilio can reach it for webhooks. If you run the components locally, use a tunneling service such as ngrok.
ngrok http 3030
Copy the forwarding host that ngrok returns and set it as CALLBACK_BASE_URL in your .env — without the https:// scheme, since the code prepends https:// / wss:// itself. If you changed PORT, tunnel to that port instead of 3030.

In the Twilio Console, open your TwiML App settings and set Voice Request URL to the endpoint for the component you want to test, using your public host from step 4 in place of yourdomain:

1https://yourdomain/twilio-voice-dialer/twiml
2https://yourdomain/twilio-voice-basic-call-control/twiml
3https://yourdomain/twilio-voice-monitoring/twiml
4https://yourdomain/twilio-voice-ai-conversation/twiml
5https://yourdomain/twilio-voice-noise-cancellation/twiml

Run the project locally

Start the local server under the twilio-voice-js-reference-components folder.
npm start
Open a browser and navigate to a component URL.
- Dialer: http://localhost:3030/twilio-voice-dialer?identity=bob
- Basic call control: http://localhost:3030/twilio-voice-basic-call-control?identity=bob
- Monitoring: http://localhost:3030/twilio-voice-monitoring?identity=bob
- Voice AI Conversation: http://localhost:3030/twilio-voice-ai-conversation?identity=bob
- Noise Cancellation: http://localhost:3030/twilio-voice-noise-cancellation?identity=bob