JavaScript SDK

Installation

Installera paketet i ditt projekt med en pakethanterare.

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

Användning

Det här biblioteket är främst avsett för utveckling i vanliga JavaScript-projekt, eller som grund för bibliotek anpassade för specifika ramverk. Vi rekommenderar att du kontrollerar om ditt specifika ramverk har ett eget bibliotek. Du kan dock använda det här biblioteket i alla JavaScript-baserade projekt.

Initiera konversation

Skapa först en ny konversationssession med Conversation.startSession:

const conversation = await Conversation.startSession(options);

Detta upprättar en anslutning och börjar använda mikrofonen för att kommunicera med ElevenLabs Agents-agenten. Överväg att förklara och be om mikrofonåtkomst i appens gränssnitt innan du startar konversationen:

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

Sessionskonfiguration

Alternativen som skickas till startSession anger hur sessionen upprättas. Konversationer kan startas med offentliga eller privata agenter.

Offentliga agenter

Agenter som inte kräver autentisering kan användas för att starta en konversation med agent-ID:t. Agent-ID:t kan hämtas via ElevenLabs-gränssnittet.

För offentliga agenter kan du använda ID:t direkt:

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

Privata agenter

Om konversationen kräver auktorisering måste du lägga till en särskild slutpunkt på din server som antingen begär en signerad URL (om du använder anslutningstypen WebSockets) eller en konversationstoken (om du använder WebRTC) med ElevenLabs API och skickar tillbaka den till klienten.

Här är ett exempel för en WebSocket-anslutning:

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

Här är ett exempel för 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);
});

När du har tokenen startar konversationen via WebRTC när du skickar den till startSession.

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

Valfria callbacks

Alternativen som skickas till startSession kan också användas för att registrera valfria callbacks:

• onConnect - hanterare som anropas när konversationens WebSocket-anslutning har upprättats.
• onDisconnect - hanterare som anropas när konversationens WebSocket-anslutning avslutas.
• onMessage - hanterare som anropas när ett nytt textmeddelande tas emot. Dessa kan vara preliminära eller slutliga transkriberingar av användarens röst eller svar som producerats av LLM. Används främst för att hantera konversationstranskribering.
• onError - hanterare som anropas när ett fel uppstår.
• onStatusChange - hanterare som anropas när anslutningsstatusen ändras. Kan vara connected, connecting och disconnected (initialt).
• onModeChange - hanterare som anropas när en status ändras, till exempel när agenten växlar från speaking till listening, eller tvärtom.
• onCanSendFeedbackChange - hanterare som anropas när det blir möjligt eller omöjligt att skicka feedback.
• onAudioAlignment - hanterare som anropas när ljudjusteringsdata tas emot och ger tidsinformation på teckennivå för agentens tal.

Returvärde

startSession returnerar en konversationsinstans (VoiceConversation eller TextConversation beroende på läge) som kan användas för att styra sessionen. Metoden utlöser ett fel om sessionen inte kan upprättas. Detta kan hända om användaren nekar mikrofonåtkomst eller om anslutningen misslyckas.

endSession

En metod för att avsluta konversationen manuellt. Metoden avslutar konversationen och kopplar från WebSocket. Därefter går konversationsinstansen inte att använda och kan utan problem kasseras.

await conversation.endSession();

getId

En metod som returnerar konversations-ID:t.

const id = conversation.getId();

setVolume

En metod för att ställa in konversationens utgående volym. Tar emot ett objekt med ett volymfält mellan 0 och 1.

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

getInputVolume / getOutputVolume

Metoder som returnerar aktuell in- respektive utvolym på en skala från 0 till 1, där 0 är -100 dB och 1 är -30 dB.

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

sendFeedback

En metod för att skicka binär feedback till agenten. Metoden tar emot ett booleskt värde, där true representerar positiv feedback och false negativ feedback.

Feedback kopplas alltid till agentens senaste svar och kan endast skickas en gång per svar.

Du kan lyssna på onCanSendFeedbackChange för att veta om feedback kan skickas vid tillfället.

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

sendContextualUpdate

En metod för att skicka kontextuella uppdateringar till agenten. Detta kan användas för att informera agenten om användaråtgärder som inte är direkt relaterade till konversationen, men som kan påverka agentens svar.

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

sendUserMessage

Skickar ett textmeddelande till agenten.

Kan användas för att låta användaren skriva meddelandet i stället för att använda mikrofonen. Till skillnad från sendContextualUpdate behandlas detta som ett användarmeddelande och uppmanar agenten att ta sin tur i konversationen.

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

sendUserActivity

Meddelar agenten om användaraktivitet.

Agenten försöker inte tala under minst 2 sekunder efter att användaraktivitet har upptäckts.

Detta kan användas för att hindra agenten från att avbryta användaren när hen skriver.

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

setMicMuted

En metod för att stänga av eller slå på mikrofonen.

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

changeInputDevice

Gör det möjligt att ändra ljudinmatningsenhet under en aktiv röstkonversation. Den här metoden är endast tillgänglig för röstkonversationer.

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

Om enhets-ID:t är ogiltigt används standardenheten i stället.

changeOutputDevice

Gör det möjligt att ändra ljudutmatningsenhet under en aktiv röstkonversation. Den här metoden är endast tillgänglig för röstkonversationer.

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

Metoder som returnerar Uint8Array:er med aktuell frekvensdata för in- respektive utmatning. Se AnalyserNode.getByteFrequencyData för mer information.