> ## Documentation Index
> Fetch the complete documentation index at: https://staging.docs.vocode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# React Quickstart

> Get up and running using React

# Installation

`npm install vocode`

Or, start from our [Replit template](https://replit.com/@vocode/Simple-Conversation).

# Usage

## Setting up the conversation

### Hosted

You'll need to get an API key from our [dashboard](https://app.vocode.dev/) to get started. Similar to the Python Quickstart, we provide a TypeScript interface for the conversation configuration.

```javascript theme={null}
import {
  AudioDeviceConfig,
  ConversationConfig,
  ChatGPTAgentConfig,
  DeepgramTranscriberConfig,
  AzureSynthesizerConfig,
  VocodeConfig,
} from "vocode";

const transcriberConfig: Omit<
  DeepgramTranscriberConfig,
  "samplingRate" | "audioEncoding"
> = {
  type: "transcriber_deepgram",
  chunkSize: 2048,
};
const agentConfig: ChatGPTAgentConfig = {
  type: "agent_chat_gpt",
  initialMessage: {
    type: "message_base",
    text: "Hello!",
  },
  promptPreamble: "The AI is having a pleasant conversation about life",
};
const synthesizerConfig: Omit<
  AzureSynthesizerConfig,
  "samplingRate" | "audioEncoding"
> = {
  type: "synthesizer_azure",
  shouldEncodeAsWav: true,
};
const vocodeConfig: VocodeConfig = {
  apiKey: process.env.REACT_APP_VOCODE_API_KEY || "",
};
const audioDeviceConfig: AudioDeviceConfig = {};
```

#### Running the conversation

We provide a React hook to facilitate conversations created from the configuration above.

```javascript theme={null}
import { useConversation } from "vocode";

const { status, start, stop, analyserNode } = useConversation({
  transcriberConfig,
  agentConfig,
  synthesizerConfig,
  vocodeConfig,
  audioDeviceConfig,
});
```

* `start` opens the microphone stream and starts sending audio from the conversation to the user
* `stop` closes the microphone and speaker streams
* `status` is an enum that contains the status of the conversation, one of `idle`, `connecting`, `connected`, and `error`
* `analyserNode` is an object (defined by the Web Audio API [here](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode)) that allows for audio visualizations based on the audio output of the conversation

### Self-hosted

Our self-hosted backend allows you to expose a websocket route in the same format that our hosted backend does. This allows you to deploy any agent you'd to into the conversation.

To get started, clone the Vocode repo or copy the [client backend app](https://github.com/vocodedev/vocode-python/tree/main/apps/client_backend) directory.

#### Environment

Copy the `.env.template` and add your API keys.

```
cp .env.template .env
```

You'll need:

* [Deepgram](https://deepgram.com) (for speech transcription)
* [OpenAI](https://platform.openai.com) (for the underlying agent)
* [Azure](https://azure.microsoft.com/en-us/products/cognitive-services/text-to-speech/) (for speech synthesis)

```
DEEPGRAM_API_KEY=
OPENAI_API_KEY=
AZURE_SPEECH_KEY=
AZURE_SPEECH_REGION=
```

#### Running with Docker

From the `client_backend` directory:

```
docker build -t vocode-client-backend .
docker run --env-file=.env -p 3000:3000 -t vocode-client-backend
```

#### Running with Python

```
pip3 install vocode
uvicorn main:app --port 3000
```

You now have a server with a Vocode websocket route at localhost:3000! You can now use the `useConversation` hook with your self-hosted backend as follows:

```javascript theme={null}
const { status, start, stop, analyserNode } = useConversation({
  backendUrl: "<YOUR_BACKEND_URL>", // looks like ws://localhost:3000/conversation or wss://asdf1234.ngrok.app/conversation if using ngrok
  audioDeviceConfig: {},
});
```

# Demo installation and setup

Clone the `vocode-react-demo` [repository](https://github.com/vocodedev/vocode-react-demo).

```
$ git clone https://github.com/vocodedev/vocode-react-demo.git
```

Run npm install inside the directory to download all of the dependencies.

```
$ npm install
```

Set your Client SDK key inside of your `.env`

```
REACT_APP_VOCODE_API_KEY=YOUR KEY HERE
```

Start the application

```
$ npm start
```