SDK de JavaScript

Instalación

Instala el paquete en tu proyecto mediante un gestor de paquetes.

npm install @elevenlabs/client
# or
yarn add @elevenlabs/client
# or
pnpm install @elevenlabs/client

Uso

Esta biblioteca está pensada principalmente para el desarrollo de proyectos con JavaScript sin frameworks, o como base para bibliotecas adaptadas a frameworks específicos. Te recomendamos comprobar si tu framework concreto tiene su propia biblioteca. No obstante, puedes usar esta biblioteca en cualquier proyecto basado en JavaScript.

Inicializar una conversación

Primero, crea una nueva sesión de conversación con Conversation.startSession:

const conversation = await Conversation.startSession(options);

Esto establecerá una conexión y empezará a usar el micrófono para comunicarse con el agente de ElevenLabs Agents. Antes de iniciar la conversación, plantéate explicar en la interfaz de tu aplicación por qué necesitas acceder al micrófono y solicitar permiso:

// call after explaining to the user why the microphone access is needed
await navigator.mediaDevices.getUserMedia({ audio: true });

Configuración de la sesión

Las opciones que se pasan a startSession especifican cómo se establece la sesión. Las conversaciones pueden iniciarse con agentes públicos o privados.

Agentes públicos

Los agentes que no requieren autenticación pueden utilizarse para iniciar una conversación mediante el ID del agente. Puedes obtener el ID del agente a través de la interfaz de ElevenLabs.

Para los agentes públicos, puedes usar el ID directamente:

const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
});

Agentes privados

Si la conversación requiere autorización, tendrás que añadir a tu servidor una ruta de API específica que solicite una URL firmada (si utilizas el tipo de conexión WebSockets) o un token de conversación (si utilizas WebRTC) mediante la API de ElevenLabs y lo devuelva al cliente.

Aquí tienes un ejemplo para una conexión WebSocket:

// Node.js server
app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
    {
      method: "GET",
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.XI_API_KEY,
      },
    }
  );
  if (!response.ok) {
    return res.status(500).send("Failed to get signed URL");
  }
  const body = await response.json();
  res.send(body.signed_url);
});

// Client
const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();
const conversation = await Conversation.startSession({
  signedUrl,
});

Aquí tienes un ejemplo para WebRTC:

// Node.js server
app.get("/conversation-token", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
      },
    }
  );
  if (!response.ok) {
    return res.status(500).send("Failed to get conversation token");
  }
  const body = await response.json();
  res.send(body.token);
});

Cuando tengas el token, proporcionarlo a startSession iniciará la conversación mediante WebRTC.

// Client
const response = await fetch("/conversation-token", yourAuthHeaders);
const conversationToken = await response.text();
const conversation = await Conversation.startSession({
  conversationToken,
});

Callbacks opcionales

Las opciones que se pasan a startSession también pueden usarse para registrar callbacks opcionales:

• onConnect - controlador que se llama cuando se establece la conexión WebSocket de la conversación.
• onDisconnect - controlador que se llama cuando finaliza la conexión WebSocket de la conversación.
• onMessage - controlador que se llama cuando se recibe un nuevo mensaje de texto. Puede tratarse de transcripciones provisionales o definitivas de la voz del usuario, o de respuestas generadas por un LLM. Se utiliza principalmente para gestionar la transcripción de la conversación.
• onError - controlador que se llama cuando se produce un error.
• onStatusChange - controlador que se llama cada vez que cambia el estado de la conexión. Puede ser connected, connecting y disconnected (inicial).
• onModeChange - controlador que se llama cuando cambia un estado; por ejemplo, cuando el agente pasa de speaking a listening, o viceversa.
• onCanSendFeedbackChange - controlador que se llama cuando el envío de comentarios pasa a estar disponible o no disponible.
• onAudioAlignment - controlador que se llama al recibir datos de alineación de audio y proporciona información de tiempos a nivel de carácter para el habla del agente.

Valor de retorno

startSession devuelve una instancia de conversación (VoiceConversation o TextConversation, según el modo) que puedes usar para controlar la sesión. El método generará un error si no se puede establecer la sesión. Esto puede ocurrir si el usuario deniega el acceso al micrófono o si falla la conexión.

endSession

Un método para finalizar manualmente la conversación. El método finalizará la conversación y se desconectará del WebSocket. Después, la instancia de conversación dejará de poder usarse y puedes descartarla con seguridad.

await conversation.endSession();

getId

Un método que devuelve el ID de la conversación.

const id = conversation.getId();

setVolume

Un método para establecer el volumen de salida de la conversación. Acepta un objeto con un campo de volumen entre 0 y 1.

await conversation.setVolume({ volume: 0.5 });

getInputVolume / getOutputVolume

Métodos que devuelven el volumen de entrada/salida actual en una escala de 0 a 1, donde 0 equivale a -100 dB y 1 a -30 dB.

const inputVolume = await conversation.getInputVolume();
const outputVolume = await conversation.getOutputVolume();

sendFeedback

Un método para enviar comentarios binarios al agente. El método acepta un valor booleano, donde true representa comentarios positivos y false, comentarios negativos.

Los comentarios siempre se asocian a la respuesta más reciente del agente y solo pueden enviarse una vez por respuesta.

Puedes escuchar onCanSendFeedbackChange para saber si se pueden enviar comentarios en ese momento.

conversation.sendFeedback(true); // positive feedback
conversation.sendFeedback(false); // negative feedback

sendContextualUpdate

Un método para enviar actualizaciones contextuales al agente. Puede utilizarse para informar al agente sobre acciones del usuario que no están directamente relacionadas con la conversación, pero que pueden influir en las respuestas del agente.

conversation.sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);

sendUserMessage

Envía un mensaje de texto al agente.

Puedes usarlo para que el usuario escriba el mensaje en lugar de usar el micrófono. A diferencia de sendContextualUpdate, se tratará como un mensaje del usuario y hará que el agente intervenga en la conversación.

sendButton.addEventListener("click", (e) => {
  conversation.sendUserMessage(textInput.value);
  textInput.value = "";
});

sendUserActivity

Notifica al agente sobre la actividad del usuario.

El agente no intentará hablar durante al menos 2 segundos después de detectar la actividad del usuario.

Puedes usarlo para evitar que el agente interrumpa al usuario mientras escribe.

textInput.addEventListener("input", () => {
  conversation.sendUserActivity();
});

setMicMuted

Un método para silenciar o reactivar el micrófono.

// Mute the microphone
conversation.setMicMuted(true);
// Unmute the microphone
conversation.setMicMuted(false);

changeInputDevice

Te permite cambiar el dispositivo de entrada de audio durante una conversación de voz activa. Este método solo está disponible para conversaciones de voz.

const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  // Alternatively you can provide a device ID when starting the session
  // Useful if you want to start the conversation with a non-default device
  inputDeviceId: "a1b2c3d4e5f6",
});
// Change to a specific input device
await conversation.changeInputDevice({
  sampleRate: 16000,
  format: "pcm",
  preferHeadphonesForIosDevices: true,
  inputDeviceId: "a1b2c3d4e5f6",
});

Si el ID del dispositivo no es válido, se usará el dispositivo predeterminado.

changeOutputDevice

Te permite cambiar el dispositivo de salida de audio durante una conversación de voz activa. Este método solo está disponible para conversaciones de voz.

const conversation = await Conversation.startSession({
  agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
  // Alternatively you can provide a device ID when starting the session
  // Useful if you want to start the conversation with a non-default device
  outputDeviceId: "a1b2c3d4e5f6",
});
// Change to a specific output device
await conversation.changeOutputDevice({
  sampleRate: 16000,
  format: "pcm",
  outputDeviceId: "a1b2c3d4e5f6",
});

getInputByteFrequencyData / getOutputByteFrequencyData

Métodos que devuelven Uint8Arrays con los datos de frecuencia de entrada/salida actuales. Consulta AnalyserNode.getByteFrequencyData para obtener más información.