Vite (JavaScript) | ElevenLabs Documentation

Questo tutorial ti guiderà nella creazione di un client web che può interagire con un agente ElevenLabs. Imparerai a implementare conversazioni vocali in tempo reale, permettendo agli utenti di parlare con un agente IA in grado di ascoltare, comprendere e rispondere in modo naturale tramite la sintesi vocale.

Vuoi sviluppare con React/Next.js? Consulta la nostra guida su Next.js

Cosa ti serve

Un agente ElevenLabs creato seguendo questa guida
npm installato sul tuo sistema locale
Conoscenze di base di JavaScript

Configurazione del progetto

Crea una directory per il progetto

Apri un terminale e crea una nuova directory per il progetto:

mkdir elevenlabs-conversational-ai
cd elevenlabs-conversational-ai

Inizializza npm e installa le dipendenze

Inizializza un nuovo progetto npm e installa i pacchetti richiesti:

npm init -y
npm install vite @elevenlabs/client

Configura la struttura di base del progetto

Aggiungi quanto segue al tuo package.json:

package.json

{
    "scripts": {
        ...
        "dev:frontend": "vite"
    }
}

Crea la seguente struttura di file:

elevenlabs-conversational-ai/
├── index.html
├── script.js
├── package-lock.json
├── package.json
└── node_modules

Implementazione dell’interfaccia di chat vocale

Crea l'interfaccia HTML

In index.html, configura una semplice interfaccia utente:

index.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>ElevenLabs Agents</title>
    </head>
    <body style="font-family: Arial, sans-serif; text-align: center; padding: 50px;">
        <h1>ElevenLabs Agents</h1>
        <div style="margin-bottom: 20px;">
            <button id="startButton" style="padding: 10px 20px; margin: 5px;">Start Conversation</button>
            <button id="stopButton" style="padding: 10px 20px; margin: 5px;" disabled>Stop Conversation</button>
        </div>
        <div style="font-size: 18px;">
            <p>Status: <span id="connectionStatus">Disconnected</span></p>
            <p>Agent is <span id="agentStatus">listening</span></p>
        </div>
        <script type="module" src="../images/script.js"></script>
    </body>
</html>

Implementa la logica della conversazione

In script.js, implementa la funzionalità:

script.js

import { Conversation } from '@elevenlabs/client';
const startButton = document.getElementById('startButton');
const stopButton = document.getElementById('stopButton');
const connectionStatus = document.getElementById('connectionStatus');
const agentStatus = document.getElementById('agentStatus');
let conversation;
async function startConversation() {
    try {
        // Request microphone permission
        await navigator.mediaDevices.getUserMedia({ audio: true });
        // Start the conversation
        conversation = await Conversation.startSession({
            agentId: 'YOUR_AGENT_ID', // Replace with your agent ID
            onConnect: () => {
                connectionStatus.textContent = 'Connected';
                startButton.disabled = true;
                stopButton.disabled = false;
            },
            onDisconnect: () => {
                connectionStatus.textContent = 'Disconnected';
                startButton.disabled = false;
                stopButton.disabled = true;
            },
            onError: (error) => {
                console.error('Error:', error);
            },
            onModeChange: (mode) => {
                agentStatus.textContent = mode.mode === 'speaking' ? 'speaking' : 'listening';
            },
        });
    } catch (error) {
        console.error('Failed to start conversation:', error);
    }
}
async function stopConversation() {
    if (conversation) {
        await conversation.endSession();
        conversation = null;
    }
}
startButton.addEventListener('click', startConversation);
stopButton.addEventListener('click', stopConversation);

Avvia il server frontend

npm run dev:frontend

Assicurati di sostituire 'YOUR_AGENT_ID' con l’ID effettivo del tuo agente ElevenLabs.

(Facoltativo) Autenticazione con un URL firmato

Questo passaggio di autenticazione è necessario solo per gli agenti privati. Se usi un agente pubblico, puoi saltare questa sezione e usare direttamente agentId nella chiamata startSession.

Crea le variabili d'ambiente

Crea un file .env nella directory principale del progetto:

.env

ELEVENLABS_API_KEY=your-api-key-here
AGENT_ID=your-agent-id-here

Assicurati di aggiungere .env al file .gitignore per evitare di eseguire accidentalmente il commit di credenziali sensibili.

Configura il backend

Installa dipendenze aggiuntive:

npm install express cors dotenv

Crea una nuova cartella denominata backend:

elevenlabs-conversational-ai/
├── backend
...

Crea il server

backend/server.js

require("dotenv").config();
const express = require("express");
const cors = require("cors");
const app = express();
app.use(cors());
app.use(express.json());
const PORT = process.env.PORT || 3001;
app.get("/api/get-signed-url", async (req, res) => {
    try {
        const response = await fetch(
            `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
            {
                headers: {
                    "xi-api-key": process.env.ELEVENLABS_API_KEY,
                },
            }
        );
        if (!response.ok) {
            throw new Error("Failed to get signed URL");
        }
        const data = await response.json();
        res.json({ signedUrl: data.signed_url });
    } catch (error) {
        console.error("Error:", error);
        res.status(500).json({ error: "Failed to generate signed URL" });
    }
});
app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
});

Aggiorna il codice client

Modifica il tuo script.js per recuperare e usare l’URL firmato:

script.js

// ... existing imports and variables ...
async function getSignedUrl() {
    const response = await fetch('http://localhost:3001/api/get-signed-url');
    if (!response.ok) {
        throw new Error(`Failed to get signed url: ${response.statusText}`);
    }
    const { signedUrl } = await response.json();
    return signedUrl;
}
async function startConversation() {
    try {
        await navigator.mediaDevices.getUserMedia({ audio: true });
        const signedUrl = await getSignedUrl();
        conversation = await Conversation.startSession({
            signedUrl,
            // agentId has been removed...
            onConnect: () => {
                connectionStatus.textContent = 'Connected';
                startButton.disabled = true;
                stopButton.disabled = false;
            },
            onDisconnect: () => {
                connectionStatus.textContent = 'Disconnected';
                startButton.disabled = false;
                stopButton.disabled = true;
            },
            onError: (error) => {
                console.error('Error:', error);
            },
            onModeChange: (mode) => {
                agentStatus.textContent = mode.mode === 'speaking' ? 'speaking' : 'listening';
            },
        });
    } catch (error) {
        console.error('Failed to start conversation:', error);
    }
}
// ... rest of the code ...

Gli URL firmati scadono dopo un breve periodo. Tuttavia, tutte le conversazioni avviate prima della scadenza proseguiranno senza interruzioni. In un ambiente di produzione, implementa una gestione degli errori e una logica di aggiornamento degli URL adeguate per avviare nuove conversazioni.

Aggiorna package.json

package.json

{
    "scripts": {
        ...
        "dev:backend": "node backend/server.js",
        "dev": "npm run dev:frontend & npm run dev:backend"
    }
}

Esegui l'applicazione

Avvia l’applicazione con:

npm run dev

Passaggi successivi

Ora che hai un’implementazione di base, puoi:

Aggiungere feedback visivo per l’attività vocale
Implementare la gestione degli errori e la logica dei tentativi
Aggiungere una visualizzazione della cronologia della chat
Personalizzare l’interfaccia utente in base al tuo brand

Per funzionalità e opzioni di personalizzazione più avanzate, consulta il pacchetto @elevenlabs/client.