> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Integrazione Vonage

## Panoramica

Collega ElevenLabs Agents alle chiamate Vonage Voice API o Video API tramite un'[applicazione connettore WebSocket](https://github.com/nexmo-se/elevenlabs-agent-ws-connector). In questo modo abiliti lo streaming audio bidirezionale in tempo reale per casi d'uso come chiamate PSTN, SIP trunk e client WebRTC.

## Come funziona

Il connettore Node.js collega Vonage ed ElevenLabs:

1. Vonage avvia una connessione WebSocket al connettore per una chiamata attiva.
2. Il connettore stabilisce una connessione WebSocket all'endpoint ElevenLabs Agents.
3. L'audio viene inoltrato: Vonage (L16) -> Connettore -> ElevenLabs (base64) e viceversa.
4. Il connettore gestisce gli eventi della conversazione (`user_transcript`, `agent_response`, `interruption`).

## Configurazione

### 1. Ottieni le credenziali ElevenLabs

* **Chiave API**: le chiavi API si trovano nella [scheda API Keys della pagina Developers](https://elevenlabs.io/app/developers), accessibile dalla barra laterale.
* **ID dell'agente**: trova l'agente nella [dashboard ElevenAgents](https://elevenlabs.io/app/agents/agents/). Dopo averlo selezionato, fai clic sul pulsante delle impostazioni e seleziona "Copy Agent ID".

### 2. Configura il connettore

Clona il repository e configura il file dell'ambiente.

```bash
git clone https://github.com/nexmo-se/elevenlabs-agent-ws-connector.git
cd elevenlabs-agent-ws-connector
cp .env.example .env
```

Aggiungi le tue credenziali a `.env`:

**`.env`**

```bash title=".env"
ELEVENLABS_API_KEY = YOUR_API_KEY;
ELEVENLABS_AGENT_ID = YOUR_AGENT_ID;
```

Installa le dipendenze: `npm install`.

### 3. Esponi il connettore (sviluppo locale)

Usa ngrok, o un servizio simile, per creare un URL pubblico per il connettore (porta predefinita 6000).

```bash
ngrok http 6000
```

Prendi nota dell'URL pubblico `Forwarding` (ad esempio, `xxxxxxxx.ngrok-free.app`). **Non includere `https://`** durante la configurazione di Vonage.

### 4. Avvia il connettore

Avvia l'applicazione:

```bash
node elevenlabs-agent-ws-connector.cjs
```

### 5. Configura l'applicazione vocale Vonage

La tua app Vonage deve connettersi all'endpoint WebSocket del connettore (`wss://YOUR_CONNECTOR_HOSTNAME/socket`). Questo è l'URL ngrok del passaggio 3.

* **Usa l'app di esempio**: configura l'[app Vonage di esempio](https://github.com/nexmo-se/voice-to-ai-engines) con `PROCESSOR_SERVER` impostato sul nome host del tuo connettore.
* **Aggiorna un'app esistente**: modifica il tuo [Nexmo Call Control Object](https://developer.vonage.com/en/voice/voice-api/ncco-reference) per includere un'azione `connect` indirizzata all'URI WebSocket del connettore (`wss://...`) con `content-type: audio/l16;rate=16000`. Passa i parametri query necessari, come `peer_uuid` e `webhook_url`.

### 6. Testa

Effettua una chiamata in entrata o in uscita tramite l'applicazione Vonage per interagire con l'agente ElevenLabs.

## Deployment cloud

Per la produzione, esegui il deployment del connettore presso un provider di hosting stabile (ad esempio, Vonage Cloud Runtime) con un hostname pubblico.