Voice runtime

The runtime Voice object places outbound voice calls from agent code: the platform allocates a room, dials the target, and starts the agent’s voice definition with the context you pass. voice.call (lowercase) is an alias. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. Verified against lua-cli 3.33.0.

import { Voice } from 'lua-cli';

Quick example

A call resolves as soon as it is placed; whether anyone answers is a runtime outcome, not an error.

import { Voice } from 'lua-cli';

const call = await Voice.call({
  to: '+15551234567',
  voice: 'support-line',
  context: { reason: 'recovery', orderId: 'ORD-4471' },
});

Methods

call(input)

Places an outbound call to a phone number, a meeting, or a browser.

Voice.call(input: VoiceDispatchInput): Promise<VoiceDispatchOutput>

string | { kind: 'phone' | 'meet' | 'web', ... }

required

Where to dial. An E.164 string is shorthand for { kind: 'phone', number }. { kind: 'phone', number, callerId? } dials a number, with an optional outbound caller id the organization owns; { kind: 'meet', url } joins a meeting by URL; { kind: 'web', returnToken? } allocates a browser voice session and, with returnToken: true, returns a joinUrl.

string

The id or name of the voice to run. Defaults to the agent’s first active voice. It must belong to this agent.

Record<string, unknown>

A JSON-serializable object the model sees on the call’s first turn, so it can act without a lookup. The voice’s hooks read it as ctx.session.userdata.dispatchContext.

string

default:"voice:<sessionId>"

Thread suffix that scopes User, Data, and the other runtime objects inside the call. The default gives each call isolated storage.

'phone' | 'meeting' | 'whatsapp' | 'webchat' | 'unknown'

Overrides the channel label inferred from to.kind, for analytics and billing.

Returns

VoiceDispatchOutput

Show properties

string

The voice session’s id.

string

The room the call landed in.

string

The provider’s call id: the SIP participant id for phone, the meeting participant id for meet, absent for web.

string

The URL a browser opens to join, for web with returnToken: true.

Example

import { LuaJob, Data, Voice } from 'lua-cli';

export default new LuaJob({
  name: 'abandoned-cart-calls',
  description: 'Call customers who left a basket yesterday',
  schedule: { type: 'cron', expression: '0 10 * * *', timezone: 'America/New_York' },
  async execute() {
    const carts = await Data.get('abandoned-carts', { called: false }, 1, 20);
    for (const cart of carts.data) {
      const call = await Voice.call({
        to: cart.data.phone,
        voice: 'recovery-line',
        context: { basketId: cart.data.basketId, total: cart.data.total },
      });
      await Data.update('abandoned-carts', cart.id, { called: true, sessionId: call.sessionId });
    }
    return { placed: carts.data.length };
  },
});

Errors — the call throws when the dispatch is refused. In a deployed agent the error is a VoiceDispatchError with code and statusCode; in lua test it is a plain Error carrying the server’s message, or Voice dispatch failed.

Voice "<name>" not active on agent <agentId> (deactivated, missing, or owned by a different agent).
Agent <agentId> has no active LuaVoice configured. Push a voice before dispatching.
Caller ID is not authorized for this agent.
Voice dispatch rate limit exceeded for agent <agentId> (100/min): more than 100 accepted dispatches in a minute.
Unsupported dispatch target kind.

createSession(input?)

Creates a room and a client token for a voice session your own front end joins with a standard LiveKit client.

Voice.createSession(input?: VoiceSessionInput): Promise<VoiceSessionOutput>

string

default:"web"

The voice channel for the voice session.

string

Your end user’s id, so conversation memory and the transcript are scoped to them. Without it the voice session runs under a synthetic identity.

string

A voice id that overrides the agent’s channel-bound voice.

string

The participant’s display name.

Returns — url (the wss:// server URL), roomName, token (the client access token), participantIdentity, and agentName. Hand url and token to the client’s room.connect.

Local runs only. Neither the deployed runtime nor lua test injects createSession, so agent code fails with Voice.createSession is not a function; the member works only when Node runs your file directly with the lua-cli package and your developer credentials.

Errors — Voice session creation failed when the platform gives no message.

Types

VoiceApi is exported from lua-cli. The input and output shapes of both methods are not exported; they are the inline types described under each method.

SDK

CLI

REST API

Quick example

Methods

call(input)

createSession(input?)

Types

See also

​Quick example

​Methods

​call(input)

​createSession(input?)

​Types

​See also

Quick example

Methods

call(input)

createSession(input?)

Types

See also