# Voice JavaScript SDK Reference Components

While the [quickstarts][qs] 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][qs].

## 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

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

   # Twilio account sid
   ACCOUNT_SID=ACxxxxxxxxxxxxxx

   # Twilio API key
   API_KEY_SID=SKxxxxxxxxxxxxxx

   # Twilio API secret
   API_KEY_SECRET=xxxxxxxxxxxxxx

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

   # Twilio auth token
   AUTH_TOKEN=xxxxxxxxxxxxxx

   # Caller ID
   CALLER_ID=+11234567890

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

   # Default identity to use
   DEFAULT_IDENTITY=alice

   # twilio-voice-ai-conversation
   # See https://platform.openai.com/settings/organization/api-keys
   OPENAI_API_KEY="sk-proj......."
   ```
4. 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][].

   ```bash
   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`.
5. 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`:
   ```text
   https://yourdomain/twilio-voice-dialer/twiml
   https://yourdomain/twilio-voice-basic-call-control/twiml
   https://yourdomain/twilio-voice-monitoring/twiml
   https://yourdomain/twilio-voice-ai-conversation/twiml
   https://yourdomain/twilio-voice-noise-cancellation/twiml
   ```

## Run the project locally

1. Start the local server under the `twilio-voice-js-reference-components` folder.
   ```bash
   npm start
   ```
2. 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`

[Twilio Voice JavaScript Reference Components]: https://github.com/twilio/twilio-voice-js-reference-components

[Web Components]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components

[how the JavaScript SDK works]: /docs/voice/sdks/javascript#how-it-works

[ngrok]: https://ngrok.com

[qs]: /docs/voice/sdks/javascript/get-started