Next.JS | ElevenLabs Documentation

Den här guiden hjälper dig att skapa en webbklient som kan interagera med en ElevenLabs-agent. Du lär dig implementera röstsamtal i realtid, så att användare kan prata med en AI-agent som kan lyssna, förstå och svara naturligt med talsyntes.

Det här behöver du

En ElevenLabs-agent som skapats enligt den här guiden
npm installerat på ditt lokala system.
Vi använder Typescript i den här guiden, men du kan använda Javascript om du föredrar det.

Vill du ha ett komplett exempel? Se vår Next.js-demo på GitHub.

Konfiguration

Skapa ett nytt Next.js-projekt

Öppna ett terminalfönster och kör följande kommando:

npm create next-app my-conversational-agent

Du får svara på några frågor om hur projektet ska byggas. I den här guiden följer vi standardförslagen.

Gå till projektkatalogen

cd my-conversational-agent

Installera ElevenLabs-beroendet

npm install @elevenlabs/react

Testa konfigurationen

Kör följande kommando för att starta utvecklingsservern och öppna den angivna URL:en i webbläsaren:

npm run dev

Implementera ElevenLabs Agents

Skapa konversationskomponenten

Skapa en ny fil, 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>
  );
}

Uppdatera huvudsidan

Ersätt innehållet i app/page.tsx med:

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>
  );
}

(Valfritt) Autentisera agenter med en signerad URL

Detta autentiseringssteg krävs bara för privata agenter. Om du använder en offentlig agent kan du hoppa över det här avsnittet och använda agentId direkt i anropet till startSession.

Om du använder en privat agent som kräver autentisering måste du generera en signerad URL från din server. Det här avsnittet förklarar hur du konfigurerar det.

Det här behöver du

Ett ElevenLabs-konto och en API-nyckel. Registrera dig här.

Skapa miljövariabler

Skapa en .env.local-fil i projektets rot:

.env.local

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

Se till att lägga till .env.local i din .gitignore-fil för att undvika att känsliga autentiseringsuppgifter av misstag skickas till versionshanteringen.
Exponera aldrig din API-nyckel i klientkod. Håll den alltid säker på servern.

Skapa en API-rutt

Skapa en ny fil, 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 }
    );
  }
}

Uppdatera Conversation-komponenten

Ändra din conversation.tsx för att hämta och använda den signerade URL:en:

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 ...
}

Signerade URL:er upphör att gälla efter en kort tid. Samtal som påbörjats före utgångstiden fortsätter dock utan avbrott. I en produktionsmiljö bör du implementera korrekt felhantering och logik för att uppdatera URL:er när nya samtal startas.

Nästa steg

Nu när du har en grundläggande implementering kan du:

Lägga till visuell återkoppling för röstaktivitet
Implementera felhantering och logik för nya försök
Lägga till en visning av chatthistorik
Anpassa gränssnittet efter ditt varumärke

För mer avancerade funktioner och anpassningsalternativ, se paketet @elevenlabs/react.