React SDK

​

Installation

Install the package in your project through package manager.

npm install @11labs/react
# or
yarn add @11labs/react
# or
pnpm install @11labs/react

​

Usage

​

useConversation

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

​

Initialize conversation

First, initialize the Conversation instance.

const conversation = useConversation();

Note that Conversational AI requires microphone access. Consider explaining and allowing access in your apps UI before the Conversation kicks off.

// call after explaning to the user why the microphone access is needed
await navigator.mediaDevices.getUserMedia();

​

Options

The Conversation can be initialized with certain options. Those are all optional.

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

• 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

startConversation

startConversation method kick off the websocket connection and starts using microphone to communicate with the ElevenLabs Conversational AI agent.
The method accepts options object, with the url or agentId option being required.

Agent ID can be acquired through ElevenLabs UI and is always necessary.

const conversation = useConversation();
const conversationId = await conversation.startSession({ url });

For the public agents, define agentId - no signed link generation necessary.

In case the conversation requires authorization, use the REST API to generate signed links. Use the signed link as a url parameter.

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

// your server
const requestHeaders: HeadersInit = new Headers();
requestHeaders.set("xi-api-key", process.env.XI_API_KEY); // use your ElevenLabs API key 

const response = await fetch(
    "https://api.elevenlabs.io/v1/convai/conversation/get_signed_url?agent_id={{agent id created through ElevenLabs UI}}",
    {
      method: "GET",
      headers: requestHeaders,
    }
);

if (!response.ok) {
    return Response.error();
}

const body = await response.json();
const url = body.signed_url; // use this URL for startConversation method.

endSession

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

await conversation.endSession();

setVolume

A method to set the output volume of the conversation. Accepts object with volume field between 0 and 1.

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

status

A React state containing the current status of the conversation.

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

isSpeaking

A React state containing the information of whether the agent is currently speaking. This is helpful for indicating the mode in your UI.

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