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

# Next.JS

Dieses Tutorial zeigt Ihnen, wie Sie einen Webclient erstellen, der mit einem ElevenLabs-Agenten interagieren kann. Sie lernen, Echtzeit-Sprachunterhaltungen zu implementieren, damit Nutzer mit einem KI-Agenten sprechen können, der zuhören, verstehen und mithilfe von Sprachsynthese natürlich antworten kann.

## Was Sie benötigen

1. Einen ElevenLabs-Agenten, den Sie gemäß [dieser Anleitung](/docs/de/eleven-agents/quickstart) erstellt haben
2. `npm`, installiert auf Ihrem lokalen System
3. Wir verwenden in diesem Tutorial Typescript, Sie können aber auch Javascript verwenden.

> **Note**
>
> Sie suchen ein vollständiges Beispiel? Sehen Sie sich unsere [Next.js-Demo auf GitHub](https://github.com/elevenlabs/examples/tree/main/agents/nextjs/quickstart) an.

![](/docs/_fern-img/c1bc26a84d079cebcdfe6b4eb602bd27476d5afc92419e9ddfb92b755ca8058e.webp)

## Einrichtung

#### Neues Next.js-Projekt erstellen

Öffnen Sie ein Terminal und führen Sie den folgenden Befehl aus:

```bash
npm create next-app my-conversational-agent
```

Sie werden einige Fragen zur Einrichtung Ihres Projekts beantworten. Für dieses Tutorial verwenden wir die Standardvorschläge.

#### Zum Projektverzeichnis wechseln

```shell
cd my-conversational-agent
```

#### ElevenLabs-Abhängigkeit installieren

```shell
npm install @elevenlabs/react
```

#### Einrichtung testen

Führen Sie den folgenden Befehl aus, um den Entwicklungsserver zu starten, und öffnen Sie die bereitgestellte URL in Ihrem Browser:

```shell
npm run dev
```

![](/docs/_fern-img/537e2c5609df75b2fd15bf3a37c86da75410de053dfb0c76267a72d7b8d9914a.webp)

## ElevenLabs Agents implementieren

#### Unterhaltungskomponente erstellen

Erstellen Sie eine neue Datei `app/components/conversation.tsx`:

**`app/components/conversation.tsx`**

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

#### Hauptseite aktualisieren

Ersetzen Sie den Inhalt von `app/page.tsx` durch:

**`app/page.tsx`**

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

#### (Optional) Agenten mit einer signierten URL authentifizieren

> **Note**
>
> Dieser Authentifizierungsschritt ist nur für private Agenten erforderlich. Wenn Sie einen öffentlichen Agenten verwenden, können Sie
> diesen Abschnitt überspringen und die `agentId` direkt im `startSession`-Aufruf verwenden.

Wenn Sie einen privaten Agenten verwenden, der eine Authentifizierung erfordert, müssen Sie
auf Ihrem Server eine signierte URL generieren. Dieser Abschnitt erklärt die Einrichtung.

### Was Sie benötigen

1. Ein ElevenLabs-Konto und einen API-Schlüssel. Registrieren Sie sich [hier](https://elevenlabs.io/app/sign-up).

#### Umgebungsvariablen erstellen

Erstellen Sie im Stammverzeichnis Ihres Projekts eine `.env.local`-Datei:

**`.env.local`**

```yaml .env.local
ELEVENLABS_API_KEY=your-api-key-here
NEXT_PUBLIC_AGENT_ID=your-agent-id-here
```

> **Warning**
>
> 1. Fügen Sie `.env.local` unbedingt zu Ihrer `.gitignore`-Datei hinzu, damit sensible Zugangsdaten nicht versehentlich in die Versionsverwaltung übertragen werden.
> 2. Legen Sie Ihren API-Schlüssel niemals im clientseitigen Code offen. Bewahren Sie ihn immer sicher auf dem Server auf.

#### API-Route erstellen

Erstellen Sie eine neue Datei `app/api/get-signed-url/route.ts`:

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

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

#### Conversation-Komponente aktualisieren

Ändern Sie Ihre `conversation.tsx`, um die signierte URL abzurufen und zu verwenden:

**`app/components/conversation.tsx`**

```tsx app/components/conversation.tsx {5-12,19,23}
// ... 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 ...
}
```

> **Warning**
>
> Signierte URLs laufen nach kurzer Zeit ab. Unterhaltungen, die vor dem Ablauf gestartet wurden, werden jedoch ohne Unterbrechung fortgesetzt. Implementieren Sie in einer Produktionsumgebung eine geeignete Fehlerbehandlung und Logik zum Aktualisieren der URL, um neue Unterhaltungen zu starten.

## Nächste Schritte

Nachdem Sie jetzt eine grundlegende Implementierung haben, können Sie:

1. Visuelles Feedback für Sprachaktivität hinzufügen
2. Fehlerbehandlung und Wiederholungslogik implementieren
3. Eine Anzeige für den Chatverlauf hinzufügen
4. Die Benutzeroberfläche an Ihre Marke anpassen

> **Info**
>
> Weitere erweiterte Funktionen und Anpassungsoptionen finden Sie im
> Paket [@elevenlabs/react](https://www.npmjs.com/package/@elevenlabs/react).