> 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. # WebSocket > **Note** > > Esta documentación está dirigida a desarrolladores que integran directamente la API WebSocket de ElevenLabs. Para > mayor comodidad, te recomendamos usar [los SDK oficiales de ElevenLabs](/docs/es/eleven-agents/libraries/python). La API WebSocket de [ElevenAgents](https://elevenlabs.io/agents) permite mantener conversaciones de voz interactivas en tiempo real con agentes de IA. Al establecer una conexión WebSocket, puedes enviar audio de entrada y recibir respuestas de audio en tiempo real, creando experiencias conversacionales realistas. > **Note** > > Ruta de API: `wss://api.elevenlabs.io/v1/convai/conversation?agent_id={agent_id}` ## Autenticación ### Usar el ID del agente Para agentes públicos, puedes usar directamente el `agent_id` en la URL de WebSocket sin autenticación adicional: ```bash wss://api.elevenlabs.io/v1/convai/conversation?agent_id= ``` ### Usar una URL firmada Para agentes privados o conversaciones que requieran autorización, obtén una URL firmada desde tu servidor, que se comunica de forma segura con la API de ElevenLabs mediante tu clave de API. ### Ejemplo con cURL **Solicitud:** ```bash curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=" \ -H "xi-api-key: " ``` **Respuesta:** ```json { "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=&token=" } ``` > **Warning** > > Nunca expongas tu clave de API de ElevenLabs en el lado del cliente. ## Eventos de WebSocket ### Eventos del cliente al servidor Puedes enviar los siguientes eventos desde el cliente al servidor: #### Actualizaciones contextuales Envía información contextual que no interrumpa la conversación para actualizar su estado. Esto te permite aportar contexto adicional sin alterar el flujo de la conversación en curso. ```javascript { "type": "contextual_update", "text": "User clicked on pricing page" } ``` **Casos de uso:** * Actualizar el estado o las preferencias del usuario * Proporcionar contexto del entorno * Añadir información de contexto * Hacer seguimiento de las interacciones en la interfaz de usuario **Puntos clave:** * No interrumpe el flujo actual de la conversación * Las actualizaciones se incorporan como llamadas a herramientas en el historial de la conversación * Ayuda a mantener el contexto sin romper el diálogo natural > **Note** > > Las actualizaciones contextuales se procesan de forma asíncrona y no requieren una respuesta directa del servidor. #### [Referencia de la API WebSocket](/docs/es/eleven-agents/api-reference/eleven-agents/websocket) Consulta la documentación de referencia de la API WebSocket de ElevenLabs Agents para ver estructuras de mensajes, parámetros y ejemplos detallados. ## Ejemplo de implementación en Next.js Este ejemplo muestra cómo implementar un cliente de agente conversacional basado en WebSocket en Next.js mediante la API WebSocket de ElevenLabs. > **Note** > > Aunque este ejemplo utiliza el paquete `voice-stream` para gestionar la entrada del micrófono, puedes > implementar tu propia solución para capturar y codificar audio. El objetivo es mostrar > la conexión WebSocket y la gestión de eventos con la API de ElevenLabs. #### Instala las dependencias necesarias Primero, instala los paquetes necesarios: ```bash npm install voice-stream ``` El paquete `voice-stream` gestiona el acceso al micrófono y el streaming de audio, y codifica automáticamente el audio en formato base64, tal como requiere la API de ElevenLabs. > **Note** > > Este ejemplo utiliza Tailwind CSS para los estilos. Para añadir Tailwind a tu proyecto de Next.js: > > ```bash > npm install -D tailwindcss postcss autoprefixer > npx tailwindcss init -p > ``` > > Después, sigue la [guía oficial de configuración de Tailwind CSS para Next.js](https://tailwindcss.com/docs/guides/nextjs). > > También puedes sustituir los atributos className por tus propios estilos CSS. #### Crea los tipos de WebSocket Define los tipos de los eventos de WebSocket: **`app/types/websocket.ts`** ```typescript app/types/websocket.ts type BaseEvent = { type: string; }; type UserTranscriptEvent = BaseEvent & { type: "user_transcript"; user_transcription_event: { user_transcript: string; }; }; type AgentResponseEvent = BaseEvent & { type: "agent_response"; agent_response_event: { agent_response: string; }; }; type AgentResponseCorrectionEvent = BaseEvent & { type: "agent_response_correction"; agent_response_correction_event: { original_agent_response: string; corrected_agent_response: string; }; }; type AudioResponseEvent = BaseEvent & { type: "audio"; audio_event: { audio_base_64: string; event_id: number; alignment: { chars: string[]; char_durations_ms: number[]; char_start_times_ms: number[]; }; }; }; type InterruptionEvent = BaseEvent & { type: "interruption"; interruption_event: { reason: string; }; }; type PingEvent = BaseEvent & { type: "ping"; ping_event: { event_id: number; ping_ms?: number; }; }; type AgentChatResponsePartEvent = BaseEvent & { type: "agent_chat_response_part"; text_response_part: { type: "start" | "delta" | "stop"; text: string; event_id: number; response_id: string; }; }; export type ElevenLabsWebSocketEvent = | UserTranscriptEvent | AgentResponseEvent | AgentResponseCorrectionEvent | AudioResponseEvent | InterruptionEvent | PingEvent | AgentChatResponsePartEvent; ``` #### Crea el hook de WebSocket Crea un hook personalizado para gestionar la conexión WebSocket: **`app/hooks/useAgentConversation.ts`** ```typescript app/hooks/useAgentConversation.ts 'use client'; import { useCallback, useEffect, useRef, useState } from 'react'; import { useVoiceStream } from 'voice-stream'; import type { ElevenLabsWebSocketEvent } from '../types/websocket'; const sendMessage = (websocket: WebSocket, request: object) => { if (websocket.readyState !== WebSocket.OPEN) { return; } websocket.send(JSON.stringify(request)); }; export const useAgentConversation = () => { const websocketRef = useRef(null); const [isConnected, setIsConnected] = useState(false); const { startStreaming, stopStreaming } = useVoiceStream({ onAudioChunked: (audioData) => { if (!websocketRef.current) return; sendMessage(websocketRef.current, { user_audio_chunk: audioData, }); }, }); const startConversation = useCallback(async () => { if (isConnected) return; const websocket = new WebSocket("wss://api.elevenlabs.io/v1/convai/conversation"); websocket.onopen = async () => { setIsConnected(true); sendMessage(websocket, { type: "conversation_initiation_client_data", }); await startStreaming(); }; websocket.onmessage = async (event) => { const data = JSON.parse(event.data) as ElevenLabsWebSocketEvent; // Handle ping events to keep connection alive if (data.type === "ping") { setTimeout(() => { sendMessage(websocket, { type: "pong", event_id: data.ping_event.event_id, }); }, data.ping_event.ping_ms); } if (data.type === "user_transcript") { const { user_transcription_event } = data; console.log("User transcript", user_transcription_event.user_transcript); } if (data.type === "agent_response") { const { agent_response_event } = data; console.log("Agent response", agent_response_event.agent_response); } if (data.type === "agent_response_correction") { const { agent_response_correction_event } = data; console.log("Agent response correction", agent_response_correction_event.corrected_agent_response); } if (data.type === "interruption") { // Handle interruption } if (data.type === "audio") { const { audio_event } = data; // Implement your own audio playback system here // Note: You'll need to handle audio queuing to prevent overlapping // as the WebSocket sends audio events in chunks } if (data.type === "agent_chat_response_part") { const { text_response_part } = data; const { type: partType, text, response_id } = text_response_part; // Handle the agent's response text as it is generated. Enable // agent_chat_response_part in the agent's client_events to receive // this during voice conversations. console.log("Chat response part:", partType, text, response_id); } }; websocketRef.current = websocket; websocket.onclose = async () => { websocketRef.current = null; setIsConnected(false); stopStreaming(); }; }, [startStreaming, isConnected, stopStreaming]); const stopConversation = useCallback(async () => { if (!websocketRef.current) return; websocketRef.current.close(); }, []); useEffect(() => { return () => { if (websocketRef.current) { websocketRef.current.close(); } }; }, []); return { startConversation, stopConversation, isConnected, }; }; ``` #### Crea el componente de conversación Crea un componente para usar el hook de WebSocket: **`app/components/Conversation.tsx`** ```typescript app/components/Conversation.tsx 'use client'; import { useCallback } from 'react'; import { useAgentConversation } from '../hooks/useAgentConversation'; export function Conversation() { const { startConversation, stopConversation, isConnected } = useAgentConversation(); const handleStart = useCallback(async () => { try { await navigator.mediaDevices.getUserMedia({ audio: true }); await startConversation(); } catch (error) { console.error('Failed to start conversation:', error); } }, [startConversation]); return (

Status: {isConnected ? 'Connected' : 'Disconnected'}

); } ``` ## Siguientes pasos 1. **Reproducción de audio**: Implementa tu propio sistema de reproducción de audio con Web Audio API o una biblioteca. Recuerda gestionar la cola de audio para evitar superposiciones, ya que WebSocket envía los eventos de audio por fragmentos. 2. **Gestión de errores**: Añade lógica de reintento y mecanismos de recuperación ante errores. 3. **Información en la interfaz**: Añade indicadores visuales de actividad de voz y estado de conexión. ## Gestión de la latencia Para garantizar conversaciones fluidas, implementa estas estrategias: * **Búfer adaptativo:** Ajusta el búfer de audio según las condiciones de red. * **Búfer de fluctuación:** Implementa un búfer de fluctuación para suavizar las variaciones en los tiempos de llegada de los paquetes. * **Supervisión de ping-pong:** Usa eventos ping y pong para medir el tiempo de ida y vuelta y ajustar según corresponda. ## Buenas prácticas de seguridad * Rota las claves de API periódicamente y usa variables de entorno para almacenarlas. * Implementa límites de velocidad para evitar usos indebidos. * Explica claramente el motivo cuando pidas a usuarios acceso al micrófono. * Fragmentación optimizada: ajusta la duración de los fragmentos de audio para equilibrar latencia y eficiencia. ## Recursos adicionales * [Documentación de ElevenLabs Agents](/docs/es/eleven-agents/overview) * [SDK de ElevenLabs Agents](/docs/es/eleven-agents/libraries/python)