> 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

Ce tutoriel vous guidera dans la création d’un client web capable d’interagir avec un agent ElevenLabs. Vous apprendrez à mettre en œuvre des conversations vocales en temps réel, permettant aux utilisateurs de parler à un agent IA capable d’écouter, de comprendre et de répondre naturellement grâce à la synthèse vocale.

## Prérequis

1. Un agent ElevenLabs créé en suivant [ce guide](/docs/fr/eleven-agents/quickstart)
2. `npm` installé sur votre système local.
3. Nous utiliserons Typescript dans ce tutoriel, mais vous pouvez utiliser Javascript si vous le préférez.

> **Note**
>
> Vous cherchez un exemple complet ? Consultez notre [démo Next.js sur GitHub](https://github.com/elevenlabs/examples/tree/main/agents/nextjs/quickstart).

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

## Configuration

#### Créer un projet Next.js

Ouvrez une fenêtre de terminal et exécutez la commande suivante :

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

Elle vous posera quelques questions sur la façon de créer votre projet. Pour ce tutoriel, nous suivrons les suggestions par défaut.

#### Accéder au répertoire du projet

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

#### Installer la dépendance ElevenLabs

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

#### Tester la configuration

Exécutez la commande suivante pour démarrer le serveur de développement et ouvrir l’URL fournie dans votre navigateur :

```shell
npm run dev
```

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

## Mettre en œuvre les agents ElevenLabs

#### Créer le composant de conversation

Créez un fichier `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>
  );
}
```

#### Mettre à jour la page principale

Remplacez le contenu de `app/page.tsx` par :

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

#### (Facultatif) Authentifier les agents avec une URL signée

> **Note**
>
> Cette étape d’authentification est requise uniquement pour les agents privés. Si vous utilisez un agent public, vous pouvez ignorer cette section et utiliser directement `agentId` dans l’appel `startSession`.

Si vous utilisez un agent privé qui exige une authentification, vous devrez générer une URL signée depuis votre serveur. Cette section explique comment procéder.

### Prérequis

1. Un compte ElevenLabs et une clé API. [Inscrivez-vous ici](https://elevenlabs.io/app/sign-up).

#### Créer des variables d’environnement

Créez un fichier `.env.local` à la racine de votre projet :

**`.env.local`**

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

> **Warning**
>
> 1. Veillez à ajouter `.env.local` à votre fichier `.gitignore` afin d’éviter de valider accidentellement des identifiants sensibles dans votre gestionnaire de versions.
> 2. N’exposez jamais votre clé API dans le code côté client. Conservez-la toujours de manière sécurisée sur le serveur.

#### Créer une route API

Créez un fichier `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 }
    );
  }
}
```

#### Mettre à jour le composant Conversation

Modifiez votre fichier `conversation.tsx` pour récupérer et utiliser l’URL signée :

**`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**
>
> Les URL signées expirent après une courte période. Toutefois, les conversations lancées avant leur expiration se poursuivent sans interruption. En environnement de production, mettez en œuvre une gestion appropriée des erreurs et une logique de renouvellement des URL pour démarrer de nouvelles conversations.

## Étapes suivantes

Vous disposez désormais d’une implémentation de base. Vous pouvez :

1. Ajouter un retour visuel sur l’activité vocale
2. Mettre en œuvre une logique de gestion des erreurs et de nouvelle tentative
3. Ajouter l’affichage de l’historique des conversations
4. Personnaliser l’interface pour l’adapter à votre marque

> **Info**
>
> Pour des fonctionnalités et des options de personnalisation plus avancées, consultez le package [@elevenlabs/react](https://www.npmjs.com/package/@elevenlabs/react).