Using LiveKit WebRTC

Neuphonic supports LiveKit-compatible WebRTC connections, enabling you to connect to a voice agent directly from a browser, mobile app, or any LiveKit client SDK. This is the recommended approach for production web and mobile applications where low latency and native browser audio capture are important.

How it works

1. Your backend requests a short-lived token from the Neuphonic API for a given agent and room.
2. Your frontend uses that token to connect to the Neuphonic LiveKit server.
3. Once connected, the agent is automatically dispatched into the room and the conversation begins.

The Neuphonic LiveKit server URL is:

https://agents.neuphonic.com

Step 1 — Request a token

Tokens must be requested from your backend (never expose your API key in the browser). Call POST /agents/{agent_id}/token with a room_name of your choice.

curl -X POST "https://api.neuphonic.com/agents/<AGENT_ID>/token" \
     -H "X-API-KEY: <API_KEY>" \
     -H "Content-Type: application/json" \
     -d '{"room_name": "my-room", "api_key": "<API_KEY>"}'

The response contains the token and the room name:

{
  "data": {
    "token": "<LIVEKIT_JWT>",
    "room_name": "my-room"
  }
}

Optional agent parameters

Any additional fields in the request body are forwarded to the agent as metadata. You can use these to override the agent's voice, language, prompt, and audio settings, for example:

{
  "api_key": "<API_KEY>",
  "jwt_token": "<JWT_TOKEN>",
  "room_name": "my-room",
  "lang_code": "es",
  "voice_id": "<VOICE_ID>",
  "greeting": "¡Hola! ¿En qué puedo ayudarte?",
  "instructions": "You are a helpful Spanish-speaking assistant.",
  "mcp_servers": ["https://my-mcp-server.example.com"],
  "return_sampling_rate": 22050,
  "return_encoding": "pcm_linear",
  "incoming_sampling_rate": 16000,
  "incoming_encoding": "pcm_linear"
}

Step 2 — Connect with a LiveKit client

Pass the token and the Neuphonic LiveKit URL to any LiveKit client SDK. The agent is automatically dispatched into the room when you join. All LiveKit frontends are supported — see the LiveKit frontend SDKs for guides covering JavaScript, React, Swift, Kotlin, Flutter, and more.

JavaScript / TypeScript

Install the LiveKit client SDK:

npm install livekit-client @livekit/components-reac @livekit/components-styles

Then connect to the room:

'use client';

import {
  LiveKitRoom,
  useTranscriptions,
  AudioConference
} from '@livekit/components-react';
import '@livekit/components-styles';
import { useEffect, useRef } from 'react';

const LIVEKIT_URL = 'https://agents.neuphonic.com';

const Transcript = () => {
  const transcriptions = useTranscriptions();
  const scrollRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (scrollRef.current) {
      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
    }
  }, [transcriptions]);

  return (
    <div
      ref={scrollRef}
      className="flex min-h-0 flex-1 w-full flex-col gap-4 overflow-y-auto rounded-xl border border-slate-200 bg-white p-4 dark:border-neutral-700 dark:bg-neutral-800"
    >
      {transcriptions.length === 0 ? (
        <div className="flex h-full items-center justify-center text-sm text-gray-400 dark:text-neutral-500">
          Conversation will appear here...
        </div>
      ) : (
        transcriptions.map((t, idx) => {
          const isAgent = t.participantInfo.identity.startsWith('agent-');
          return (
            <div
              key={idx}
              className={`flex ${isAgent ? 'justify-start' : 'justify-end'}`}
            >
              <div
                className={`max-w-[80%] rounded-lg px-3 py-2 text-base ${
                  isAgent
                    ? 'text-neutral-700 dark:text-neutral-200'
                    : 'bg-themeContrast2 text-themeWhite shadow-md shadow-slate-300 dark:border dark:border-darkThemeSecondary/30 dark:bg-darkThemeSecondary/20 dark:shadow-neutral-800'
                }`}
              >
                {t.text}
              </div>
            </div>
          );
        })
      )}
    </div>
  );
};

export const Agent = ({ token }: { token: string }) => {
  return (
    <div>
      <LiveKitRoom
        serverUrl={LIVEKIT_URL}
        token={token}
        data-lk-theme="default"
        connect={true}
        audio={true}
      >
        <AudioConference />
        <Transcript />
      </LiveKitRoom>
    </div>
  );
};

tip

For browser applications, always request the token from your own backend and pass it to the frontend — never expose your Neuphonic API key in client-side code.

Reference

Token endpoint

Method	POST
Path	/agents/{agent_id}/token
Auth	X-API-KEY header

Request body

Field	Type	Required	Description
api_key	string	Yes*	Your Neuphonic API key. Required if jwt_token is not provided.
jwt_token	string	Yes*	Your Neuphonic JWT token. Required if api_key is not provided.
room_name	string	No	A name for the LiveKit room. A unique name is auto-generated if omitted.
greeting	string	No	Override the agent's opening greeting for this session.
instructions	string	No	Override the agent's system prompt for this session.
voice_id	string	No	Voice ID to use for TTS.
lang_code	string	No	Language code for the agent (e.g. en, es).
mcp_servers	string[]	No	List of MCP server URLs to make available to the agent.
return_sampling_rate	integer	No	Sample rate (Hz) of the audio returned by the agent. Defaults to 22050.
return_encoding	string	No	Encoding of the audio returned by the agent (e.g. pcm_linear).
incoming_sampling_rate	integer	No	Sample rate (Hz) of the audio you send to the agent. Defaults to 16000.
incoming_encoding	string	No	Encoding of the audio you send to the agent (e.g. pcm_linear, opus).

*Exactly one of api_key or jwt_token must be provided. These credentials are passed to the agent so it can authenticate with Neuphonic during the conversation.

Response

Field	Type	Description
data.token	string	A signed LiveKit JWT. Valid for one session.
data.room_name	string	The room name passed in the request.