React SDK

Installation

Install the package in your project through package manager.

$
npm install @elevenlabs/react
>
# or
>
yarn add @elevenlabs/react
>
# or
>
pnpm install @elevenlabs/react

Usage

useConversation

A React hook for managing connection and audio usage for ElevenLabs Conversational AI.

Initialize conversation

First, initialize the Conversation instance.

1
import { useConversation } from '@elevenlabs/react';
2
3
const conversation = useConversation();

Note that Conversational AI requires microphone access. Consider explaining and allowing access in your app’s UI before the Conversation starts.

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

Options

The Conversation can be initialized with certain options

1
const conversation = useConversation({
2
  /* options object */
3
});

• onConnect - handler called when the conversation websocket connection is established.
• onDisconnect - handler called when the conversation websocket connection is ended.
• onMessage - handler called when a new message is received. These can be tentative or final transcriptions of user voice, replies produced by LLM, or debug message when a debug option is enabled.
• onError - handler called when a error is encountered.

Methods

startSession

The startConversation method kicks off the WebSocket or WebRTC connection and starts using the microphone to communicate with the ElevenLabs Conversational AI agent. The method accepts an options object, with the signedUrl, conversationToken or agentId option being required.

The Agent ID can be acquired through ElevenLabs UI.

1
const conversation = useConversation();
2
3
// For public agents, pass in the agent ID and the connection type
4
const conversationId = await conversation.startSession({
5
  agentId: '<your-agent-id>',
6
  connectionType: 'webrtc', // either "webrtc" or "websocket"
7
});

For public agents (i.e. agents that don’t have authentication enabled), only the agentId is required.

In case the conversation requires authorization, use the REST API to generate signed links for a WebSocket connection or a conversation token for a WebRTC connection.

startSession returns a promise resolving a conversationId. The value is a globally unique conversation ID you can use to identify separate conversations.

1
// Node.js server
2
3
app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
4
  const response = await fetch(
5
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
6
    {
7
      headers: {
8
        // Requesting a signed url requires your ElevenLabs API key
9
        // Do NOT expose your API key to the client!
10
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
11
      },
12
    }
13
  );
14
15
  if (!response.ok) {
16
    return res.status(500).send("Failed to get signed URL");
17
  }
18
19
  const body = await response.json();
20
  res.send(body.signed_url);
21
});

1
// Client
2
3
const response = await fetch("/signed-url", yourAuthHeaders);
4
const signedUrl = await response.text();
5
6
const conversation = await Conversation.startSession({
7
  signedUrl,
8
  connectionType: "websocket",
9
});

endSession

A method to manually end the conversation. The method will disconnect and end the conversation.

1
await conversation.endSession();

setVolume

Sets the output volume of the conversation. Accepts an object with a volume field between 0 and 1.

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

status

A React state containing the current status of the conversation.

1
const { status } = useConversation();
2
console.log(status); // "connected" or "disconnected"

isSpeaking

A React state containing information on whether the agent is currently speaking. This is useful for indicating agent status in your UI.

1
const { isSpeaking } = useConversation();
2
console.log(isSpeaking); // boolean