GuiasInícios rápidos

Next.JS

Aprenda a criar uma aplicação web que permite conversas por voz com agentes de IA da ElevenLabs

Este tutorial vai orientar você na criação de um cliente web que pode interagir com um agente da ElevenLabs. Você aprenderá a implementar conversas de voz em tempo real, permitindo que os usuários falem com um agente de IA capaz de ouvir, entender e responder naturalmente usando síntese de voz.

O que você vai precisar

  1. Um agente da ElevenLabs criado seguindo este guia
  2. O npm instalado no seu sistema local.
  3. Usaremos Typescript neste tutorial, mas você pode usar Javascript se preferir.

Procurando um exemplo completo? Confira nossa demonstração do Next.js no GitHub.

Configuração

1

Criar um novo projeto Next.js

Abra uma janela do terminal e execute o comando a seguir:

npm create next-app my-conversational-agent

Ele fará algumas perguntas sobre como criar seu projeto. Neste tutorial, seguiremos as sugestões padrão.

3

Instalar a dependência da ElevenLabs

npm install @elevenlabs/react
4

Testar a configuração

Execute o comando a seguir para iniciar o servidor de desenvolvimento e abra a URL fornecida no navegador:

npm run dev

Implementar os agentes da ElevenLabs

1

Criar o componente de conversa

Crie um novo arquivo 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>
  );
}
2

Atualizar a página principal

Substitua o conteúdo de app/page.tsx por:

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

Esta etapa de autenticação é necessária apenas para agentes privados. Se você estiver usando um agente público, pode pular esta seção e usar diretamente o agentId na chamada startSession.

Se você estiver usando um agente privado que exige autenticação, precisará gerar uma URL assinada no seu servidor. Esta seção explica como configurar isso.

O que você vai precisar

  1. Uma conta e uma chave de API da ElevenLabs. Cadastre-se aqui.
1

Criar variáveis de ambiente

Crie um arquivo .env.local na raiz do projeto:

.env.local
ELEVENLABS_API_KEY=your-api-key-here
NEXT_PUBLIC_AGENT_ID=your-agent-id-here
  1. Adicione .env.local ao arquivo .gitignore para evitar o envio acidental de credenciais confidenciais ao controle de versão.
  2. Nunca exponha sua chave de API no código do lado do cliente. Mantenha-a sempre segura no servidor.
2

Criar uma rota de API

Crie um novo arquivo 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 }
    );
  }
}
3

Atualizar o componente Conversation

Modifique seu conversation.tsx para buscar e usar a URL assinada:

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

URLs assinadas expiram após um curto período. No entanto, todas as conversas iniciadas antes da expiração continuarão sem interrupções. Em um ambiente de produção, implemente um tratamento de erros adequado e uma lógica de atualização de URL para iniciar novas conversas.

Próximas etapas

Agora que você tem uma implementação básica, pode:

  1. Adicionar feedback visual para a atividade de voz
  2. Implementar tratamento de erros e lógica de novas tentativas
  3. Adicionar uma exibição do histórico de chat
  4. Personalizar a interface para combinar com sua marca

Para recursos mais avançados e opções de personalização, confira o pacote @elevenlabs/react.