Next.JS

Scopri come creare un'applicazione web che consente conversazioni vocali con gli agenti IA di ElevenLabs

Questo tutorial ti guiderà nella creazione di un client web in grado di 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 sintesi vocale.

Cosa ti serve

Un agente ElevenLabs creato seguendo questa guida
npm installato sul tuo sistema locale.
Per questo tutorial useremo Typescript, ma puoi usare Javascript se preferisci.

Cerchi un esempio completo? Dai un’occhiata alla nostra demo Next.js su GitHub.

Configurazione

Crea un nuovo progetto Next.js

Apri una finestra del terminale ed esegui il seguente comando:

npm create next-app my-conversational-agent

Ti verranno poste alcune domande su come creare il progetto. Per questo tutorial seguiremo le opzioni predefinite.

Accedi alla directory del progetto

cd my-conversational-agent

Installa la dipendenza di ElevenLabs

npm install @elevenlabs/react

Prova la configurazione

Esegui il seguente comando per avviare il server di sviluppo e apri l’URL fornito nel browser:

npm run dev

Implementa gli agenti ElevenLabs

Crea il componente della conversazione

Crea un nuovo file app/components/conversation.tsx:

app/components/conversation.tsx

'use client';
import { useConversation } from '@elevenlabs/react';
import { useCallback } from 'react';
export function Conversation() {
  const conversation = useConversation({
    onConnect: () => console.log('Connected'),
    onDisconnect: () => console.log('Disconnected'),
    onMessage: (message) => console.log('Message:', message),
    onError: (error) => console.error('Error:', error),
  });
  const startConversation = useCallback(async () => {
    try {
      // Request microphone permission
      await navigator.mediaDevices.getUserMedia({ audio: true });
      // Start the conversation with your agent
      await conversation.startSession({
        agentId: 'YOUR_AGENT_ID', // Replace with your agent ID
        userId: 'YOUR_CUSTOMER_USER_ID', // Optional field for tracking your end user IDs
      });
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  }, [conversation]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  return (
    <div className="flex flex-col items-center gap-4">
      <div className="flex gap-2">
        <button
          onClick={startConversation}
          disabled={conversation.status === 'connected'}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
        >
          Start Conversation
        </button>
        <button
          onClick={stopConversation}
          disabled={conversation.status !== 'connected'}
          className="px-4 py-2 bg-red-500 text-white rounded disabled:bg-gray-300"
        >
          Stop Conversation
        </button>
      </div>
      <div className="flex flex-col items-center">
        <p>Status: {conversation.status}</p>
        <p>Agent is {conversation.isSpeaking ? 'speaking' : 'listening'}</p>
      </div>
    </div>
  );
}

Aggiorna la pagina principale

Sostituisci il contenuto di app/page.tsx con:

app/page.tsx

'use client';
import { ConversationProvider } from '@elevenlabs/react';
import { Conversation } from './components/conversation';
export default function Home() {
  return (
    <ConversationProvider>
      <main className="flex min-h-screen flex-col items-center justify-between p-24">
        <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm">
          <h1 className="text-4xl font-bold mb-8 text-center">
            ElevenLabs Agents
          </h1>
          <Conversation />
        </div>
      </main>
    </ConversationProvider>
  );
}

(Facoltativo) Autentica gli agenti 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.

Se usi un agente privato che richiede l’autenticazione, dovrai generare un URL firmato dal tuo server. Questa sezione spiega come configurarlo.

Cosa ti serve

Un account ElevenLabs e una chiave API. Registrati qui.

Crea le variabili d'ambiente

Crea un file .env.local nella root del progetto:

.env.local

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

Assicurati di aggiungere .env.local al file .gitignore per evitare di eseguire accidentalmente il commit di credenziali sensibili nel controllo versione.
Non esporre mai la tua chiave API nel codice lato client. Conservala sempre al sicuro sul server.

Crea una route API

Crea un nuovo file app/api/get-signed-url/route.ts:

app/api/get-signed-url/route.ts

import { NextResponse } from 'next/server';
export async function GET() {
  try {
    const response = await fetch(
      `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.NEXT_PUBLIC_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();
    return NextResponse.json({ signedUrl: data.signed_url });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to generate signed URL' },
      { status: 500 }
    );
  }
}

Aggiorna il componente Conversation

Modifica il tuo conversation.tsx per recuperare e usare l’URL firmato:

app/components/conversation.tsx

// ... existing imports ...
export function Conversation() {
  // ... existing conversation setup ...
  const getSignedUrl = async (): Promise<string> => {
    const response = await fetch("/api/get-signed-url");
    if (!response.ok) {
      throw new Error(`Failed to get signed url: ${response.statusText}`);
    }
    const { signedUrl } = await response.json();
    return signedUrl;
  };
  const startConversation = useCallback(async () => {
    try {
      // Request microphone permission
      await navigator.mediaDevices.getUserMedia({ audio: true });
      const signedUrl = await getSignedUrl();
      // Start the conversation with your signed url
      await conversation.startSession({
        signedUrl,
      });
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  }, [conversation]);
  // ... rest of the component ...
}

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

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 di ripetizione
Aggiungere una visualizzazione della cronologia della chat
Personalizzare l’interfaccia utente in base al tuo brand

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