Speko Docs

voice

Outbound phone calls through POST /v1/sessions/phone.

Use speko.voice.dial() to place an outbound PSTN call. The API creates a voice session, dispatches the configured worker, and dials the destination over LiveKit SIP.

const call = await speko.voice.dial({
  to: '+12015551234',
  from: '+12015550199',
  agentId: 'agent_123',
  webhookTags: { environment: 'production' },
  telephony: {
    region: 'us-east',
    amd: { mode: 'agent', timeoutSeconds: 8 },
  },
});

console.log(call.sessionId, call.status);

Signature

speko.voice.dial(params: VoiceDialParams): Promise<VoiceDialResult>

Parameters

FieldTypeDescription
tostringDestination in E.164 format.
fromstring?Caller ID: a number the organization owns. Omit it to use the organization's first outbound number, or a shared Speko number if it has none.
agentIdstring?Persisted agent to run. Required unless intent is supplied.
intentRoutingIntent?Routing intent for ad hoc calls. Required unless agentId is supplied.
constraintsPipelineConstraints?Provider allow-list constraints.
voicestring?TTS voice id override.
systemPromptstring?Agent instructions for this call.
firstMessagestring?Optional first utterance.
llm{ temperature?: number; maxTokens?: number }?LLM tuning.
ttsOptions{ sampleRate?: number; speed?: number }?TTS options.
sttOptions{ keywords?: string[]; prompt?: string; language?: string }?STT keyword hints, an optional free-text transcription prompt (domain/context prose, max 2000 chars — used only by prompt-capable models such as OpenAI GPT transcribe and AssemblyAI Universal-3 Pro), and a stream-language override — pass 'auto' to let the provider detect the spoken language (Soniox auto-detects when no hint is sent).
telephony{ region?: string; amd?: { mode?: 'agent' | 'carrier' | 'disabled'; timeoutSeconds?: number } }?SIP routing and voicemail-detection hints.
webhookTagsRecord<string, string>?Case-sensitive workspace webhook routing tags; requires agentId.
metadataRecord<string, unknown>?Free-form metadata surfaced in webhooks and call events.

Returns

FieldTypeDescription
sessionIdstringVoice session id.
callControlIdstringLiveKit SIP participant identity for the outbound leg.
roomNamestringLiveKit room name.
status'dialing' | 'dialing-stub'Dial status. Stub appears when SIP is not configured in the deployment.
tostringDestination number.
fromstringResolved caller ID.

On this page