Construye un asistente de voz con ElevenLabs y Next.js (Next.js)

Antes de escribir cualquier código, invoca la habilidad /speech-engine para aprender los patrones correctos del SDK de ElevenLabs.

1. package.json

• Añade @elevenlabs/react, @elevenlabs/elevenlabs-js, openai, dotenv y tsx.
• Añade scripts: speech-engine:create (tsx scripts/create-engine.mts), speech-engine:enable-first-message (tsx scripts/enable-first-message.mts), speech-engine:server (tsx server.mts).

2. .env.example

• Documenta ELEVENLABS_API_KEY, ELEVENLABS_SPEECH_ENGINE_ID, OPENAI_API_KEY y PUBLIC_WS_URL (wss://…/ws de ngrok).

3. scripts/create-engine.mts

• Carga el entorno con dotenv/config.
• Crea un Speech Engine con elevenlabs.speechEngine.create, usando speechEngine.wsUrl de PUBLIC_WS_URL.
• Llama a un ayudante compartido para habilitar overrides.firstMessage en el nuevo recurso.
• Imprime engineId e instrucciones para el siguiente paso.

4. scripts/enable-first-message.mts

• Actualiza un Speech Engine existente (ELEVENLABS_SPEECH_ENGINE_ID) para que el cliente pueda establecer overrides.agent.firstMessage.

5. lib/speech-engine-overrides.ts

• Exporta enableFirstMessageOverride(client, speechEngineId) usando speechEngine.update con overrides: { firstMessage: true }.

6. lib/assistant.ts

• Ayudantes compartidos de la API de respuestas de OpenAI: ASSISTANT_INSTRUCTIONS, isChatRole, normalizeChatMessages, transcriptToChatMessages, createAssistantReply(messages, signal) y createAssistantStream(messages, signal).
• Mapea el rol agent de Speech Engine a assistant de OpenAI; mantén las respuestas concisas.
• Normaliza el historial antes de enviarlo a OpenAI: recorta el contenido, elimina mensajes vacíos, limita el recuento de mensajes y la longitud por mensaje.

7. lib/voice-history.ts

• Añade un pequeño almacén local que permita a la aplicación Next.js entregar el historial de chat tipificado al servidor Speech Engine independiente.
• Almacena el ChatMessage[] normalizado en .next/cache/voice-history.json por historyId aleatorio.
• Exporta createVoiceHistory(messages), linkVoiceHistory(conversationId, historyId) y loadVoiceHistory(conversationId).
• Mantén esto solo para demostración y respaldado por archivos; sin base de datos ni capa de autenticación.

8. server.mts

• Servidor HTTP independiente en el puerto 3001 con speechEngine.attach(SPEECH_ENGINE_ID, httpServer, "/ws", { debug: true, … }).
• onTranscript: carga cualquier historial de chat tipificado vinculado a session.conversationId, añade transcriptToChatMessages(transcript), pasa AbortSignal a createAssistantStream y session.sendResponse(stream).
• Almacena en caché el historial inicial cargado por conversación y reintenta brevemente porque el navegador puede vincular el historial inmediatamente después de que se crea la conversación de voz.
• Registra onInit, onClose y onError. Requiere ELEVENLABS_SPEECH_ENGINE_ID y OPENAI_API_KEY.

9. app/api/chat/route.ts

• Ruta POST segura para chat tipificado regular.
• Acepta { messages }, valida cada mensaje como { role: "user" | "assistant", content: string }, limita el historial de solicitudes y llama a createAssistantReply(messages, request.signal).
• Devuelve { message }; devuelve errores JSON para cargas útiles no válidas o fallos de OpenAI.
• Esta ruta y el modo de voz deben usar la misma forma ChatMessage para que el contexto pueda moverse entre modos.

10. app/api/voice-history/route.ts

• Ruta POST que acepta el historial de chat tipificado actual antes de que comience el modo de voz.
• Valida y normaliza los mensajes con isChatRole, llama a createVoiceHistory(messages) y devuelve { historyId }.
• Devuelve un 400 si no se proporcionan mensajes válidos.

11. app/api/voice-history/link/route.ts

• Ruta POST que acepta { historyId, conversationId } del navegador una vez que el cliente de Speech Engine crea una conversación de voz.
• Llama a linkVoiceHistory(conversationId, historyId) y devuelve { ok: true }, o 404 si el ID del historial es desconocido.

12. app/api/token/route.ts

• Ruta GET segura; nunca expongas ELEVENLABS_API_KEY al cliente.
• Devuelve { token } de conversationalAi.conversations.getWebrtcToken({ agentId: ELEVENLABS_SPEECH_ENGINE_ID }).
• Maneja la falta de entorno y los errores de la API con respuestas de error JSON.

13. app/page.tsx

• Crea una única interfaz de usuario de chat que funcione primero como un chat de asistente normal, y luego pueda cambiar al modo de voz sin perder el contexto.
• Mantén un array de estado messages con { id, role: "user" | "assistant", content, channel: "chat" | "voice", pending?, error? }.
• Ruta de envío de texto: añade el mensaje del usuario, envía el historial normalizado completo a /api/chat, reemplaza el mensaje pendiente del asistente con la respuesta y mantén el compositor utilizable.
• Ruta de inicio de voz: solicita acceso al micrófono, envía el historial de chat actual no pendiente/sin errores a /api/voice-history, busca /api/token y luego inicia la sesión de voz con un saludo overrides.agent.firstMessage en línea.
• En onConversationCreated, vincula el historyId almacenado a voiceConversation.getId() con /api/voice-history/link; si es útil, también envía una actualización contextual que resuma el chat tipificado reciente.
• Ruta de eventos de voz: usa useConversation({ onMessage }) para añadir o actualizar mensajes de transcripción en el mismo array messages, mapeando el rol agent del SDK al rol local assistant.
• Mientras la voz esté conectada, permite también mensajes tipificados: añádelos al mismo hilo y llama a conversation.sendUserMessage(content); evita duplicar ecos de onMessage.
• El siguiente chat tipificado después del modo de voz debe incluir mensajes de transcripción de voz en el historial enviado a /api/chat.
• Muestra un hilo de mensajes desplazable, un compositor de texto, un control de micrófono/inicio de voz, un control de parada de voz, estado de conexión, silenciar/activar sonido cuando esté conectado y mensajes de error de chat/voz separados.
• Sigue DESIGN.md; haz que la página se sienta como una aplicación de chat regular con voz como un modo, no una demostración solo de voz.