# Voice JavaScript SDK: Reference Components

## Overview

While the [quickstarts](/docs/voice/sdks/javascript/get-started) 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](https://developer.mozilla.org/en-US/docs/Web/API/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.

Before proceeding, take a moment to explore [how the JavaScript SDK works](/docs/voice/sdks/javascript#how-it-works) and review the [getting started page](/docs/voice/sdks/javascript/get-started) to familiarize yourself with key concepts.

* [Use cases](#use-cases)
* [Installation](#installation)
* [Running locally](#run-the-project-locally)

## Use cases

The reference components demonstrate several common Twilio Voice use cases. For detailed implementation guidance, visit the [Twilio Voice JavaScript Reference Components](https://github.com/twilio/twilio-voice-js-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

## Installation

1. Clone the [Twilio Voice JavaScript Reference Components](https://github.com/twilio/twilio-voice-js-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. For details about each variable, see the [quickstart](https://www.twilio.com/docs/voice/sdks/javascript/get-started).

```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. In the Twilio Console, open your **TwiML App** settings and set **Voice Request URL** to the endpoint for the component you want to test:

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

## 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](http://localhost:3030/twilio-voice-dialer?identity=bob)
* Basic call control: [http://localhost:3030/twilio-voice-basic-call-control?identity=bob](http://localhost:3030/twilio-voice-basic-call-control?identity=bob)
* Monitoring: [http://localhost:3030/twilio-voice-monitoring?identity=bob](http://localhost:3030/twilio-voice-monitoring?identity=bob)
* Voice AI Conversation: [http://localhost:3030/twilio-voice-ai-conversation?identity=bob](http://localhost:3030/twilio-voice-ai-conversation?identity=bob)