JavaScript SDK
Conversational AI SDK: deploy customized, interactive voice agents in minutes.
Also see the Conversational AI overview
Installation
Install the package in your project through package manager.
Usage
This library is primarily meant for development in vanilla JavaScript projects, or as a base for libraries tailored to specific frameworks. It is recommended to check whether your specific framework has it’s own library. However, you can use this library in any JavaScript-based project.
Initialize conversation
First, initialize the Conversation instance:
This will kick off the websocket connection and start using microphone to communicate with the ElevenLabs Conversational AI agent. Consider explaining and allowing microphone access in your apps UI before the Conversation kicks off:
Session configuration
The options passed to startSession
specifiy how the session is established. There are two ways to start a session:
Using Agent ID
Agent ID can be acquired through ElevenLabs UI. For public agents, you can use the ID directly:
Using a signed URL
If the conversation requires authorization, you will need to add a dedicated endpoint to your server that will request a signed url using the ElevenLabs API and pass it back to the client.
Here’s an example of how it could be set up:
Optional callbacks
The options passed to startSession
can also be used to register optional callbacks:
- 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 text message is received. These can be tentative or final transcriptions of user voice, replies produced by LLM. Primarily used for handling conversation transcription.
- onError - handler called when an error is encountered.
- onStatusChange - handler called whenever connection status changes. Can be
connected
,connecting
anddisconnected
(initial). - onModeChange - handler called when a status changes, eg. agent switches from
speaking
tolistening
, or the other way around.
Return value
startSession
returns a Conversation
instance that can be used to control the session. The method will throw an error if the session cannot be established. This can happen if the user denies microphone access, or if the websocket connection
fails.
endSession
A method to manually end the conversation. The method will end the conversation and disconnect from websocket. Afterwards the conversation instance will be unusable and can be safely discarded.
getId
A method returning the conversation ID.
setVolume
A method to set the output volume of the conversation. Accepts object with volume field between 0 and 1.
getInputVolume / getOutputVolume
Methods that return the current input/output volume on a scale from 0
to 1
where 0
is -100 dB and 1
is -30 dB.
getInputByteFrequencyData / getOutputByteFrequencyData
Methods that return Uint8Array
s containg the current input/output frequency data. See AnalyserNode.getByteFrequencyData for more information.