ElevenLabs Voice Agent

ElevenLabs Conversational AI lets you create voice agents with cloned or synthetic voices. ElevenLabs agents normally think using a model you choose from their list. Instead, you point the agent at Pria’s Chat Completions API — ElevenLabs calls this a Custom LLM — so your Digital Twin does the thinking, with all its knowledge and tools, while ElevenLabs handles listening and speaking. No additional backend code required.

This integration combines ElevenLabs’ voice synthesis and real-time audio with your Digital Twin’s knowledge, personality, and tools.

How It Works

ElevenLabs Agent

Handles voice input/output, speech-to-text, text-to-speech, and the real-time audio stream.

Chat Completions API

Receives OpenAI-compatible requests from ElevenLabs and routes them to your Digital Twin.

Digital Twin

Generates intelligent responses using its knowledge base, tools, assistants, and conversation memory.

User speaks → ElevenLabs (STT) → Chat Completions API → Digital Twin → Response → ElevenLabs (TTS) → User hears

Prerequisites

Before you begin, make sure you have:

An ElevenLabs account with access to Conversational AI Agents
A voice created (and, if cloned, trained) in ElevenLabs
A Praxis AI account with at least one Digital Twin configured
Your Digital Twin’s Public ID (a UUID found in the administration panel)

Step 1: Create an ElevenLabs Agent

Go to the ElevenLabs Dashboard

Navigate to Conversational AI in your ElevenLabs account and create a new agent.

Choose a voice

Select a stock voice, or use ElevenLabs’ voice cloning to create a custom voice that matches your Digital Twin’s persona.

Configure the system prompt

The Digital Twin manages its own system instructions server-side. Use the ElevenLabs system prompt for voice-specific behavior only (e.g., greeting style, conversation pacing).

First Message

Type a greeting, for example Hey there, ready to learn something new together?

LLM

Select Custom LLM

Step 2: Connect to Custom LLM

This is the core configuration — tell your ElevenLabs agent to use your Digital Twin as its language model.

Open LLM settings

In your agent’s settings, go to the LLM section and select Custom LLM.

Set the Server URL

Enter your Chat Completions API base URL:

https://pria.praxislxp.com/api/ai

Set the Model ID

Enter your Digital Twin’s Public ID as the model:

e455529a-4f51-479e-94fc-bbebb41d19a1

ElevenLabs includes this value as the model parameter on every request. Note that the Digital Twin that actually serves the request is resolved from the user’s x_access_token — or the x-praxis-institution-public-id header when targeting a specific Twin — as described in the Chat Completions API docs.

API Key

In the API Key section of your ElevenLabs custom-LLM dashboard, select your ElevenLabs API Key or create a new one.

Save this same API Key in your Digital Twin’s configuration in Praxis (see Step 4) — Pria uses it server-side to start Convo Mode sessions with your agent.

Step 3: Configure Dynamic Variables

Dynamic variables let you pass user identity and conversation context from the client application through ElevenLabs to your Digital Twin. These are mapped to the x-praxis-* request headers that the Chat Completions API forwards to Praxis.

Define Variables in ElevenLabs

In your agent’s settings, define the custom header mapping to dynamic variables:

Header	Description	Dynamic Variable
`x-access-token`	Praxis JWT for user authentication	`x_access_token`
`x-praxis-conversation-id`	Numeric conversation/course identifier	`x_praxis_conversation_id`
`x-praxis-assistant-id`	Assistant to execute during the conversation	`x_praxis_assistant_id`
`x-praxis-institution-public-id`	Override the target Digital Twin when using the voice agent for multiple Twins	`x_praxis_institution_public_id`

x_access_token carries the signed-in user’s own Praxis token. Pria uses it to answer as that user — with their permissions and their conversation history — so the voice agent never has more access than the person using it.

This is the example JSON configuration for your Agent’s custom LLM:

Don’t forget to publish your changes after making updates.

How Variables Flow

Client widget passes dynamic variables at session start
        ↓
ElevenLabs injects variables into custom headers + system prompt
        ↓
Chat Completions API extracts x-praxis-* headers
        ↓
Digital Twin receives full conversation context

Pria reads the context exclusively from the x-praxis-* HTTP headers, so configure the custom-header mapping shown above. ElevenLabs’ Extra Body option (which copies dynamic variables into the request body under elevenlabs_extra_body) is not read by Pria — headers are the required channel.

Step 4: Configure Your Digital Twin

Now set the Praxis side up, in the Admin dashboard with your Digital Twin open.

The order matters. The ElevenLabs credential fields don’t exist until the twin is set to speak through ElevenLabs — so turn Convo on and pick the model first, and the boxes appear.

Turn on the Chat Completions endpoint

On Configuration and Integrations, in the Chat Completion section, tick Enable Chat Completion endpoint.

This one is easy to miss and breaks everything. It is off until someone turns it on, and it’s the door ElevenLabs knocks on — without it every spoken turn is refused and your agent connects, listens, and then says nothing. See the Chat Completions API for the overrides it reveals.

Turn on Convo

Still on Configuration and Integrations, under Realtime / Convo, tick Enable Convo (Speech-to-Speech).

Choose ElevenLabs as the voice

On Personalization and AI Models, set Speech-to-Speech Model to an ElevenLabs model.

Enter the credentials

Return to Configuration and Integrations, where an ElevenLabs Voice Cloning section has now appeared:

ElevenLabs Agent ID (for Digital Twin Voice) — the agent_… identifier from your ElevenLabs dashboard
ElevenLabs API Key — the same key from Step 2. Pria uses it server-side to start each conversation with your agent; it is never exposed to the browser
ElevenLabs Connection Method — see below

If ElevenLabs is the chosen voice but the Agent ID or API Key are missing, a warning pill appears pointing you back here.

Start a conversation

Users can now press the Convo button and speak to the Digital Twin.

See Configuration — ElevenLabs for full details on the credential fields.

You don’t pick the voice in Praxis. The voice is whichever one your ElevenLabs agent is set to — change it in your ElevenLabs agent configuration.

Connection Method

ElevenLabs Connection Method decides how the audio travels between the listener’s browser and ElevenLabs:

Method	Description
WebSocket (default)	Relayed through a server. The safest choice — it behaves on corporate and campus networks
WebRTC	A direct connection, lower latency, but often blocked by strict firewalls

Start on the default and only try WebRTC if you want to shave latency and your users aren’t behind restrictive networks. If you switched to WebRTC and people report connection failures, switch back.

Step 5: Deploy Client Widgets (optional)

ElevenLabs provides multiple ways to embed a voice agent in your application. Each method supports passing dynamic variables at session start. The simplest option — add two lines to any web page:

<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

<elevenlabs-convai agent-id="YOUR_ELEVENLABS_AGENT_ID"></elevenlabs-convai>

Pin to a specific version on a live site: @elevenlabs/convai-widget-embed@1.0.0

React Integration

For React applications, use the @elevenlabs/react package with dynamic variables:

import { useConversation } from "@elevenlabs/react";

export function DigitalTwinVoice({ praxisToken, courseId, assistantId, publicId }) {
  const conversation = useConversation({
    agentId: "YOUR_ELEVENLABS_AGENT_ID",
    dynamicVariables: {
      x_access_token: praxisToken,
      x_praxis_conversation_id: courseId,
      x_praxis_assistant_id: assistantId,
      x_praxis_institution_public_id: publicId,
    },
  });

  const handleStart = async () => {
    await navigator.mediaDevices.getUserMedia({ audio: true });
    await conversation.startSession();
  };

  return (
    <div>
      <button onClick={handleStart}>
        Talk to your Digital Twin
      </button>
      {conversation.status === "connected" && (
        <button onClick={() => conversation.endSession()}>
          End Conversation
        </button>
      )}
    </div>
  );
}

Install the dependency:

npm install @elevenlabs/react

JavaScript SDK (Vanilla)

For non-React applications, use the @elevenlabs/client SDK directly:

import { Conversation } from "@elevenlabs/client";

const conversation = await Conversation.startSession({
  agentId: "YOUR_ELEVENLABS_AGENT_ID",
  connectionType: "webrtc",
  dynamicVariables: {
    x_access_token: "your-praxis-jwt-token",
    x_praxis_conversation_id: "48201",
    x_praxis_assistant_id: "69956bf0c8510d46974a11a6",
    x_praxis_institution_public_id: "f831501f-b645-481a-9cbb-331509aaf8c1",
  },
  onMessage: (message) => {
    console.log(`${message.source}: ${message.message}`);
  },
  onError: (error) => {
    console.error("Conversation error:", error);
  },
  onStatusChange: (status) => {
    console.log("Status:", status);
  },
});

// End the session when done
await conversation.endSession();

Install the dependency:

npm install @elevenlabs/client

Securing Private Agents

On a live site, use signed URLs to prevent unauthorized access to your ElevenLabs agent.

Generate a signed URL on your server

// Server-side (Node.js)
app.get("/api/voice-session", async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${AGENT_ID}`,
    {
      headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY },
    }
  );
  const data = await response.json();
  res.json({ signedUrl: data.signed_url });
});

Use the signed URL on the client

const { signedUrl } = await fetch("/api/voice-session").then(r => r.json());

const conversation = useConversation({
  signedUrl: signedUrl,
  dynamicVariables: {
    x_access_token: praxisToken,
    x_praxis_conversation_id: courseId,
    x_praxis_assistant_id: assistantId,
  },
});

Never expose your ElevenLabs API key in client-side code. Always generate signed URLs from your backend. Signed URLs expire after 15 minutes.

You can also configure an allowlist of approved domains in your agent’s Security tab to restrict where the widget can be embedded.

A complete React component that authenticates with your backend, starts a voice session with a Digital Twin, and displays the conversation transcript:

import React, { useState, useCallback } from "react";
import { useConversation } from "@elevenlabs/react";

export function SupportWidget({ praxisToken, courseId, assistantId, publicId }) {
  const [messages, setMessages] = useState([]);

  const conversation = useConversation({
    agentId: "YOUR_ELEVENLABS_AGENT_ID",
    dynamicVariables: {
      x_access_token: praxisToken,
      x_praxis_conversation_id: String(courseId),
      x_praxis_assistant_id: assistantId,
      x_praxis_institution_public_id: publicId,
    },
    onMessage: (msg) => {
      setMessages((prev) => [
        ...prev,
        { role: msg.source === "ai" ? "assistant" : "user", text: msg.message },
      ]);
    },
  });

  const toggle = useCallback(async () => {
    if (conversation.status === "connected") {
      await conversation.endSession();
    } else {
      await navigator.mediaDevices.getUserMedia({ audio: true });
      await conversation.startSession();
    }
  }, [conversation]);

  return (
    <div style={{ maxWidth: 400, margin: "0 auto", fontFamily: "sans-serif" }}>
      <button onClick={toggle}>
        {conversation.status === "connected" ? "End" : "Start"} Conversation
      </button>

      <div style={{ marginTop: 16 }}>
        {messages.map((m, i) => (
          <p key={i}>
            <strong>{m.role === "assistant" ? "Twin" : "You"}:</strong> {m.text}
          </p>
        ))}
      </div>
    </div>
  );
}

Troubleshooting

Symptom	Cause	Fix
Agent connects, then says nothing	Chat Completions is switched off for the Digital Twin — every turn is refused with `chat_completion_disabled`	Tick Enable Chat Completion endpoint (Step 4)
Agent responds but has no knowledge	Model ID is wrong	Verify the Digital Twin Public ID in the LLM model field
401 from Chat Completions API	The JWT has expired	Refresh the `x_access_token` dynamic variable
403 `Authentication Required`	No token reached Pria at all	Check the `x-access-token` custom-header mapping is published on the agent
The ElevenLabs credential boxes aren’t there	The twin isn’t set to speak through ElevenLabs yet	Enable Convo and set Speech-to-Speech Model to an ElevenLabs model first
No audio from agent	Microphone not granted	Check browser permissions; call `getUserMedia` before `startSession`
Agent is silent after connecting	ElevenLabs can’t reach your API	Verify the Custom LLM server URL is publicly accessible
Connection fails on a campus or office network	WebRTC is blocked	Set ElevenLabs Connection Method back to WebSocket
”LiveKit v1” 404 in console	Normal SDK behavior	Benign version negotiation — safe to ignore

Chat Completions API — Set up the OpenAI-compatible endpoint that powers this integration
Web SDK — Embed the full Digital Twin UI (text + voice) in your app
ElevenLabs Custom LLM Docs — Official ElevenLabs configuration reference
ElevenLabs Dynamic Variables — How variables flow through the agent

Overview

Getting Started

Authentication

REST API

Runtime API

Administrator API

JavaScript SDK

Web & Chat Integrations

LMS Integrations

Voice & Avatars

MCP Server

Other Services

ElevenLabs Voice Agent

How It Works

ElevenLabs Agent

Chat Completions API

Digital Twin

Prerequisites

Step 1: Create an ElevenLabs Agent

Step 2: Connect to Custom LLM

Step 3: Configure Dynamic Variables

Define Variables in ElevenLabs

How Variables Flow

Step 4: Configure Your Digital Twin

Connection Method

Step 5: Deploy Client Widgets (optional)

HTML Widget

React Integration

JavaScript SDK (Vanilla)

Securing Private Agents

Full Example: Embeddable Support Widget

Troubleshooting

​How It Works

ElevenLabs Agent

Chat Completions API

Digital Twin

​Prerequisites

​Step 1: Create an ElevenLabs Agent

​Step 2: Connect to Custom LLM

​Step 3: Configure Dynamic Variables

​Define Variables in ElevenLabs

​How Variables Flow

​Step 4: Configure Your Digital Twin

​Connection Method

​Step 5: Deploy Client Widgets (optional)

​HTML Widget

​React Integration

​JavaScript SDK (Vanilla)

​Securing Private Agents

​Full Example: Embeddable Support Widget

​Troubleshooting

​Related

How It Works

Prerequisites

Step 1: Create an ElevenLabs Agent

Step 2: Connect to Custom LLM

Step 3: Configure Dynamic Variables

Define Variables in ElevenLabs

How Variables Flow

Step 4: Configure Your Digital Twin

Connection Method

Step 5: Deploy Client Widgets (optional)

HTML Widget

React Integration

JavaScript SDK (Vanilla)

Securing Private Agents

Full Example: Embeddable Support Widget

Troubleshooting

Related