RecursosSDK

WebSocket

Crea conversaciones de voz interactivas en tiempo real con agentes de IA

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.

La API WebSocket de ElevenAgents 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.

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:

wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<your-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:

curl -X GET "https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=<your-agent-id>" \
     -H "xi-api-key: <your-api-key>"

Respuesta:

{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=<your-agent-id>&token=<token>"
}
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:

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.

{
  "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

Las actualizaciones contextuales se procesan de forma asíncrona y no requieren una respuesta directa del servidor.

Referencia de la API 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.

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.

1

Instala las dependencias necesarias

Primero, instala los paquetes necesarios:

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.

Este ejemplo utiliza Tailwind CSS para los estilos. Para añadir Tailwind a tu proyecto de Next.js:

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.

También puedes sustituir los atributos className por tus propios estilos CSS.

2

Crea los tipos de WebSocket

Define los tipos de los eventos de WebSocket:

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;
3

Crea el hook de WebSocket

Crea un hook personalizado para gestionar la conexión WebSocket:

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<WebSocket>(null);
  const [isConnected, setIsConnected] = useState<boolean>(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,
  };
};
4

Crea el componente de conversación

Crea un componente para usar el hook de WebSocket:

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 (
    <div className="flex flex-col items-center gap-4">
      <div className="flex gap-2">
        <button
          onClick={handleStart}
          disabled={isConnected}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
        >
          Start Conversation
        </button>
        <button
          onClick={stopConversation}
          disabled={!isConnected}
          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: {isConnected ? 'Connected' : 'Disconnected'}</p>
      </div>
    </div>
  );
}

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