write sample code in nodejs to create outbound cal...
# ask-ail
late-glass-71191
12/29/2025, 10:24 PMwrite sample code in nodejs to create outbound call agent
t
tall-airline-16756
12/29/2025, 10:24 PMThanks for reaching out, Anirban. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
tall-airline-16756
12/29/2025, 10:24 PMThanks — I’ll help with a concise Node.js example to create an outbound call agent using LiveKit’s server SDK and the Agents API.
Which environment do you want this for?
• A LiveKit Agent worker (JobContext) that dials out from a room, or
• A standalone Node.js script using the LiveKit Server SDK to create a SIP participant directly?
If you confirm, I’ll provide the exact code for that environment (including required imports and a minimal package example).
Sources: Agents telephony integration | LiveKit docs | Outbound Calling Script | LiveKit docs | SIP Lifecycle Management Agent | LiveKit docs
l
late-glass-71191
12/29/2025, 10:29 PMA LiveKit Agent worker (JobContext) that dials out from a room
t
tall-airline-16756
12/29/2025, 10:30 PMThanks — responding to your request for a LiveKit Agent worker (JobContext) that dials out from a room.
Below is a minimal, ready-to-run Node.js agent using
defineAgentRoomServiceClientlivekit-server-sdk Copy code
// outbound-agent.ts
import dotenv from "dotenv";
import { defineAgent, JobContext } from "@livekit/agents";
import { RoomServiceClient } from "livekit-server-sdk";
dotenv.config();
export default defineAgent({
entry: async (ctx: JobContext) => {
// Expect job.metadata to be a JSON string containing { "phone_number": "+15105550123" }
let metadata: any = {};
try {
metadata = ctx.job.metadata ? JSON.parse(ctx.job.metadata) : {};
} catch (e) {
console.error("Invalid job.metadata JSON:", e);
await ctx.aclose();
return;
}
const phoneNumber = metadata.phone_number;
if (!phoneNumber) {
console.error("No phone_number found in job.metadata");
await ctx.aclose();
return;
}
const livekitUrl = process.env.LIVEKIT_URL!;
const livekitKey = process.env.LIVEKIT_API_KEY!;
const livekitSecret = process.env.LIVEKIT_API_SECRET!;
const sipTrunkId = process.env.SIP_TRUNK_ID!; // configured in LiveKit console
if (!livekitUrl || !livekitKey || !livekitSecret || !sipTrunkId) {
console.error("Missing one of LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, SIP_TRUNK_ID");
await ctx.aclose();
return;
}
const roomName = ctx.room.name; // ensure agent was dispatched to a room
const participantIdentity = `outbound-${phoneNumber.replace(/\D/g, "")}`;
const roomService = new RoomServiceClient(livekitUrl, livekitKey, livekitSecret);
try {
await roomService.createSIPParticipant({
room: roomName,
sipTrunkId,
sipCallTo: phoneNumber,
participantIdentity,
participantName: "Outbound Caller",
waitUntilAnswered: true,
});
console.log(`Call initiated to ${phoneNumber} and joined room ${roomName}`);
} catch (err) {
console.error("Error creating SIP participant:", err);
} finally {
// close underlying http client if available
try { roomService.httpClient?.close(); } catch {}
await ctx.aclose();
}
},
});job.metadataphone_numberl
late-glass-71191
12/29/2025, 10:43 PMrouter.post('/initiate', async (req, res) => {
try {
const {
trunkId,
fromNumber,
toNumber,
roomName,
displayName,
participantMetadata,
} = req.body;
if (!trunkId || !fromNumber || !toNumber) {
return res.status(400).json({
success: false,
message: 'Missing required fields: agentId, trunkId, fromNumber, toNumber',
});
}
const phoneRegex = /^\+\d{10,15}$/;
if (!phoneRegex.test(toNumber)) {
return res.status(400).json({
success: false,
message: 'Invalid phone number format. Use E.164 format (e.g., +12135550100)',
});
}
const result = await livekitService.initiateCall(
trunkId,
fromNumber,
toNumber,
);
res.json({
success: true,
message: result.message,
data: result,
});
return
} catch (error: any) {
console.error('Failed to initiate call:', error);
if (error.message.includes('SIP Error')) {
return res.status(400).json({
success: false,
message: 'Call failed',
error: error.message,
});
}
res.status(500).json({
success: false,
message: 'Failed to initiate call',
error: error.message,
});
return
}
})
i have a router that initiates call to the phone number but upon receiving there is no agent voice / response
export default defineAgent({
prewarm: async (proc: JobProcess) => {
console.log('Prewarming agent...');
// Load Silero VAD model for voice activity detection
proc.userData.vad = await silero.VAD.load();
console.log('VAD model loaded successfully');
},
entry: async (ctx: JobContext) => {
const agentId = process.env.AGENT_ID || 'unknown';
const agentName = process.env.AGENT_NAME || '{{AGENT_NAME}}';
await ctx.connect();
console.log('Connected to LiveKit room');
// Wait for a participant to join
const participant = await ctx.waitForParticipant();
console.log(
Participant joined: ${participant.identity}Call record created: ${currentCallId}Usage: ${JSON.stringify(summary)}t
tall-airline-16756
12/29/2025, 10:43 PMThanks — I see the problem: calls connect but the agent's voice isn't heard. I'll help troubleshoot the audio path so the agent's TTS/stt session actually sends audio into the SIP participant.
A few quick clarifying questions first:
1. When the SIP participant answers, do you see the SIP participant in the room list (participant identity) and any published audio tracks in LiveKit logs?
2. Do your agent logs show the TTS model producing audio bytes (or any TTS success messages) after
session.generateReply({ instructions: ... })l
late-glass-71191
12/29/2025, 10:52 PM2025-12-30T034318: [dotenv@17.2.3] injecting env (0) from .env.local -- tip: 👥 sync secrets across teammates & machines: https://dotenvx.com/ops
2025-12-30T034318: [dotenv@17.2.3] injecting env (0) from .env.local -- tip: ⚙️ override existing env vars with { override: true }
2025-12-30T034319: [034318.915] [32mINFO[39m (152273): [36mstarting worker[39m
2025-12-30T034319: version: "0.1.0"
2025-12-30T034319: [034318.953] [32mINFO[39m (152273): [36mServer is listening on port 42357[39m
2025-12-30T034319: [034319.192] [32mINFO[39m (152273): [36mregistered worker[39m
2025-12-30T034319: version: "0.1.0"
2025-12-30T034319: id: "AW_Fo37bzeDQ2ns"
2025-12-30T034319: server_info: {
2025-12-30T034319: "edition": "Cloud",
2025-12-30T034319: "version": "1.9.9",
2025-12-30T034319: "protocol": 16,
2025-12-30T034319: "region": "India West",
2025-12-30T034319: "nodeId": "NC_OMUMBAI1A_EPdvUoGC8cT9",
2025-12-30T034319: "debugInfo": "",
2025-12-30T034319: "agentProtocol": 0
2025-12-30T034319: }
my agent logs
t
tall-airline-16756
12/29/2025, 10:52 PMThanks — I see your agent started and registered a worker (Cloud, v1.9.9). You’ve provided the startup logs which confirm the agent process and worker registration, but those logs don’t show TTS, publishing, or SIP events yet.
To troubleshoot why the agent’s voice isn’t heard, please provide or check the following (quick checklist + targeted next steps):
1) Confirm SIP participant in room
• After the SIP call answers, do you see the SIP participant in the room list? Check LiveKit room participant list or add logging when ctx.waitForParticipant() returns (you already log identity — confirm it matches the phone number).
2) TTS generation logs
• Add/attach logs showing TTS output bytes or success confirmation right after your TTS call (the place where session.generateReply or the TTS provider returns audio). Example: log the returned buffer length and format (sample rate, channels).
3) Confirm publishing of audio track
• Ensure the agent session actually publishes the generated TTS audio as an outgoing audio track to the room. Add a log where the session/agent publishes with the track id/name and confirm LiveKit reports a published track event for the agent.
4) Test with a known WAV file
• Temporarily bypass TTS and publish a short 48kHz mono PCM WAV (e.g., a spoken “hello”) from the agent into the room to isolate TTS vs publish/transcoding issues.
5) Check codec & trunk expectations
• What codec does your SIP trunk require (PCMU/PCMA/opus)? If the trunk uses PCMU/PCMA and the agent publishes Opus, ensure LiveKit or the trunk is configured to transcode or map codecs. Add logs for any codec-negotiation or RTP errors.
6) VAD gating
• Disable VAD temporarily to ensure it’s not suppressing agent playback. VAD can block audio if levels or timing look like silence.
7) Enable verbose LiveKit and agent logs
• Increase logging around publish/subscribe and room events so you capture:
◦ participant joined/left
◦ track published/updated/unpublished
◦ any codec or RTP warnings/errors
Share those logs (especially around the time the call answers and when session.generateReply runs).
If you want, I can provide:
• A small code snippet to log TTS buffer details and force-publish a WAV into the room, or
• A snippet to disable VAD temporarily.
Which would you like next, and can you paste logs for: (A) participant join + track published events, and (B) TTS generation output?
l
late-glass-71191
12/29/2025, 10:52 PMinbpound calls work perfectly
t
tall-airline-16756
12/29/2025, 10:53 PMThanks — good to know inbound calls work perfectly. That tells us SIP connectivity and the SIP->room audio path are OK, so the problem is likely in how the agent’s TTS/audio is produced or published for outbound calls.
Quick checklist and focused next steps to isolate & fix the issue:
1) Confirm agent is publishing after outbound connect
• Add a log after the agent publishes any audio track. Look for LiveKit events: participant published track, trackSubscribed. If you don’t see a published track for the agent when the SIP participant is present, publishing is the issue.
2) Verify TTS output exists and format
• Log the TTS result right after generation: buffer length, sample rate, channels, and format. Example logs: “TTS produced N bytes — 16-bit PCM, 16000 Hz, mono”.
• If the buffer is empty or too short, the TTS step failed.
3) Force-test publishing a known WAV
• Temporarily bypass TTS and publish a test 48kHz mono PCM WAV (short spoken “hello”) from the agent into the room. If SIP hears it, publishing/transcoding works and TTS integration is the culprit.
4) Check codec expectations and transcoding
• Inbound working implies the trunk is configured correctly, but for outbound confirm the trunk can accept whatever codec the agent publishes (typically Opus). If the trunk only accepts PCMU/PCMA, ensure LiveKit or the trunk transcodes Opus -> PCMU/PCMA.
5) Disable VAD temporarily
• VAD can suppress outgoing audio. Disable or bypass VAD to confirm it isn’t gating the TTS playback.
6) Confirm you’re targeting the same room participant
• Make sure the SIP participant is actually subscribing to the agent’s published track (agent publishes -> room forwards -> SIP leg subscribed). Log participant identities and subscription events to verify routing.
If you want, I can provide any of these immediately:
• A small code snippet to log TTS buffer details,
• A snippet to publish a local 48kHz WAV into the room from your agent,
• Example code to temporarily disable VAD or bypass it for TTS playback,
• Logging additions to capture participant/track events.
Which snippet would you like first? Also paste any logs showing track published/subscribed events around the outbound call answer time and any TTS-generation logs you have.
l
late-glass-71191
12/30/2025, 3:09 PMfrom future import annotations
import asyncio
import logging
from dotenv import load_dotenv
import json
import os
from typing import Any
from livekit import rtc, api
from livekit.agents import (
AgentSession,
Agent,
JobContext,
function_tool,
RunContext,
get_job_context,
cli,
WorkerOptions,
RoomInputOptions,
)
from livekit.plugins import (
deepgram,
openai,
cartesia,
silero,
noise_cancellation, # noqa: F401
)
from livekit.plugins.turn_detector.english import EnglishModel
# load environment variables, this is optional, only used for local development
load_dotenv(dotenv_path=".env.local")
logger = logging.getLogger("outbound-caller")
logger.setLevel(logging.INFO)
outbound_trunk_id = os.getenv("SIP_OUTBOUND_TRUNK_ID")
class OutboundCaller(Agent):
def __init__(
self,
*,
name: str,
appointment_time: str,
dial_info: dict[str, Any],
):
super().__init__(
instructions=f"""
You are a scheduling assistant for a dental practice. Your interface with user will be voice.
You will be on a call with a patient who has an upcoming appointment. Your goal is to confirm the appointment details.
As a customer service representative, you will be polite and professional at all times. Allow user to end the conversation.
When the user would like to be transferred to a human agent, first confirm with them. upon confirmation, use the transfer_call tool.
The customer's name is {name}. His appointment is on {appointment_time}.
"""
)
# keep reference to the participant for transfers
self.participant: rtc.RemoteParticipant | None = None
self.dial_info = dial_info
def set_participant(self, participant: rtc.RemoteParticipant):
self.participant = participant
async def hangup(self):
"""Helper function to hang up the call by deleting the room"""
job_ctx = get_job_context()
await job_ctx.api.room.delete_room(
api.DeleteRoomRequest(
room=job_ctx.room.name,
)
)
@function_tool()
async def transfer_call(self, ctx: RunContext):
"""Transfer the call to a human agent, called after confirming with the user"""
transfer_to = self.dial_info["transfer_to"]
if not transfer_to:
return "cannot transfer call"
logger.info(f"transferring call to {transfer_to}")
# let the message play fully before transferring
await ctx.session.generate_reply(
instructions="let the user know you'll be transferring them"
)
job_ctx = get_job_context()
try:
await job_ctx.api.sip.transfer_sip_participant(
api.TransferSIPParticipantRequest(
room_name=job_ctx.room.name,
participant_identity=self.participant.identity,
transfer_to=f"tel:{transfer_to}",
)
)
logger.info(f"transferred call to {transfer_to}")
except Exception as e:
logger.error(f"error transferring call: {e}")
await ctx.session.generate_reply(
instructions="there was an error transferring the call."
)
await self.hangup()
@function_tool()
async def end_call(self, ctx: RunContext):
"""Called when the user wants to end the call"""
logger.info(f"ending the call for {self.participant.identity}")
# let the agent finish speaking
current_speech = ctx.session.current_speech
if current_speech:
await current_speech.wait_for_playout()
await self.hangup()
@function_tool()
async def look_up_availability(
self,
ctx: RunContext,
date: str,
):
"""Called when the user asks about alternative appointment availability
Args:
date: The date of the appointment to check availability for
"""
logger.info(
f"looking up availability for {self.participant.identity} on {date}"
)
await asyncio.sleep(3)
return {
"available_times": ["1pm", "2pm", "3pm"],
}
@function_tool()
async def confirm_appointment(
self,
ctx: RunContext,
date: str,
time: str,
):
"""Called when the user confirms their appointment on a specific date.
Use this tool only when they are certain about the date and time.
Args:
date: The date of the appointment
time: The time of the appointment
"""
logger.info(
f"confirming appointment for {self.participant.identity} on {date} at {time}"
)
return "reservation confirmed"
@function_tool()
async def detected_answering_machine(self, ctx: RunContext):
"""Called when the call reaches voicemail. Use this tool AFTER you hear the voicemail greeting"""
logger.info(f"detected answering machine for {self.participant.identity}")
await self.hangup()
async def entrypoint(ctx: JobContext):
logger.info(f"connecting to room {ctx.room.name}")
await ctx.connect()
# when dispatching the agent, we'll pass it the approriate info to dial the user
# dial_info is a dict with the following keys:
# - phone_number: the phone number to dial
# - transfer_to: the phone number to transfer the call to when requested
dial_info = json.loads(ctx.job.metadata)
participant_identity = phone_number = dial_info["phone_number"]
# look up the user's phone number and appointment details
agent = OutboundCaller(
name="Jayden",
appointment_time="next Tuesday at 3pm",
dial_info=dial_info,
)
# the following uses GPT-4o, Deepgram and Cartesia
session = AgentSession(
turn_detection=EnglishModel(),
vad=silero.VAD.load(),
stt=deepgram.STT(),
# you can also use OpenAI's TTS with openai.TTS()
tts=cartesia.TTS(),
llm=openai.LLM(model="gpt-4o"),
# you can also use a speech-to-speech model like OpenAI's Realtime API
# llm=openai.realtime.RealtimeModel()
)
# start the session first before dialing, to ensure that when the user picks up
# the agent does not miss anything the user says
session_started = asyncio.create_task(
session.start(
agent=agent,
room=ctx.room,
room_input_options=RoomInputOptions(
# enable Krisp background voice and noise removal
noise_cancellation=noise_cancellation.BVCTelephony(),
),
)
)
#
create_sip_participantt
tall-airline-16756
12/30/2025, 3:09 PMThanks — I’ll explain how this outbound agent works and how it knows which call to attend.
High-level flow
• The agent is an Agent subclass (OutboundCaller) that contains call-related helpers (transfer, end, hangup) and keeps a reference to the SIP participant in
self.participantdial_infoawait ctx.connect()dial_infoctx.job.metadataparticipant_identityctx.api.sip.create_sip_participant(...)wait_until_answered=Truectx.wait_for_participant(identity=participant_identity)ctx.job.metadatadial_infophone_numberparticipant_identityctx.wait_for_participant(identity=participant_identity)self.participantself.dial_infotransfer_callend_calllook_up_availabilityconfirm_appointmentdetected_answering_machine@function_tool()hangup()session.start(agent=agent, room=ctx.room, ...)session.generate_reply(...)ctx.api.sip.create_sip_participant(...)wait_until_answered=Trueapi.TwirpErrorctx.shutdown()transfer_callend_callctx.job.metadatadial_infotransfer_toparticipant_identityctx.wait_for_participant(...)l
late-glass-71191
12/30/2025, 3:18 PMcould you build similar outbound caller using nodejs
t
tall-airline-16756
12/30/2025, 3:18 PMThanks — I’ll provide a concise Node.js outbound caller agent that mirrors your Python example: it starts an AgentSession (STT, TTS, VAD, LLM), dials with createSIPParticipant, waits for the SIP participant, and ties the session to that call via participant identity.
Save as outbound-agent.ts (TypeScript; works in Node with ts-node or compiled). Set env vars: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, SIP_OUTBOUND_TRUNK_ID.
Copy code
import dotenv from "dotenv";
import { defineAgent, JobContext, Agent, RunContext, function_tool, get_job_context, cli, WorkerOptions } from "@livekit/agents";
import { RoomInputOptions } from "@livekit/agents";
import { api } from "livekit"; // server API types
import { AgentSession } from "@livekit/agents";
import * as rtc from "@livekit/rtc"; // types
import * as plugins from "@livekit/plugins"; // STT/TTS/VAD plugins (Deepgram/Cartesia/Silero etc.)
import { EnglishModel } from "@livekit/plugins/turn_detector/english";
dotenv.config();
const OUTBOUND_TRUNK_ID = process.env.SIP_OUTBOUND_TRUNK_ID!;
class OutboundCaller extends Agent {
participant?: rtc.RemoteParticipant;
dialInfo: any;
constructor(opts: { name: string; appointmentTime: string; dialInfo: any }) {
super({
instructions: `You are a scheduling assistant for a dental practice. Use voice to confirm the appointment for ${opts.name} at ${opts.appointmentTime}.`,
});
this.dialInfo = opts.dialInfo;
}
setParticipant(p: rtc.RemoteParticipant) { this.participant = p; }
async hangup() {
const jobCtx = get_job_context();
await jobCtx.api.room.deleteRoom({ room: jobCtx.room.name });
}
@function_tool()
async transfer_call(ctx: RunContext) {
const transferTo = this.dialInfo.transfer_to;
if (!transferTo) return "no transfer target";
await ctx.session.generate_reply({ instructions: "Notifying user of transfer" });
const jobCtx = get_job_context();
await jobCtx.api.sip.transferSIPParticipant({
roomName: jobCtx.room.name,
participantIdentity: this.participant!.identity,
transferTo: `tel:${transferTo}`,
} as any);
await this.hangup();
return `transferred to ${transferTo}`;
}
@function_tool()
async end_call(ctx: RunContext) {
const cur = ctx.session.current_speech;
if (cur) await cur.wait_for_playout();
await this.hangup();
}
}
export default defineAgent({
entry: async (ctx: JobContext) => {
console.log(`connecting to room ${ctx.room.name}`);
await ctx.connect();
// Expect job.metadata to be JSON with { "phone_number": "+1...", "transfer_to": "...", ... }
const dialInfo = ctx.job.metadata ? JSON.parse(String(ctx.job.metadata)) : {};
const phoneNumber = dialInfo.phone_number;
const participantIdentity = phoneNumber;
const agent = new OutboundCaller({ name: "Jayden", appointmentTime: "next Tuesday at 3pm", dialInfo });
// Build session with desired plugins (replace with your configured providers)
const session = new AgentSession({
turn_detection: new EnglishModel(),
vad: await plugins.silero.VAD.load(),
stt: new plugins.deepgram.STT({ apiKey: process.env.DEEPGRAM_API_KEY }),
tts: new plugins.cartesia.TTS({ apiKey: process.env.CARTESIA_API_KEY }),
llm: new plugins.openai.LLM({ apiKey: process.env.OPENAI_API_KEY, model: "gpt-4o" }),
});
// Start session before dialing so it's ready to publish
const sessionStarted = session.start({
agent,
room: ctx.room,
room_input_options: new RoomInputOptions({
noise_cancellation: new plugins.noise_cancellation.BVCTelephony(),
}),
});
try {
// Dial outbound via SIP trunk; waitUntilAnswered blocks until answer or error
await ctx.api.sip.createSIPParticipant({
roomName: ctx.room.name,
sipTrunkId: OUTBOUND_TRUNK_ID,
sipCallTo: phoneNumber,
participantIdentity,
waitUntilAnswered: true,
} as any);
// ensure session started
await sessionStarted;
// wait specifically for the SIP participant to join
const participant = await ctx.waitForParticipant({ identity: participantIdentity } as any);
console.log(`participant joined: ${participant.identity}`);
agent.setParticipant(participant);
// Optionally generate a greeting now that participant is present
await session.generate_reply({ instructions: "Say a friendly greeting and confirm appointment details." });
// Keep agent alive until session closes (AgentSession emits Close)
await session.closed; // waits until session ends
} catch (e: any) {
console.error("error creating SIP participant or running session:", e?.message ?? e);
ctx.shutdown();
}
},
});ctx.waitForParticipant(identity=participantIdentity)l
late-glass-71191
12/30/2025, 3:49 PMconst dispatch = await agentDispatchClient.createDispatch(
roomName,
agentName,
{
metadata: formattedPhoneNumber,
},
);
what dispatch does this code create
t
tall-airline-16756
12/30/2025, 3:49 PMYou're creating a dispatch job that launches an agent instance in a specific room and passes it metadata.
Specifically:
• roomName — the LiveKit room where the agent will connect.
• agentName — which agent implementation (by name) to run.
• metadata — the data sent with the job (here
formattedPhoneNumberctx.job.metadatadial_info.phone_numberl
late-glass-71191
12/30/2025, 3:50 PMimport {
AgentDispatchClient,
RoomServiceClient,
SipClient,
} from 'livekit-server-sdk';
import {agentName} from './agent.js';
const {
LIVEKIT_API_KEY = '',
LIVEKIT_API_SECRET = '',
LIVEKIT_URL = '',
SIP_OUTBOUND_TRUNK_ID = '',
} = process.env;
/**
* Formats a phone number to E.164 format for SIP compatibility
* @average-fall-32270 number - Raw phone number input
* @returns Formatted phone number in E.164 format
* @throws Error if the phone number is invalid
*/
function formatPhoneNumber(number = ''): string {
const digits = number.replace(/\D/g, '');
if (digits.length !== 10) {
throw new Error(
'Invalid phone number format. Please enter a 10-digit US phone number.',
);
}
return `+1${digits}`;
}
/**
* Makes a call to a specified phone number using LiveKit and SIP
* @average-fall-32270 phoneNumber - The phone number to dial
* @throws Error if the phone number is invalid or if there is an error creating the SIP participant
*/
async function makeCall(phoneNumber: string) {
const formattedPhoneNumber = formatPhoneNumber(phoneNumber);
const agentDispatchClient = new AgentDispatchClient(
LIVEKIT_URL,
LIVEKIT_API_KEY,
LIVEKIT_API_SECRET,
);
const roomServiceClient = new RoomServiceClient(
LIVEKIT_URL,
LIVEKIT_API_KEY,
LIVEKIT_API_SECRET,
);
const sipClient = new SipClient(
LIVEKIT_URL,
LIVEKIT_API_KEY,
LIVEKIT_API_SECRET,
);
const roomName = `room_${Math.floor(Math.random() * 10_000)}`;
const participantIdentity = `caller_${formattedPhoneNumber}}`;
await roomServiceClient.createRoom({name: roomName, emptyTimeout: 60});
// Create agent dispatch
console.log(
Creating dispatch for agent ${agentName} in room ${roomName}Created dispatch: ${dispatch.id}Dialing ${formattedPhoneNumber} to room ${roomName}Created SIP participant: ${sipParticipant.participantId}Error creating SIP participant: ${e instanceof Error ? e.message : e}Dialing ${phoneNumber}t
tall-airline-16756
12/30/2025, 3:50 PMThanks — I’ll explain what this code does and how the pieces interact.
High-level purpose
• Creates a temporary LiveKit room, dispatches a named agent into that room with the phone number in job metadata, then creates a SIP participant that dials the phone and joins the room when answered.
Step-by-step behavior
1. Environment and helpers
• Reads LiveKit credentials and SIP trunk id from env vars.
•
formatPhoneNumber(number)+1XXXXXXXXXXformatPhoneNumberAgentDispatchClientRoomServiceClientSipClientroomNameparticipantIdentityroomServiceClient.createRoom(...)agentDispatchClient.createDispatch(roomName, agentName, { metadata: formattedPhoneNumber })ctx.job.metadataSIP_OUTBOUND_TRUNK_IDsipClient.createSipParticipant(...)ctx.job.metadataparticipantIdentityctx.waitForParticipant(identity=participantIdentity)agentNamectx.job.metadatactx.api.sip.create_sip_participantctx.waitForParticipantctx.job.metadataparticipantIdentityctx.job.metadatal
late-glass-71191
12/30/2025, 3:54 PMbasicallt the agent was already starter operating before dispatching to the room ?
t
tall-airline-16756
12/30/2025, 3:54 PMGood question — short answer: no, the agent isn't running before dispatch. Creating a dispatch launches (starts) the agent instance in the target room.
Clarified sequence:
1. You call createDispatch(roomName, agentName, { metadata }) — this tells the system to start an agent job.
2. The worker runs the agent's entrypoint for that job (the agent process starts and executes your entry code).
3. In your entrypoint the agent typically:
◦ Connects to the room (await ctx.connect()),
◦ Starts its AgentSession (STT/TTS/VAD/LLM) so it's ready to publish/receive audio,
◦ Then you create the SIP participant (dial outbound) or wait for one to join.
1. The SIP call rings and when answered the SIP participant joins the room; the agent is already connected and ready to handle that specific participant (you bind by participant identity with ctx.waitForParticipant).
Because the agent is started by the dispatch, starting the AgentSession before dialing avoids missed audio when the callee answers.
l
late-glass-71191
12/30/2025, 4:02 PMi have a pm2 manager that starts the agent in lkivekit cloud
now how can i push the running agent to newly created room and call participant'
t
tall-airline-16756
12/30/2025, 4:02 PMThanks — helpful context. Quick answer: you don’t “push” a running agent process into a new room. Instead, keep your pm2-managed worker process running (it hosts the agent code), and dispatch a new job that starts an agent instance connected to the new room. Each dispatch runs the agent entrypoint and creates an AgentSession tied to that room and participant.
Short plan and options:
1) Keep pm2 worker(s) running (what you have)
• The pm2 process runs your agent binary/worker and listens for dispatch jobs.
• When you call AgentDispatchClient.createDispatch(...) the dispatcher tells your worker to start a new agent job that runs the agent entrypoint connected to the target room.
2) Recommended flow to handle a new outbound call
• Create a room (RoomServiceClient.createRoom) or reuse an existing room.
• Call AgentDispatchClient.createDispatch(roomName, agentName, { metadata: dialInfo }) to start an agent job for that room.
• From your server, create the SIP participant (RoomServiceClient/SipClient.createSipParticipant) to dial the phone into that room.
• In the agent entrypoint:
◦ call await ctx.connect();
◦ start AgentSession (STT/TTS/VAD/LLM) so it can publish immediately;
◦ call await ctx.waitForParticipant(identity=participantIdentity) to bind to that SIP call participant;
◦ proceed with session.generate_reply / handle events.
3) If you need the running process to proactively join arbitrary rooms (alternative pattern)
• Instead of trying to move a single running agent instance:
◦ Keep a lightweight controller process in pm2 that can request the worker to start jobs (i.e., the same AgentDispatchClient.createDispatch).
◦ Or implement an RPC/HTTP endpoint inside your worker that accepts a "start agent for room X" request; that endpoint should create a new local job/process or instruct the worker runtime to run the agent entrypoint for that room (this still results in a new agent instance).
4) Minimal code sketch (Node) — server that creates room, dispatches agent, then dials:
• create room: roomService.createRoom({ name: roomName });
• dispatch agent: agentDispatch.createDispatch(roomName, agentName, { metadata: JSON.stringify(dialInfo) });
• dial: sipClient.createSipParticipant(trunkId, formattedPhoneNumber, roomName, { participantIdentity });
5) Key notes / pitfalls
• The agent code must read ctx.job.metadata to get dial info and participantIdentity.
• Start AgentSession before dialing to avoid missed audio.
• Each dispatch/job is isolated — multiple simultaneous calls require multiple dispatches.
• Do not try to reuse a single AgentSession across different rooms; create one per job/room.
• If you want fast startup, use prewarmed workers or keep the worker runtime ready to accept jobs.
If you want, I can:
• Provide a concrete Node.js example that your pm2-managed worker can call to dispatch an agent and then dial the number, or
• Show how to add an HTTP endpoint in your running pm2 process that triggers createDispatch + createSipParticipant.
Which would you prefer?
l
late-glass-71191
12/30/2025, 4:43 PMshould the agent names be unique then ?
t
tall-airline-16756
12/30/2025, 4:44 PMGood question — short answer: no, agent names do not need to be unique per dispatch.
Clarification:
• The agent name identifies the agent implementation/type (which entrypoint/worker code to run), not a single running instance. Example: "outbound-caller" means "run that agent code".
• Each call/dispatch creates a separate job/instance of that agent implementation. Multiple dispatches can use the same agent name concurrently; each becomes its own job with its own JobContext, AgentSession, and room binding.
When you might use unique names:
• If you have different agent behaviors or configurations that must be selected at dispatch time, register them under different agent names (e.g., "outbound-caller-v1" vs "outbound-caller-sales").
• You can also pass variant behavior via job metadata (preferred) while keeping a single agent name.
Practical rules
• Use stable agent names for an implementation (not per-call).
• Bind a job to a room/participant using metadata and participantIdentity — that’s how the running instance knows which call to attend.
• No per-dispatch uniqueness is required; the dispatch system spawns isolated instances for each job.
If you want, I can recommend a naming pattern and show how to pass metadata to select behavior without creating multiple agent names. Which would you prefer?
l
late-glass-71191
12/30/2025, 8:04 PMasync createSipOutboundTrunk(
name: string,
address: string,
numbers: string[],
opts?: CreateSipOutboundTrunkOptions,
): Promise<SIPOutboundTrunkInfo> {
if (opts === undefined) {
opts = {
transport: SIPTransport.SIP_TRANSPORT_AUTO,
};
}
const req = new CreateSIPOutboundTrunkRequest({
trunk: new SIPOutboundTrunkInfo({
name: name,
address: address,
numbers: numbers,
metadata: opts.metadata,
transport: opts.transport,
authUsername: opts.authUsername ?? opts.auth_username,
authPassword: opts.authPassword ?? opts.auth_password,
headers: opts.headers,
headersToAttributes: opts.headersToAttributes,
includeHeaders: opts.includeHeaders,
destinationCountry: opts.destinationCountry,
mediaEncryption: opts.mediaEncryption,
}),
}).toJson();
const data = await this.rpc.request(
svc,
'CreateSIPOutboundTrunk',
req,
await this.authHeader({}, { admin: true }),
);
return SIPOutboundTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
}
can i not provide an empty array in the phone numbers params
t
tall-airline-16756
12/30/2025, 8:04 PMShort answer: Yes — you can pass an empty array for
numberscreateSipOutboundTrunknumbers+1234567890sip_numberl
late-glass-71191
12/30/2025, 10:19 PMalright after the outbpund call is ended by user does the created room delete on its own ?
t
tall-airline-16756
12/30/2025, 10:19 PMShort answer: not immediately — rooms are not deleted automatically the moment the user hangs up unless you configured automatic cleanup. Two mechanisms control room deletion:
• emptyTimeout on room creation: if you set an empty timeout (e.g., 60 seconds) the room will be automatically deleted after it becomes empty for that duration. Your example code used
emptyTimeout: 60roomServiceClient.deleteRoom(...)hangup()ctx.api.room.delete_roomemptyTimeoutl
late-glass-71191
01/01/2026, 12:58 PMupdates {
numbers: ListUpdate {
set: [],
add: [ '+18153489346' ],
remove: [],
clear: false
}
}
Failed to update trunk: TwirpError [Internal Server Error]: no trunk numbers specified
at TwirpRpc.request (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/dist/TwirpRPC.js6113)
at process.processTicksAndRejections (nodeinternal/process/task queues105:5)
at async SipClient.updateSipOutboundTrunk (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/src/SipClient.ts63218)
at async LiveKitService.updateTrunkFields (/home/anirban-singha/Documents/agent-starter-node/src/services/livekitService.ts3007)
at async syncPhoneNumberToTrunk (/home/anirban-singha/Documents/agent-starter-node/src/utils/syncPhoneNumber.ts4013)
at async <anonymous> (/home/anirban-singha/Documents/agent-starter-node/src/routers/agent.router.ts907) {
status: 500,
code: 'unknown',
metadata: undefined
}
Failed to update trunk in LiveKit: TwirpError [Internal Server Error]: no trunk numbers specified
at TwirpRpc.request (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/dist/TwirpRPC.js6113)
at process.processTicksAndRejections (nodeinternal/process/task queues105:5)
at async SipClient.updateSipOutboundTrunk (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/src/SipClient.ts63218)
at async LiveKitService.updateTrunkFields (/home/anirban-singha/Documents/agent-starter-node/src/services/livekitService.ts3007)
at async syncPhoneNumberToTrunk (/home/anirban-singha/Documents/agent-starter-node/src/utils/syncPhoneNumber.ts4013)
at async <anonymous> (/home/anirban-singha/Documents/agent-starter-node/src/routers/agent.router.ts907) {
status: 500,
code: 'unknown',
metadata: undefined
}
why do i get this error
t
tall-airline-16756
01/01/2026, 12:58 PMThanks — this error happens because the update request ends up with no trunk numbers at the moment the API validates the request. The LiveKit SIP trunk update rejects requests that result in an empty numbers list.
Why it happened
• Your ListUpdate shows
set: []add: ['+18153489346']set: []addsetsetsetset: []setl
late-glass-71191
01/01/2026, 12:59 PMexport async function syncPhoneNumberToTrunk(orgId: string, phoneNumber: string, action: 'add' | 'remove') {
try {
const trunk = await prisma.outboundTrunk.findFirst({
where: {
org_id: orgId,
},
});
if (!trunk) {
console.log(
No active outbound trunk found for org ${orgId}, skipping sync${action === 'add' ? 'Adding' : 'Removing'} ${phoneNumber} ${action === 'add' ? 'to' : 'from'} trunk ${trunk.trunkId}Phone number ${phoneNumber} already in trunkTrunk updated in LiveKit with ${updatedNumbers.length} numbersFailed to sync phone number to trunk:t
tall-airline-16756
01/01/2026, 12:59 PMThanks — the error happens because the LiveKit update call is being sent with an empty
setnumbersaddset: []setupdatedNumbersnumbers: new ListUpdate({ set: updatedNumbers })set: mergedset: []addset: []setsetset: mergedl
late-glass-71191
01/01/2026, 1:00 PMalright follow first step and provide code
t
tall-airline-16756
01/01/2026, 1:00 PMThanks — below is a concise patch that implements step 1: compute the final numbers list and send it via
setset: mergedNumbers Copy code
import { ListUpdate } from 'livekit-server-sdk'; // adjust import path if needed
export async function syncPhoneNumberToTrunk(orgId: string, phoneNumber: string, action: 'add' | 'remove') {
try {
const trunk = await prisma.outboundTrunk.findFirst({
where: { org_id: orgId },
});
if (!trunk) {
console.log(`No active outbound trunk found for org ${orgId}, skipping sync`);
return null;
}
// compute updatedNumbers locally (same as you have)
let updatedNumbers: string[];
if (action === 'add') {
if (trunk.numbers.includes(phoneNumber)) {
console.log(`Phone number ${phoneNumber} already in trunk`);
return trunk;
}
updatedNumbers = [...trunk.numbers, phoneNumber];
} else {
updatedNumbers = trunk.numbers.filter((num) => num !== phoneNumber);
}
// persist locally
const updatedTrunk = await prisma.outboundTrunk.update({
where: { id: trunk.id },
data: { numbers: updatedNumbers },
});
// Fetch current trunk from LiveKit to be safe
const livekitTrunk = await livekitService.getTrunkById(trunk.id); // implement/get wrapper that calls RoomServiceClient or SipClient GET
const existing = Array.isArray(livekitTrunk?.numbers) ? livekitTrunk.numbers : [];
// Merge deterministically (avoid duplicates)
const merged = action === 'add'
? Array.from(new Set([...existing, phoneNumber]))
: existing.filter(n => n !== phoneNumber);
// Send final list using `set`
await livekitService.updateTrunkFields(trunk.id, {
numbers: new ListUpdate({ set: merged }) as any,
});
console.log(`Trunk updated in LiveKit with ${merged.length} numbers`);
return updatedTrunk;
} catch (error) {
console.error(`Failed to sync phone number to trunk:`, error);
return null;
}
} Copy code
async updateTrunkFields(trunkId: string, updates: Partial<TrunkConfig>) {
try {
const updateData: any = {};
if (updates.name) updateData.name = updates.name;
if (updates.address) updateData.address = updates.address;
if (updates.numbers) updateData.numbers = updates.numbers; // pass ListUpdate obj
if (updates.authUsername) updateData.auth_username = updates.authUsername;
if (updates.authPassword) updateData.auth_password = updates.authPassword;
console.log('updates ', updateData);
await this.sipClient.updateSipOutboundTrunk(trunkId, updateData);
return updateData;
} catch (error: any) {
console.error('Failed to update trunk:', error);
throw error;
}
}livekitService.getTrunkById(trunk.id)numbersset: mergedSetupdatedNumbersmergedsetgetTrunkByIdl
late-glass-71191
01/01/2026, 1:17 PMFailed to update trunk: TwirpError [Internal Server Error]: no trunk numbers specified
at TwirpRpc.request (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/dist/TwirpRPC.js6113)
at process.processTicksAndRejections (nodeinternal/process/task queues105:5)
at async SipClient.updateSipOutboundTrunk (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/src/SipClient.ts63218)
at async LiveKitService.updateTrunkFields (/home/anirban-singha/Documents/agent-starter-node/src/services/livekitService.ts3005)
at async syncPhoneNumberToTrunk (/home/anirban-singha/Documents/agent-starter-node/src/utils/syncPhoneNumber.ts375)
at async <anonymous> (/home/anirban-singha/Documents/agent-starter-node/src/routers/agent.router.ts907) {
status: 500,
code: 'unknown',
metadata: undefined
}
Failed to sync phone number to trunk: TwirpError [Internal Server Error]: no trunk numbers specified
at TwirpRpc.request (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/dist/TwirpRPC.js6113)
at process.processTicksAndRejections (nodeinternal/process/task queues105:5)
at async SipClient.updateSipOutboundTrunk (/home/anirban-singha/Documents/agent-starter-node/node_modules/.pnpm/livekit-server-sdk@2.14.2/node_modules/livekit-server-sdk/src/SipClient.ts63218)
at async LiveKitService.updateTrunkFields (/home/anirban-singha/Documents/agent-starter-node/src/services/livekitService.ts3005)
at async syncPhoneNumberToTrunk (/home/anirban-singha/Documents/agent-starter-node/src/utils/syncPhoneNumber.ts375)
at async <anonymous> (/home/anirban-singha/Documents/agent-starter-node/src/routers/agent.router.ts907) {
status: 500,
code: 'unknown',
metadata: undefined
}
t
tall-airline-16756
01/01/2026, 1:17 PMThanks — sorry this is still failing. The error means the update request you're sending to LiveKit still results in no trunk numbers. To fix it I need to confirm a couple quick facts and see one small log.
Please do two things and paste the outputs here:
1) Log the final payload sent to LiveKit right before the update call. In updateTrunkFields add:
Copy code
console.log('LiveKit update payload:', JSON.stringify(updateData));mergedupdatedNumbers Copy code
console.log('numbers to set on trunk:', merged);setl
late-glass-71191
01/01/2026, 1:25 PMUpdating LiveKit trunk: {
numbers: ListUpdate {
set: [ '+18153489346' ],
add: [],
remove: [],
clear: false
}
}
t
tall-airline-16756
01/01/2026, 1:25 PMThanks — the payload you posted shows the numbers are wrapped with markdown-like text ("+18153489346") instead of a plain E.164 string. LiveKit expects raw phone numbers (e.g. "+18153489346"), and the server rejects the request because it doesn't see valid numbers.
Fix:
• Strip any Markdown/HTML or display formatting before building the ListUpdate. Send plain strings.
Example minimal fix before calling update:
Copy code
function normalizeNumber(n: string) {
return n.replace(/.*?(\+\d{10,15}).*/, "$1");
}
const merged = ['[+18153489346](tel:+18153489346)'].map(normalizeNumber);
// merged => ['+18153489346']
await livekitService.updateTrunkFields(trunk.id, {
numbers: new ListUpdate({ set: merged }),
});l
late-glass-71191
01/01/2026, 1:40 PMasync updateSipOutboundTrunk(
sipTrunkId: string,
trunk: SIPOutboundTrunkInfo,
): Promise<SIPOutboundTrunkInfo> {
const req = new UpdateSIPOutboundTrunkRequest({
sipTrunkId,
action: {
case: 'replace',
value: trunk,
},
}).toJson();
const data = await this.rpc.request(
svc,
'UpdateSIPOutboundTrunk',
req,
await this.authHeader({}, { admin: true }),
);
return SIPOutboundTrunkInfo.fromJson(data, { ignoreUnknownFields: true });
}
declare class SIPOutboundTrunkInfo extends Message<SIPOutboundTrunkInfo> {
/**
* @generated from field: string sip_trunk_id = 1;
*/
sipTrunkId: string;
/**
* Human-readable name for the Trunk.
*
* @generated from field: string name = 2;
*/
name: string;
/**
* User-defined metadata for the Trunk.
*
* @generated from field: string metadata = 3;
*/
metadata: string;
/**
* Hostname or IP that SIP INVITE is sent too.
* Note that this is not a SIP URI and should not contain the 'sip:' protocol prefix.
*
* @generated from field: string address = 4;
*/
address: string;
/**
* country where the call terminates as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will be used by the livekit infrastructure to route calls.
*
* @generated from field: string destination_country = 14;
*/
destinationCountry: string;
/**
* SIP Transport used for outbound call.
*
* @generated from field: livekit.SIPTransport transport = 5;
*/
transport: SIPTransport;
/**
* Numbers used to make the calls. Random one from this list will be selected.
*
* @generated from field: repeated string numbers = 6;
*/
numbers: string[];
/**
* Username and password used to authenticate with SIP server.
* May be empty to have no authentication.
*
* @generated from field: string auth_username = 7;
*/
authUsername: string;
/**
* @generated from field: string auth_password = 8;
*/
authPassword: string;
/**
* Include these SIP X-* headers in INVITE request.
* These headers are sent as-is and may help identify this call as coming from LiveKit for the other SIP endpoint.
*
* @generated from field: map<string, string> headers = 9;
*/
headers: { [key: string]: string };
/**
* Map SIP X-* headers from 200 OK to SIP participant attributes.
* Keys are the names of X-* headers and values are the names of attributes they will be mapped to.
*
* @generated from field: map<string, string> headers_to_attributes = 10;
*/
headersToAttributes: { [key: string]: string };
/**
* Map LiveKit attributes to SIP X-* headers when sending BYE or REFER requests.
* Keys are the names of attributes and values are the names of X-* headers they will be mapped to.
*
* @generated from field: map<string, string> attributes_to_headers = 11;
*/
attributesToHeaders: { [key: string]: string };
/**
* Map SIP headers from 200 OK to sip.h.* participant attributes automatically.
*
* When the names of required headers is known, using headers_to_attributes is strongly recommended.
*
* When mapping 200 OK headers to follow-up request headers with attributes_to_headers map,
* lowercase header names should be used, for example: sip.h.x-custom-header.
*
* @generated from field: livekit.SIPHeaderOptions include_headers = 12;
*/
includeHeaders: SIPHeaderOptions;
/**
* @generated from field: livekit.SIPMediaEncryption media_encryption = 13;
*/
mediaEncryption: SIPMediaEncryption;
constructor(data?: PartialMessage<SIPOutboundTrunkInfo>);
static readonly runtime: typeof proto3;
static readonly typeName = "livekit.SIPOutboundTrunkInfo";
static readonly fields: FieldList;
static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): SIPOutboundTrunkInfo;
static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): SIPOutboundTrunkInfo;
static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): SIPOutboundTrunkInfo;
static equals(a: SIPOutboundTrunkInfo | PlainMessage<SIPOutboundTrunkInfo> | undefined, b: SIPOutboundTrunkInfo | PlainMessage<SIPOutboundTrunkInfo> | undefined): boolean;
}
what to provide in updated trunk for nummbers
t
tall-airline-16756
01/01/2026, 1:41 PMProvide the trunk
numbersset Copy code
// using ListUpdate.set with plain E.164 numbers
numbers: new ListUpdate({ set: ["+18153489346", "+14155552671"] }) Copy code
numbers: new ListUpdate({ set: merged }) Copy code
// compute remaining = existing.filter(n => n !== "+18153489346")
numbers: new ListUpdate({ set: remaining })set: []numbers.setsetListUpdate({ set: merged })3 Views