Speko Docs
Build

Build a phone agent

Inbound and outbound PSTN calls, phone-number routing, lifecycle webhooks, reports, and transfers.

Speko can run the same voice agent over browser sessions and PSTN calls. Phone calls use the platform-hosted LiveKit SIP path: Speko creates or receives the call leg, dispatches the agent worker, records the room, persists transcripts and events, and finalizes a call report after hangup.

Use this guide when you want a receptionist, appointment setter, callback workflow, or support line that can place calls, answer calls, and transfer callers to a human.

Phone surfaces

NeedAPISDK
Place an outbound phone callPOST /v1/sessions/phonespeko.voice.dial()
Buy or import numbers/v1/phone-numbers/*speko.phoneNumbers
Route inbound callsagentId or dispatchMetadataTemplate on a phone numberspeko.phoneNumbers.update()
Inspect calls and reports/v1/calls/{id}speko.calls.get()
Read lifecycle events/v1/calls/{id}/eventsspeko.calls.events()
Listen to a live call in a browserPOST /v1/calls/{id}/listenspeko.calls.listen(). See Listen to live calls.
Transfer live calls/v1/calls/{id}/transfers/*speko.calls.blindTransfer() / speko.calls.warmTransfer()

1. Create an agent

Phone calls work best with a persisted agent because the phone-number row can hydrate its prompt, routing intent, provider preferences, speech settings, and tools every time a call starts. Lifecycle webhooks are configured once at the workspace level and scoped to this agent when needed.

curl -X POST https://api.speko.dev/v1/agents \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Front desk",
    "systemPrompt": "You are the front-desk receptionist. Greet callers, collect their name and reason for calling, answer common questions, and transfer urgent calls.",
    "intent": { "language": "en-US", "optimizeFor": "latency" }
  }'

Create lifecycle endpoints in Settings → Webhooks or through speko.webhooks. See Workspace webhooks for event selection, agent scopes, tagged routing, signing, retries, and logs. Agent-level webhooks fields are deprecated compatibility fields through the current SDK major version.

Realtime (speech-to-speech) agents on the phone

An agent saved with runMode: "s2s" (dashboard: Architecture → Realtime) answers and places phone calls with one speech-to-speech model instead of the STT → LLM → TTS cascade. These models can do this, because Speko's voice worker hosts them and a SIP leg can ride what the worker holds:

PinModelVoicesBilled as
openai:gpt-live-1OpenAI GPT-LiveGPT-Live roster (see below)flat per-minute rate, billed per second, plus backend model tokens
xai:grok-voice-3.0xAI Grok Voice 3.0eve (default), ara, rex, sal, leoflat per-minute rate, billed per second

These are the only speech-to-speech models an agent can use on the phone. On the web, an agent can also pin Fish Audio Live 3 (fishaudio:live3) where it is enabled for the workspace. It runs only on agent web sessions, in English, on the Speko-managed Fish key (BYOK is refused), and it does not run agent graphs. It bills the same flat per-minute rate, billed per second, with no add-on. Automatic selection never picks it. Agents cannot pin the gpt-realtime-* models, Gemini Live or the older Grok Voice ids. Saving an agent with one of them returns 400 S2S_MODEL_NOT_ALLOWED. An agent saved with one of them before this rule keeps working and runs on GPT-Live, with no change to the agent. Those models stay available for agentless provider-direct sessions (see Provider-direct speech-to-speech).

  • On a phone agent, leave stackPreferences.allowedProviders.s2s empty or pin one of the rows above (a bare openai / xai selects that provider's default; xai:grok-voice-latest also works and resolves to 3.0). An empty allowlist means GPT-Live. The API refuses to link a phone number to a realtime agent pinned to a model a phone cannot host (AGENT_S2S_PIN_NOT_PHONE_HOSTABLE), and refuses the agent update that would create that state (S2S_PIN_NOT_PHONE_HOSTABLE).
  • The agent's voice is the model's own voice, not a TTS voice id. GPT-Live speaks marin (default), quartz, ripple, vesper, willow, stone, gleam, meridian, bossa, tempo, beacon, delta and cinder. Realtime API voices such as cedar or echo are not on the GPT-Live roster. Setting a voice the model cannot speak on a realtime agent, or passing one as voice on POST /v1/sessions/phone, returns 400 S2S_VOICE_UNSUPPORTED with the supported list. A voice the model cannot speak that the agent already carries (one saved before this check, or a TTS voice on an agent called with runMode: "s2s") does not fail the call. The call uses the model voice that matches it best by gender and accent, for example meridian for a male American voice on GPT-Live. If the saved voice's gender is not known, the call uses the model's default. The call's warnings and its session events include a voice_substituted entry that names both voices. Saving such an agent returns the same warning.
  • Reasoning models think before they answer. Save llmOptions.reasoningEffort on the agent to set how long, on every call: none on Grok Voice 3.0 turns its reasoning off, and GPT-Live applies the value to its backend model. Models without a dial ignore it.
  • Tools, end_call and transcripts work the same on both models; GPT-Live reaches them through its backend model, Grok Voice runs them itself.
  • The session row carries pipelineKind: "s2s". GPT-Live bills the same flat published per-minute rate as a cascade call, with the voice model included, on any backend. Its backend model's tokens (s2s.backendModel, gpt-5.6-luna by default) are an add-on, billed at the provider's list price plus 5% and itemised as Backend model on the call's cost receipt. Grok Voice 3.0 bills the same flat per-minute rate, with the voice model included and no add-on. A call on your own OpenAI key (BYOK) pays no Speko minute and no backend tokens.
  • If a call still cannot host the route at dial time — no credential for the pinned model's provider in the workspace, or the worker is unavailable — the call runs the cascade and says so: an s2s.fallback event on the session timeline, metadata.s2sFallback on the session, and a warning in the logs. It is never silent.
  • A single outbound call can ask for this without an agent: POST /v1/sessions/phone accepts runMode: "s2s" next to intent / systemPrompt, and the leg is hosted on GPT-Live (the default when nothing is pinned). The per-call value also wins over an agent's saved run mode — runMode: "cascade" on a Realtime agent runs the cascade for that call, with no fallback recorded because it was asked for. The same dial-time fallbacks apply.
  • Outbound GPT-Live calls run worker-side answering-machine detection, rolled out per workspace. Until it is turned on for yours, the detector only observes: each verdict is recorded as a worker.duplex.amd_shadow_verdict event and the call carries on as if nothing had been detected. Once on, turnHandling.onMachine applies, with the differences listed under Voicemail handling. Grok Voice calls have no worker-side detection (a call that asks for it by name gets a worker.duplex.amd_unsupported event); carrier AMD still applies to every model.
  • Keypad navigation works on every model: every realtime phone leg can press digits with send_dtmf unless turnHandling.keypad is false, and turnHandling.profile: "ivr" navigates menus from the first turn. For a menu you already know, a saved outboundDtmf or a per-call telephony.dtmf presses the path before the model starts (see Navigating phone menus). Idle check-ins follow the agent's idleRePrompts, spoken in the model's own words; an agent with them off or unset gets none. A call placed without an agent checks in after 30 seconds of silence.
  • Not yet on the realtime phone path: warm transfers, mid-call language switching (the agent answers in its configured language), and data capture. Use a cascade agent when a call needs those.

Voice level on phone calls

TTS voices are mastered at very different levels. Some synthesize speech at -12 to -15 dBFS with peaks near full scale, well above the roughly -20 dBFS of ordinary telephone speech, and callees hear them as loud or harsh on a mobile handset. audioOutput.gainDb sets a static gain on the agent's own voice, in dB from -24 to 12. It applies to every call the agent takes, whichever TTS provider speaks, and on phone legs it is applied before the audio reaches the SIP trunk (dashboard: Advanced → Speech & audio → Voice volume (dB)):

curl -X PATCH https://api.speko.dev/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "audioOutput": { "gainDb": -6 } }'
  • Negative values make the agent quieter: -6 roughly halves the amplitude. Attenuation never distorts.
  • Positive values boost a voice that is mastered quiet. The boost saturates at full scale, so it clips a voice that already peaks near 0 dBFS.
  • 0 (or null) plays the voice at its own level. Background audio and tool sounds keep their own volume.
  • It also applies on realtime phone legs (GPT-Live, Grok Voice). It does not apply to provider-direct realtime sessions, where the browser talks to the vendor itself.
  • A pre-call webhook can override it per call (audioOutput in the returned config), and POST /v1/sessions accepts it per session. Either replaces the agent's value as a whole.

2. Add a phone number

A number is required to receive calls. Outbound calls work without one: they dial from a shared Speko number.

You can use a platform-managed number or register a customer-owned SIP trunk number.

Managed number search and purchase is currently the US-number path. It requires phone-number business verification and sufficient credits:

const options = await speko.phoneNumbers.searchAvailable({ areaCode: '415' });

const number = await speko.phoneNumbers.create({
  e164: options[0]!.e164,
  direction: 'both',
  agentId: 'agent_123',
  label: 'Main line',
});

For numbers you already own, import the SIP trunk instead:

await speko.phoneNumbers.importSipTrunk({
  e164: '+442071234567',
  sipConnectionInstallationId: '00000000-0000-4000-8000-000000000010',
  direction: 'both',
  agentId: 'agent_123',
  label: 'London front desk',
});

direction controls whether the number can be used for inbound calls, outbound calls, or both. Inbound calls require either an agentId or a dispatchMetadataTemplate.

A SIP connection does not register with your carrier or PBX. It authenticates each call with the connection's username and password. If the call target is a PBX, give the connection a SIP trunk's credentials, not an extension's: many PBXs place calls only for a registered extension, and drop an unregistered one's call without a reply. In the call's details, such a call shows as Never rang.

Caller name

A US local number bought through Speko can carry a caller name (CNAM): the name a called party's carrier may show next to the number on your outbound calls. It's free. Set it on the number's page in the dashboard, or through the API:

await speko.phoneNumbers.update('pn_123', { callerName: 'ACME DENTAL' });
  • Letters, digits and spaces only, 15 characters at most. Extra spaces are trimmed and collapsed.
  • null or an empty string removes it.
  • Only workspace owners and admins can change it, from the dashboard or an OAuth connection signed in as them. A plain API key gets 403.
  • callerNameSupported on the number says whether it can carry one. Imported numbers (set the name with your own carrier), toll-free numbers and non-US numbers can't. Sending a name for one of them returns 400 CALLER_NAME_NOT_SUPPORTED.
  • Carriers pick up a change within about 72 hours (callerNameUpdatedAt is when it last changed). Sending the current name again re-applies it without moving that time.
  • Whether it shows is up to the called party's carrier. Landlines with caller-name service display it; most mobile carriers don't.
  • Use your business name. Misleading caller ID is illegal under the Truth in Caller ID Act.

3. Place outbound calls

Use POST /v1/sessions/phone or speko.voice.dial() for outbound PSTN calls. The response returns the Speko session id, room name, resolved caller ID, and SIP participant handle.

const call = await speko.voice.dial({
  to: '+12015551234',
  from: '+12015550199',
  agentId: 'agent_123',
  firstMessage: 'Hi {{customer_name}}, this is Ava from Acme. Is now still a good time?',
  variables: {
    customer_name: 'Priya',
    renewal_date: 'June 30',
  },
  toolSecrets: {
    access_token: process.env.ACME_CUSTOMER_TOKEN!,
  },
  timezone: 'America/Chicago',
  telephony: {
    region: 'us-east',
    amd: { mode: 'agent', timeoutSeconds: 8 },
  },
  webhookTags: {
    environment: 'production',
  },
  metadata: {
    campaignId: 'renewal-q2',
    leadId: 'lead_456',
  },
});

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

agentId is required unless you pass an ad hoc intent. Per-call fields such as systemPrompt, firstMessage, voice, llm, ttsOptions, sttOptions, and constraints override the agent's defaults for that call.

Three fields carry per-call data, and each goes to a different place:

FieldReachesUse it for
variablesThe prompt and greeting, through {{name}} placeholdersNames, dates, account details the agent should say or use
toolSecretsTools only: session.secrets.<name> in custom-code tools, {{name}} in webhook tool url and headersAccess tokens and other values the model must never see
metadataNothing in the call. Stored on the session and returned in reads, reports, and webhooksYour own IDs for joining results back to your records

metadata never reaches the prompt, so a value the agent needs must go in variables. Sending variables (even {}) renders the prompt and greeting as templates. A placeholder with no value and no default fails the request with 400 MISSING_TEMPLATE_VARIABLES. Each variable value is a string of up to 10,000 characters. The whole call configuration has a size limit too, so a call carrying several very long values can fail with 400 PIPELINE_CONFIG_TOO_LARGE. Each toolSecrets value must be at least 6 characters; see Per-call secrets for the full limits.

Pass timezone (an IANA name such as America/Chicago) to set the call's local time. The agent schedules from it, and {{system.now}} renders in it, so "Thursday at 1PM" resolves to the right date. It overrides the agent's saved timezone for that call only. POST /v1/sessions accepts the same field.

On workspaces running Pipecat agents, variables, timezone, and the other prompt and pipeline overrides are rejected with 400 PIPECAT_CALL_OVERRIDE_UNSUPPORTED. Publish those settings in the workflow instead. toolSecrets and metadata still work.

Calling without a number

A workspace with no outbound number of its own dials from a shared Speko number. Leave out from and the call goes out on it; the response's from shows which number was used. Once the workspace buys or imports a number, calls use that number instead.

The shared number is for trying outbound calls, so it has limits:

LimitValue
DestinationsEvery country the workspace can call (see Calls to other countries)
Calls per workspace10 an hour, 30 a day
Call length10 minutes
CallbacksPeople you call cannot call the shared number back

A call past the hourly or daily count is refused before it dials and is not charged: 429 POOL_DIAL_CAP_REACHED. Buy a number to remove the limits and to receive inbound calls. Scheduled callbacks and Pipecat agents always need a number of the workspace's own.

Calling from your own number

To show a number you already have, such as your mobile or office line, verify it once and pass it as from. See Call from your own number.

Calls to other countries

Free credit covers calls to the US and Canada, including Puerto Rico, the US Virgin Islands, Guam, the Northern Mariana Islands and American Samoa, plus one short call abroad (below). Any other call to another country, or to a US or Canadian premium-rate number, needs the workspace to top up once, any amount from $5. After that, every country dials on credit like any other call, from the shared number or from the workspace's own.

Until then, the call is refused before it dials and is not charged:

{
  "error": "Top up once to call China.",
  "code": "DESTINATION_REQUIRES_CARD",
  "reason": "abroad",
  "country": "CN",
  "hint": "Free credit covers calls in the US and Canada, plus one short call to your own mobile. Add any amount once, from $5, and calls to every country unlock for good.",
  "billingUrl": "/settings/billing",
  "topUpUrl": "https://platform.speko.ai/v1/public/top-up/..."
}

reason is abroad, premium_rate, free_call_used or free_call_in_use. topUpUrl is a one-tap link to pay for this workspace; show it to the user as it is.

One short call abroad stays free, so "call me" works everywhere. Before its top-up, a workspace may place one call from POST /v1/sessions/phone (the dashboard, the API, the SDKs and every MCP host) to a mobile number in another country. It is billed on free credit like a US call, and it ends after 2 minutes of talk whatever maxDurationSeconds asks for. The response says so with "freeCall": { "maxDurationSeconds": 120 }. A call that never connected (busy, declined, no answer, or never placed) does not use it up. Each workspace gets one, and each phone number gets one across Speko. Call lists, scheduled callbacks and the softphone never use it. Buying a phone number does not unlock other countries, and Speko never buys one for a call it would refuse. Calls that leave through your own SIP trunk or PBX are billed by your carrier, so free credit's limits do not apply to them. Sanctioned destinations stay refused for every workspace.

Retry safely with Idempotency-Key

A network timeout leaves you unsure whether the call went out. Send an Idempotency-Key header, such as a UUID you store with the lead, and retry with the same key and the same body. Within 24 hours, a repeat returns the first call's response with X-Idempotent-Replay: true and does not dial again.

curl -X POST https://api.speko.dev/v1/sessions/phone \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Idempotency-Key: 6f1c2b8e-4a1d-4c55-9a2e-3b7f0d9e1a42" \
  -H "Content-Type: application/json" \
  -d '{"to": "+12015551234", "agentId": "agent_123", "metadata": {"leadId": "lead_456"}}'
ResponseMeaningWhat to do
200 with X-Idempotent-Replay: trueThe first request placed the call.Use the returned sessionId.
409 IDEMPOTENCY_KEY_IN_PROGRESSThe first request is still running.Retry after a second.
409 IDEMPOTENCY_KEY_REUSEDThe key was used with a different body.Use a new key for a different call.
409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWNThe first request ended in a 5xx or never finished, so the call may or may not exist.Check GET /v1/sessions?metadata[leadId]=lead_456, then dial with a new key if needed.

A 4xx response frees the key, so you can fix the request and retry with the same key. A 5xx does not, because a dial that errored may still have reached the carrier. Keys belong to your organization and the API key that sent them. Without the header, every request places a call.

Call a list

To call many people with one agent, upload a call list. In the dashboard, open Call lists in the sidebar, upload a CSV, pick the agent and the caller number, and start. Speko dials each row, a few calls at a time, and shows the result of every row.

The CSV needs a phone column (phone, phone_number, number, to, mobile or cell). Every other column becomes a variable your agent can use, so a customer_name column fills {{customer_name}} in the prompt or first message.

From the API, send the rows as JSON:

curl -X POST https://api.speko.dev/v1/call-batches \
  -H "Authorization: Bearer $SPEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October renewals",
    "agentId": "agent_123",
    "from": "+12015550199",
    "concurrency": 2,
    "callWindow": { "timezone": "America/Chicago", "startHour": 9, "endHour": 20, "days": [1, 2, 3, 4, 5] },
    "recipients": [
      { "to": "+12015551234", "variables": { "customer_name": "Priya" } },
      { "to": "+12015551235", "variables": { "customer_name": "Sam" } }
    ]
  }'
  • A list holds up to 1,000 rows. concurrency is 1 to 5 calls at once (default 2).
  • callWindow is optional. Outside it, rows wait until the window opens.
  • Invalid and duplicate numbers don't fail the request. They are marked skipped with a reason.
  • A row free credit does not cover (see Calls to other countries) is marked skipped with DESTINATION_REQUIRES_CARD, and the rest of the list keeps dialing. After a top-up, add those numbers to a new list.
  • If the workspace runs out of credits or hits its spending cap, the list pauses. Add credits, then POST /v1/call-batches/{id}/resume.
  • GET /v1/call-batches/{id}/calls lists every row with its status, sessionId and endReason. POST /v1/call-batches/{id}/pause and /cancel stop new dials. Calls already in progress finish.
  • Each call is a normal outbound call, billed the same way, with metadata.callBatchId set.

You need consent to call everyone on the list.

Pin an agent version

Pass agentVersion to dial with a numbered version of the agent instead of the one that is live, for example to keep a campaign on version 7 while you deploy changes. Use the version_number from GET /v1/agents/{id}/versions. Archived versions work too.

{ "to": "+12015551234", "agentId": "agent_123", "agentVersion": 7 }

The call uses that version's saved prompt, voice, greetings, stack, turn handling, language routing, and workflow graph. Agent settings that versions do not record, such as tools, knowledge bases, webhooks, and ring timeout, use their current values. agentVersion requires agentId and cannot be combined with useDraft. An unknown number returns 404 AGENT_VERSION_NOT_FOUND. Pipecat agents reject it with 400 PIPECAT_CALL_OVERRIDE_UNSUPPORTED.

Who speaks first

On an outbound call the agent's opening line comes from the first of these that is set: the per-call firstMessage, the agent's outboundFirstMessage, then the agent's firstMessage. An agent with a per-language text table (languageRouting.languages[]) checks the call language's entry first; see Greeting precedence for the full order. What you store decides what the callee hears:

ValueWhat the callee hears
A non-empty stringThat text, spoken as soon as the call connects
"" (empty string)Nothing. The agent stays silent and listens until the callee speaks
null or omittedThe next field down. If every field is null or omitted, the default greeting for the call language ("Hi, how can I help?" in English)

null does not mean "say nothing": clearing outboundFirstMessage with null brings back firstMessage or the default greeting. To open an outbound call in silence, set outboundFirstMessage: "". inboundFirstMessage follows the same rules for inbound calls.

An outbound call can get through a phone menu ("press 1 for sales") in two ways. Use the one that fits how well you know the number.

Let the agent navigatePress a known path
HowThe agent listens to the menu and presses keys with its keypad tool, send_dtmfSpeko presses a sequence you saved, the moment the call is answered
Set it withturnHandling.profile: "ivr" (IVR mode) on the agent or the calloutboundDtmf on the agent, or telephony.dtmf on the call
Use it whenThe menu is unknown, changes, or depends on what the agent hearsYou already mapped the menu, for example a supplier switchboard where 8, a pause, then 2 reaches the right desk
Model involvedYes. The model decides what to press, so it can mishear or waitNo. The keys play the same way every time, before the agent says anything

Let the agent navigate. The keypad tool is built for every phone agent, cascade and Realtime alike, unless turnHandling.keypad is false. To limit what it may press, set turnHandling.keypadAllowedKeys to the keys it may use, for example ["1", "2", "0", "#"]. The model is told the allowed keys, and a press that names any other key is refused with nothing sent. It does not limit outboundDtmf or telephony.dtmf. On outbound calls it arms when answering-machine detection or the menu's wording shows an automated menu. turnHandling.profile: "ivr" (IVR mode) also arms it when detection ends without hearing a person, which catches a long menu that never pauses. On a Realtime call, IVR mode navigates menus from the first turn. turnHandling.dtmfToolDescription changes how the tool is described to the model. See Voicemail handling for how IVR mode, hold queues and their time limits interact.

Press a known path. Save the sequence on the agent so every outbound call it places presses it:

await speko.agents.update('agent_123', { outboundDtmf: '8w2' });

Or pass it on one call, which overrides the agent's saved sequence:

await speko.voice.dial({
  to: '+12015551234',
  agentId: 'agent_123',
  telephony: { dtmf: 'ww1w8' },
});
  • A sequence is up to 64 characters of 0-9, * and #, with w or , for a half-second pause (, is stored as w). It must press at least one key. Each key is a quarter-second tone followed by a quarter-second gap.
  • The keys play once, as soon as the far end answers. Start with a pause or two (ww1) for a menu that talks over the first half-second.
  • The agent hears nothing and says nothing until the last key has gone out. Then its opening plays as usual (see Who speaks first). If the path leads to a queue or a person who answers with their own greeting, set outboundFirstMessage: "" so the agent listens first.
  • It works the same on cascade and Realtime (runMode: "s2s") calls. The agent's run mode is never consulted, because the phone carrier plays the keys, not the model.
  • A per-call telephony.dtmf wins over the agent's outboundDtmf. Send telephony: { dtmf: "" } to press nothing on one call. outboundDtmf: null on an agent update removes the saved sequence.
  • Scheduled callbacks never press the agent's saved sequence, because they ring back the person who asked for the call. Calls started from an iMessage number do not press it either.
  • outboundDtmf takes effect on the agent at once, like ringTimeoutSeconds. It is not part of drafts or versions: a draft save that includes it is rejected with 400 OUTBOUND_DTMF_NOT_DRAFTABLE.
  • Put the keys in telephony.dtmf, never after the number. A dial string such as "to": "+12015551234,,1" is rejected with 400 DTMF_IN_PHONE_NUMBER.
  • Workspaces running Pipecat agents reject telephony on the call, and do not press a saved outboundDtmf.
  • The call counts as answered when the far end picks up, before the keys play. The time spent pressing keys is billed like the rest of the call and counts toward maxDurationSeconds. The session timeline shows a sip.dial_digits_pressed event with how long the keys took.

The two approaches combine. When a known path leads to a second menu you have not mapped, press the path with telephony.dtmf and set turnHandling.profile: "ivr". The agent then takes over from wherever the keys left it.

The dtmf command on the calls API cannot press keys on an agent phone session. It acts on the legs of a call placed with the calls API and relays tones through that call's connected browser softphone. A session started with POST /v1/sessions/phone has no calls API legs, so its session id or participant identity sent as a control id fails with 404 NOT_FOUND. Use telephony.dtmf or the keypad tool instead.

How outbound calls are billed

Cascade and realtime calls (GPT-Live and Grok Voice) bill the flat per-minute rate, charged per second (see Realtime agents on the phone). For flat-rate calls, the clock starts when the callee answers, so ringing time is not billed:

OutcomeBilled
Answered and the agent spoke (to a person or a voicemail)The conversation, from answer to the carrier's hang-up
Answered, but the agent never spokeNothing
Rang, nobody answered (sip_no_answer)Nothing
Refused, the phone never rang (sip_busy, sip_declined, sip_invalid_number, sip_carrier_rejected, sip_dial_rejected)Nothing
Failed because of a Speko fault (worker, speech recognition, language model, speech synthesis or model provider)Nothing

"Nothing" includes telephony, and the rows for an agent that never spoke and for a Speko fault apply to inbound calls too. It is automatic: when such a call closes, anything it was already charged is refunded to your credits, so there is nothing to request. The refund appears on the call's cost receipt.

Telephony is billed on top of the minute for calls carried on a Speko phone number, per second of connected time (answer to hang-up). For calls placed from October 13, 2026, it bills the carrier's charge for the call, including its taxes and fees, plus 20%. Outbound calls are priced by destination country and number type, inbound calls by the country and type of the Speko number (toll-free costs more than local). No call bills below $0.01 per minute inbound or $0.015 per minute outbound, which is what most US calls pay. Earlier calls bill exactly those two rates. Calls over your own SIP trunk carry no telephony charge. A failed session pays no telephony. Post-call summaries are free.

A Speko phone number costs $1 setup and $2 a month, from prepaid credits. A few numbers cost the carrier more than that, such as some toll-free vanity numbers. Those sell at the carrier's own price for setup, monthly or both, with no markup. Number search shows each number's own price and flags these with aboveStandardPrice. To buy one, send expectedUpfrontCostUsd and expectedMonthlyCostUsd with the prices you agreed to; without them the purchase returns 409 PHONE_NUMBER_PRICE_CONFIRMATION_REQUIRED with the current quote and charges nothing. An assistant connected over MCP or OAuth can only buy numbers at the standard price; it gets 403 PHONE_NUMBER_PRICE_REQUIRES_DASHBOARD, and the owner buys the number in the dashboard. The monthly rental renews at the price the number was bought at.

When the workspace already has a number, an assistant connected over MCP or OAuth gets 409 PHONE_NUMBER_ADDITIONAL_PURCHASE_UNCONFIRMED with the numbers it owns, and nothing is charged. It should use one of those numbers, or ask the owner and send the purchase again with confirmAdditionalNumber: true. Setup is not refunded once a number is bought.

Every charge is itemised on the call's cost receipt in the dashboard and in GET /v1/sessions/{id} (usage[].chargeKind): the per-minute rate (minutes), what is billed on top of it (add_on: telephony, backend model tokens), what the minute covers (included), and what Speko absorbs (free).

Set maxDurationSeconds to cap how long a single call can run. On outbound calls the cap counts from answer, so ringing does not use it up. Pass it per call on POST /v1/sessions/phone, or save it on the agent (maxDurationSeconds, a whole number from 30 to 14400) to cap every call the agent places or answers. A per-call value wins over the agent's, and with neither the cap is 3600 seconds. A Realtime (runMode: s2s) call is held to one hour whatever either says. The agent's value takes effect at once, like ringTimeoutSeconds, and is not part of drafts or versions: a draft save that includes it is rejected with 400 MAX_DURATION_NOT_DRAFTABLE.

An outbound call rings for up to 45 seconds from when the callee's phone starts ringing, and never more than 90 seconds from dial. If the carrier never reports ringing, the call stops after 45 seconds from dial. On US and Canadian numbers the 45 seconds count from the first ring: if the phone rings again in the same call, for example after the callee declines, the window does not restart. A call that is not answered in time ends with sip_no_answer.

Set ringTimeoutSeconds (a whole number from 20 to 45) to ring for less time. It replaces the 45 seconds in both rules above: the window from when the phone starts ringing, and the window from dial when the carrier never reports ringing. The 90-second cap from dial stays. Set it on the agent to apply to all of its outbound calls, campaigns included, or pass it on POST /v1/sessions/phone to override the agent for one call. A value outside 20–45 is rejected with 400 RING_TIMEOUT_OUT_OF_RANGE. Ringing is not billed, whatever the setting.

await speko.voice.dial({ to: '+14155550123', agentId: 'agent_123', ringTimeoutSeconds: 25 });

Voicemail handling

Outbound calls use native answering-machine detection by default (a Realtime agent's calls differ — see Realtime (GPT-Live) calls below). With greetFirst: true (the default), detection runs while the agent can speak; greetFirst: false briefly holds the opening for a verdict. telephony.amd.mode: 'disabled' disables native detection and transcript-based machine cues. mode: 'carrier' also disables native detection and requires carrier/trunk support; setting that mode alone does not supply carrier verdicts to the worker. A voicemail policy does not enable detection when it is disabled or carrier-managed.

When native detection identifies recordable voicemail, turnHandling.onMachine controls the response. Set it on the agent to inherit it across calls, or override individual fields per call. For example, passing only { profile: 'ivr' } preserves the agent's onMachine and voicemailMessage settings:

const call = await speko.voice.dial({
  to: '+12015551234',
  agentId: 'agent_123',
  turnHandling: {
    onMachine: 'leave_message',
    voicemailMessage:
      "Hi, this is Ava from Acme about your renewal. I'll try again tomorrow, or call us back at 201-555-0199.",
  },
});
onMachineWhat the agent does
agent_decides (default)The verdict is handed to the model as a system note ("this is a voicemail greeting"). Your prompt's own rules apply — for example "on voicemail, call end_call immediately".
hangupEnds the answered call when voicemail is detected, without a farewell or voicemail message. An opening may already have played with greetFirst: true.
continueIgnores the verdict and carries on as a normal call: no system note, no hangup, no time limit from machineBudgetSeconds. The verdict is recorded as a worker.amd_action_gated event with reason on_machine_continue, and the call is not labelled a voicemail: a plain hangup stays a plain hangup. On a cascade call, a call-screening phase that reached the mailbox keeps its own limit.
leave_messageWaits for a 1.5-second quiet window, then speaks voicemailMessage once in the agent's voice and hangs up after playout. voicemailMessage renders the same {{variables}} as firstMessage, and can be authored per language — see Multilingual agents. If the greeting stays active for 20 seconds, it ends without speaking the message. Quiet detection is a fallback, not beep detection.
Leave a recording instead

To have the mailbox hear a recording, such as you reading the message yourself, upload it to your organization's sound library (Sounds in the dashboard, or POST /v1/sounds) and set turnHandling.voicemailSoundId to its id. Under leave_message the agent waits out the greeting in the same way, plays the file once, word for word, and hangs up when it finishes. Nothing is spoken by the model, on cascade and Realtime (GPT-Live) calls alike. On the agent page, pick the file, or upload one, under Voicemail handling → Recording.

{
  "turnHandling": {
    "onMachine": "leave_message",
    "voicemailSoundId": "snd_8f2c1a",
    "voicemailMessage": "Hi, this is Ava from Acme. Please call us back at 201-555-0199."
  }
}
  • The id must name a ready sound in your organization; otherwise the agent save or call is refused with 422 SOUND_REF_INVALID. A sound an agent uses cannot be deleted.
  • voicemailMessage is optional with a recording. If set, it is the fallback: it is spoken as usual if the file can't be fetched when the call reaches the mailbox. With neither available the result is missing_message.
  • The file is played as is, so {{variables}} and per-language variants do not apply to it.
  • Playback is capped at 3 minutes. Most mailboxes stop recording after one to three minutes.
  • Pipecat-hosted agents leave the voicemail text from their workflow; the recording applies to LiveKit-hosted agents.
  • The worker.voicemail_delivery event carries source: "recording" when the file played, and recordingUnavailable: true when it fell back.

An unavailable mailbox (for example, full or not set up) always ends without attempting a message, regardless of onMachine. It is recorded as endReason: "machine_unavailable" with report outcome unavailable.

IVR and call-screening detections continue through the navigation flow. In IVR mode the agent can follow spoken prompts and send keypad digits. Machine silence after exhausted prompts ends a line that stops making progress. IVR timeouts are not reported as voicemail.

turnHandling.machineBudgetSeconds (30 to 600, default 120) is how long the call may stay on the line after it reaches a recordable voicemail greeting, or a phone's call-screening service that never puts a person through. When it runs out the call ends with endReason: "dead_air". It bounds a voicemail left to your prompt (agent_decides) and a screener nobody accepts, on cascade and Realtime calls alike. It does not cut off a leave_message voicemail mid-sentence: once the message starts, the message's own playout bounds it. Phone menus and hold queues are not bounded by it; Waiting on hold covers them. Set it on the agent or per call:

{ "turnHandling": { "onMachine": "agent_decides", "machineBudgetSeconds": 60 } }

Waiting on hold

Once a phone menu is detected, the agent waits in the queue for as long as the line is alive. Hold music, queue announcements ("your call is important to us") and anyone speaking all count as a live line, so a long queue does not end the call. The call ends on hold only when the line is dead: no speech and no sound at all for 600 seconds.

How long the agent waits on a live line is capped by maxDurationSeconds (3600 seconds by default), counted from answer. Set it to the longest queue you are willing to pay for.

To give up on a queue sooner, set turnHandling.holdTimeoutSeconds on the agent or per call:

{ "turnHandling": { "profile": "ivr", "holdTimeoutSeconds": 1200 } }

The call then ends holdTimeoutSeconds after anyone on the line last said something conversational, even while hold music plays. Menu prompts, queue announcements and music do not restart that count; a person speaking does. The value must be a whole number from 60 to 7200, including when a pre-call webhook sets it; any other value is ignored and the default applies. It never extends a call past maxDurationSeconds. A call ended by either hold limit reports endReason: "hold_timeout".

Realtime (runMode: s2s) phone calls follow the same rules once a phone menu is detected, or from the start with profile: "ivr". On other Realtime phone calls, such as an inbound caller or a person who answered, the call ends after 600 seconds with nobody saying anything conversational, whatever sound is on the line. A holdTimeoutSeconds of 600 or more applies to the whole call. A smaller one applies only once a phone menu is detected, so a quiet caller on an ordinary call is not cut off early.

idleRePrompts do not run while the agent is in a phone menu or on hold, so "are you still there?" is never spoken into a recording or a queue.

Two idleRePrompts fields shape the check-ins on a phone call. initialDelayMs (1000 to 600000) is the silence before the first check-in while the caller has not said anything yet, counted from answer on an outbound call; omit it to use delayMs. Every later check-in, and any check-in after the caller has spoken, waits delayMs. hangupOnExhausted (default true) hangs up once the last check-in goes unanswered for one more delayMs; set it to false to keep the line open in silence until the caller speaks or maxDurationSeconds ends the call.

{ "idleRePrompts": { "enabled": true, "initialDelayMs": 20000, "delayMs": 10000, "maxPrompts": 2, "hangupOnExhausted": false } }

To change the check-ins for one outbound call, send idleRePrompts on POST /v1/sessions/phone with the same fields, without enabled. It replaces the agent's setting for that call as a whole, and turns check-ins on even when the agent has them off.

Calls ended by a voicemail policy use endReason: "voicemail_reached" and report outcome voicemail. This means a mailbox was reached, not that a message was saved: worker.voicemail_delivery separately records local playout success or failure, a greeting timeout, or a missing message. The outcome holds when the mailbox hangs up before or during your message: the call still ends as voicemail_reached, and the delivery result is call_ended.

The call report and the call.report webhook carry the same detail in a voicemail object:

{
  "outcome": "voicemail",
  "voicemail": {
    "detected": true,
    "amd_verdict": "machine-vm",
    "delivery": "delivered",
    "amd_confidence": null,
    "amd_decided_at_ms": 2850
  }
}
FieldMeaning
detectedA recordable mailbox was reached.
amd_verdictThe latest detection verdict for the line: human, machine-vm, machine-ivr, machine-unavailable or unknown. null when detection did not run.
deliveryThe leave_message result: delivered, missing_message, greeting_timeout, playout_failed, call_ended (the far end hung up while the message played), or not_attempted (the call ended before the message started). null when no message was owed.
amd_confidenceThe confidence (0 to 1) of the far-end reading that set amd_verdict. null when the machine detector's own label set it, since that label carries no score.
amd_decided_at_msMilliseconds from the answer to the event that set amd_verdict.

When the mailbox hangs up, the report can be finalized before the delivery result arrives. If the result lands while the report is still being built, the first call.report already carries it. If it lands after that call.report was sent, Speko updates the report and sends call.report once more with the corrected voicemail block (same session, new delivery id); the summary and analysis are not re-run. Treat the latest call.report for a session as authoritative. Reports finalized before this field existed carry voicemail: null.

Realtime (GPT-Live) calls

On an outbound GPT-Live call, detection reads the voice model's own transcript of the far end rather than a separate speech-to-text stage, and it is rolled out per workspace. Until it is enabled for yours it only observes: verdicts are recorded as worker.duplex.amd_shadow_verdict events, none of the actions above run, and the call's outcome is decided exactly as it would be without detection. Once enabled, onMachine works as described above, with these differences:

  • A voicemail or unavailable verdict from the classifier alone is acted on only when the far end spoke before the agent did and said at least five words that do not read like a live reply; otherwise it is recorded as worker.amd_action_gated and the call continues. An explicit recorded-mailbox announcement in the far end's speech (for example "leave a message after the tone" or "the mailbox is full") is acted on without this check, at any point in the call, unless it reads like a person talking ("I'll take a message", quoting a greeting).
  • leave_message: GPT-Live cannot read a script, so the model is told to stay silent through the greeting and then to leave voicemailMessage, which it speaks in its own words — close to what you wrote, not verbatim. A long message is shortened first, at a sentence boundary where one exists, to fit the model's instruction limit: about 1,200 characters of English, and fewer in scripts that take more tokens per character — about 420 characters of Chinese, Japanese or Korean. The realtime path does not switch languages mid-call, so only the voicemailMessage authored for the agent's configured language applies.
  • greetFirst: false is not honoured: the opening is never held for a verdict.
  • A detected voicemail left to the model (agent_decides) ends as voicemail_reached when the model ends the call, and at the latest once the mailbox goes silent or machineBudgetSeconds (default 120) runs out. IVR navigation has no machine-phase budget on a realtime call; the line guards and the one-hour realtime ceiling bound it instead.
  • Grok Voice calls have no worker-side detection. Carrier AMD (telephony.amd.mode: 'carrier') still applies to both models.

Hang up when a person answers

For campaigns that should only ever reach a mailbox, set turnHandling.onHuman: "hangup" on the agent or per call. It applies to Realtime (runMode: s2s) phone calls; a cascade call ignores it and records a worker.on_human_unsupported event.

{ "turnHandling": { "onHuman": "hangup", "onMachine": "leave_message", "voicemailMessage": "Hi, this is Ava from Acme. Please call us back at 201-555-0199." } }

With it set:

  • The agent is muted from the moment the call is answered, and no opening line is sent. The voice model may still react to what it hears, but nobody hears it, and those lines stay out of the transcript.
  • Speko decides who answered from what the far end says: each of its lines is read as a person or a machine, and answering-machine verdicts count too. A line read as a person counts once the far end then stays quiet for about 1.5 seconds, so a recorded greeting that pauses after the name is not mistaken for one. Nobody saying anything for about 4 seconds after pickup also counts as a person, because a mailbox starts its greeting at once. A line that is still unclear after 20 seconds is treated as a person once it goes quiet, and after 45 seconds in any case.
  • A person: Speko hangs up without the agent saying a word. The session ends with endReason: "human_answered" and records a worker.human_answered event. That end reason is on every call.status webhook, so you can drive an alert from it (for example, to Slack) instead of asking the model to call a tool.
  • A machine (voicemail, a phone menu, a hold queue or a call screener): the agent is unmuted (worker.pickup_decided) and the call goes on exactly as it would without onHuman. onMachine, the keypad and the call-screener handling all apply. If the model had already started talking into the muted line, it is told that nothing it said was heard, so a voicemail message it began early is left again. A person who then picks up from a call screener is hung up on too.
  • The model's own end_call is refused until the decision is made, so a person is never filed as agent_ended.

Remove any "hang up on a live person" rule from the prompt when you turn this on. Otherwise the model may still run that rule's tools (an alert, say) before Speko hangs up.

4. Receive inbound calls

When a call arrives on a registered number, Speko matches the dialed E.164 number, checks direction, creates a voice session, hydrates the linked agent, dispatches the worker, and bridges the caller into the LiveKit room.

If the caller hangs up while the call is still ringing, before the agent says anything, the session closes with status: "ended" and endReason: "caller_abandoned", and records a sip.caller_abandoned call event. It isn't counted as a failure. When LiveKit reports the leg as still ringing, the capture of the empty room is discarded (artifacts.recording.status: "discarded"); otherwise the recording is kept and served as usual.

For forwarded calls, Speko attempts to preserve the original forwarding source. It looks at Telnyx payload fields such as forwarded_from, original_to, and redirecting_number, plus SIP headers such as Diversion and History-Info. The normalized value is exposed as:

  • forwardedFromNumber in session metadata.
  • forwarded_from_number in pre-call webhook payloads.
  • call events and reports through the session metadata.

Use dispatchMetadataTemplate when you need static metadata or a legacy template alongside the linked agent:

await speko.phoneNumbers.update('pn_123', {
  agentId: 'agent_123',
  dispatchMetadataTemplate: {
    tenant: 'acme',
    line: 'front_desk',
    caller: '{{callerNumber}}',
    dialedNumber: '{{dialedNumber}}',
    forwardedFromNumber: '{{forwardedFromNumber}}',
  },
});

The agent fields are canonical. If agentId and dispatchMetadataTemplate set the same pipeline key, the persisted agent wins and the template fills the gaps.

Template keys split by name: keys from the pipeline vocabulary (systemPrompt, firstMessage, voice, intent, and the other agent-level fields) hydrate the call's pipeline config, while every other key (like tenant or line above) is static metadata — it surfaces on the session's metadata, in call events and reports, and in webhook payloads, but never changes call routing. A handful of server-internal key names (native, proxy, tools, stages, and similar) are reserved and rejected when you save the template.

5. Customize calls before answer

Configure a workspace endpoint subscribed to call.pre_call and scoped to the agent when your application needs to look up the caller, choose a greeting, inject account context, or override the call pipeline before the worker starts speaking. Only one effective pre-call endpoint may match an agent/tag route.

Speko sends:

{
  "type": "call.pre_call",
  "call_id": "session_123",
  "session_id": "session_123",
  "organization_id": "org_123",
  "direction": "inbound",
  "to": "+12015550199",
  "from": "+12015551234",
  "dialed_number": "+12015550199",
  "forwarded_from_number": null,
  "phone_number_id": "pn_123",
  "call_control_id": "sip_participant_123",
  "pipeline_config": {},
  "metadata": {}
}

Return any supported pipeline overrides at the top level or under pipelineConfig / pipeline_config:

{
  "firstMessage": "Hi Maya, thanks for calling Acme.",
  "systemPrompt": "The caller is Maya Chen, a priority customer. Keep responses brief.",
  "metadata": {
    "customerId": "cus_123",
    "plan": "enterprise"
  }
}

Supported pre-call override keys include intent, constraints, voice, systemPrompt, firstMessage, llm, ttsOptions, sttOptions, backgroundAudio, audioOutput, tools, pronunciation and text replacement rules, and idle reprompts.

The response may also carry a top-level toolSecrets object — per-call values for tools only (a short-lived access token scoped to the caller you just looked up, a tenant API base URL). Unlike variables, these never enter the prompt, the transcript, or the worker's dispatch metadata; they are stored encrypted and released only to tool execution (session.secrets.<name> in custom-code tools, {{name}} in webhook tool url/headers). Same limits and semantics as the toolSecrets request field on /v1/sessions — see Per-call secrets. On outbound calls, values sent on the dial request win over the webhook's on a name collision. An invalid toolSecrets object is dropped with a warning (names logged, never values) and the call proceeds.

{
  "firstMessage": "Hi Priya, thanks for calling back.",
  "variables": { "customer_name": "Priya" },
  "toolSecrets": { "access_token": "eyJhbGciOi...", "base_url": "https://acme.example.com" }
}

6. Track lifecycle and reports

Speko records durable lifecycle events for LiveKit, Telnyx, Speko status updates, SIP cause codes, and transfer attempts.

const call = await speko.calls.get('session_123');
const { events } = await speko.calls.events('session_123');
const report = await speko.calls.report('session_123');

Endpoints subscribed to call.status receive call progress and failure information:

{
  "type": "call.status",
  "call_id": "session_123",
  "event_type": "call.hangup",
  "provider": "telnyx",
  "status": "ended",
  "end_reason": "callee_hangup",
  "failure_cause": null,
  "sip_status_code": 200,
  "sip_status": "OK",
  "metadata": {}
}

After hangup, Speko finalizes a report with transcript entries, summary, outcome, structured data, cost breakdown, artifacts, metadata, and any scheduled callback created by analysis. Endpoints subscribed to call.report receive the same report payload. Report, analysis, and recording deliveries retry independently; inspect or manually redeliver them through speko.webhooks.deliveries.

outcome comes from the call analysis. A call on which nobody spoke can still read completed, so the report also carries contact: whether anybody reached anybody, taken from what was recorded on the line (the status, the end reason, the carrier's answer, who spoke), never from the analysis. call.report, call.analysis and GET /v1/calls/{id}/report all include it.

contactMeaning
connectedThe caller said something, or a voicemail or an unavailable mailbox answered.
no_answerThe line rang and nobody picked up.
not_connectedThe dial was refused, or the call ended without a word from either side.
no_responseThe agent spoke, and nobody replied.

contact is null while the call is open and on reports finalized before the field existed.

Call facts

call.report and GET /v1/calls/{id}/report also carry what was recorded on the line, top-level beside outcome:

{
  "end_reason": "voicemail_reached",
  "session_created_at": "2026-10-27T10:00:00.000Z",
  "ended_at": "2026-10-27T10:00:41.000Z",
  "duration_seconds": 41,
  "answered": true,
  "answered_at": "2026-10-27T10:00:06.000Z",
  "ring_duration_ms": 5400,
  "sip_code": null,
  "agent_version": 12,
  "language": "en",
  "language_switches": [],
  "dtmf": [{ "actor": "agent", "key": "1", "at_ms": 21000 }],
  "speech_detected": true,
  "speech_detected_reason": null,
  "recording_url_expires_at": "2026-11-03T10:01:30.000Z"
}
FieldMeaning
end_reasonWhy the call ended, in the vocabulary of the session's endReason. A report finalized before the session's own close can already read voicemail_reached from the recorded line verdict.
session_created_at, ended_at, duration_secondsWhen the session was created and closed, and its duration. A refused dial reads 0 seconds. created_at keeps its meaning: when the payload was built.
answered, answered_atThe carrier or the SIP leg recorded an answer, and when.
ring_duration_msHow long an outbound call rang before it was answered.
sip_codeThe far end's final SIP response on a dial that never connected (486 busy, 603 declined, 404 no such number). null once the call was answered.
agent_versionThe agent version the call ran.
language, language_switchesThe language the call started in, and each mid-call change: { at_ms, from, to, method }.
dtmfEvery keypad key pressed: { actor, key, at_ms }, where actor is agent (the agent's send_dtmf) or callee (the far end). Callee keys are recorded only with turnHandling.recordCallerKeypad: true; see below.
speech_detected, speech_detected_reasonWhether the caller said anything that reached the transcript. When false, the reason is silence, not_recognized (speech was heard but produced no transcript) or stt_error (the transcription stream failed). false only after the call ended; null on a dialed call nobody answered.
recording_url_expires_atcall.report only, beside recording_url: when that URL stops working. null when there is no recording_url.

Keys the caller presses are off by default, because callers type PINs and card numbers. Set turnHandling.recordCallerKeypad: true on the agent (or on one call's turnHandling) to record them. While it is off, Speko never stores or sends those keys, and dtmf lists only the keys the agent pressed with send_dtmf, which are always recorded.

Every at_ms counts milliseconds from session_created_at. The voicemail block adds amd_confidence (the confidence of the far-end reading that set amd_verdict; null when the machine detector's own label set it, since that label carries no score) and amd_decided_at_ms (milliseconds from the answer to the verdict). Reports finalized before these fields existed carry null for each. GET /v1/sessions/{id} returns the same facts in camelCase, for every session, and embeds this report under report.

recording_url is a presigned download URL you can fetch directly with no auth headers (a GET on the URL streams the audio). It's a signed link valid for up to 7 days from delivery (recording_url_expires_at says exactly when), so download or copy the file to your own storage rather than persisting the URL long-term. To fetch a recording on demand later, call the authenticated GET /v1/calls/{id}/recording endpoint with your API key instead.

A recording usually finishes uploading after the call ends, so the first call.report delivery often arrives with recording_url: null (and artifacts.recording.status: "uploading"). Once the recording finalizes, Speko re-fires call.report for the same call_id with recording_url populated and artifacts.recording.status: "ready". Deduplicate on call_id and treat the later delivery as authoritative for the recording. recording_url stays null when recording is disabled for the org (artifacts.recording.status: "suppressed"), when the upload failed, or when the call never connected (artifacts.recording.status: "discarded" — a refused or unanswered outbound leg, or an inbound caller who hung up while it was still ringing, captures only an empty room, so no recording is served; the same applies when the recorder never received audio in a session where nobody spoke). A recording is never discarded once the call was answered or anybody spoke.

Dedicated analysis and recording webhooks

If handling the call.report re-fire is awkward for your consumer (for example, your handler dedupes on call_id and drops the delivery that carries the recording), subscribe to the dedicated single-purpose webhooks instead. Each fires once per call — and unlike the call.report re-fire, any webhook-standard duplicate (e.g. a redelivery after a timeout) carries identical content, so deduplicating on type + call_id never loses data:

  • call.analysis fires when the LLM analysis completes: summary, outcome, structured_data, custom_data, and an analysis object (status, provider, model, completed_at). No transcript, cost, or recording — and no recording re-fire to dedupe.
  • call.recording fires when the recording reaches a terminal state. recording_url carries the presigned link (same 7-day-TTL semantics as above) when recording.status is "ready", and null when it's "failed" — so your consumer can stop waiting either way. Suppressed recordings (recording disabled for the org) never fire this event.
{
  "type": "call.recording",
  "call_id": "b2f7…",
  "session_id": "b2f7…",
  "organization_id": "org_…",
  "agent_id": "agent_…",
  "recording_url": "https://storage.googleapis.com/…",
  "recording": { "status": "ready", "duration_ms": 21625 },
  "created_at": "2026-07-09T15:15:19.131Z",
  "occurred_at": "2026-07-09T15:15:19.131Z",
  "sequence": 4,
  "webhook_id": "…",
  "webhook_tags": {}
}

Subscribe one endpoint to any combination of these events:

await speko.webhooks.create({
  name: 'Call processing',
  url: 'https://example.com/speko/calls',
  events: ['call.report', 'call.analysis', 'call.recording'],
  allAgents: true,
});

Both events are fully additive: call.report keeps its combined payload and its recording re-fire, so existing postCall consumers are unaffected. Failed deliveries retry with the same backoff as call.report.

Custom data extraction

Add extractionFields to a workspace endpoint subscribed to call.report or call.analysis to have Speko pull structured values out of every call. Each field has a name, a type (string, number, boolean, or enum), and a description that tells the analysis model what to extract — enum fields also take an options list. After the call, the model fills each field from the transcript, coerced to its declared type (or null when the call gives no basis for it), and the values arrive as a top-level custom_data object keyed by field name:

{
  "type": "call.report",
  "summary": "Jane booked a table for four.",
  "outcome": "scheduled",
  "structured_data": { "...": "..." },
  "custom_data": {
    "caller_intent": "booking",
    "party_size": 4,
    "wants_callback": true
  }
}

custom_data always carries one key per configured field, so the payload schema stays stable. A field is null when the call gave no value, and every field is null when the analysis itself failed. Manage these fields from Settings → Webhooks in the dashboard.

Fields declared on the agent (extractionFields on POST /v1/agents) reach every call.report and call.analysis endpoint for that agent, next to the endpoint's own fields.

Set maxLength on a string field to cap the delivered value, from 1 to 10,000 characters. The analysis model is asked to stay within it, and a longer value is cut to maxLength:

{ "name": "reason", "type": "string", "description": "Why the customer is leaving.", "maxLength": 200 }

Limits: up to 30 fields per webhook, each description up to 10,000 characters, with at most 40,000 characters of descriptions combined across all fields. Detailed rubric-style descriptions are encouraged for classification fields — the analysis model follows them closely.

7. Transfer callers

Use the Calls API for operator-driven transfers, or add the built-in transfer_call tool to let the agent transfer based on conversation context.

await speko.calls.blindTransfer('session_123', {
  to: '+12015554321',
  ringingTimeout: 25,
  metadata: { reason: 'billing escalation' },
});

const transfer = await speko.calls.warmTransfer('session_123', {
  from: '+12015550199',
  destinations: [
    { to: '+12015551234', label: 'Front desk' },
    { to: '+12015554321', label: 'Overflow' },
  ],
  screeningPrompt: 'Confirm the recipient can help before bridging.',
  fallback: { strategy: 'take_message' },
  voicemailDetection: { mode: 'agent', timeoutSeconds: 10 },
});

Warm transfer starts a consultation leg first. Complete the transfer when the screened recipient accepts, or cancel with tryNext: true to continue through the destination list.

Add someone to a live call

Set screening: false to skip the screening agent. The recipient joins the live call as soon as they answer. The agent goes quiet while they are on the line and speaks again when they hang up. Use it to bring yourself or a colleague into a call the agent is already on.

await speko.calls.warmTransfer('session_123', {
  to: '+12015551234',
  screening: false,
});

Nobody screens the answer, so a voicemail greeting joins the call too. If the recipient declines or does not answer, the fallback runs as usual.

Let the agent transfer with transfer_call

Add the transfer_call builtin to an agent to let the model start the transfer itself. Set defaultMode to choose blind or warm. Transfers are warm when you leave it out.

{
  "name": "transfer_call",
  "description": "Transfer the caller to Russell when they ask for him.",
  "parameters": { "type": "object", "properties": {}, "required": [], "additionalProperties": false },
  "executionMode": "builtin",
  "source": {
    "kind": "builtin",
    "name": "transfer_call",
    "config": {
      "defaultMode": "blind",
      "ringingTimeout": 25,
      "destinations": [{ "to": "+12015554321", "label": "Russell" }]
    }
  }
}

A blind transfer rings the destination and bridges the caller straight through. A warm transfer first connects a screening agent to the recipient, then bridges the caller once the recipient accepts.

FieldTypeModeMeaning
destinationsarray, 1–10, requiredbothWhere the call can go. Each item has to (E.164, required), label (required), and optional id, mode, outboundTrunkId, screeningPrompt, screening, summary.
defaultMode"blind" | "warm"bothMode for every destination. Default "warm".
destinations[].mode"blind" | "warm"bothOverrides defaultMode for one destination.
ringingTimeoutinteger seconds, max 120bothHow long the destination rings.
destinations[].screeningbooleanwarmfalse adds the recipient straight into the call on answer, with no screening agent. The agent stays quiet until they leave. Default true.
destinations[].screeningPromptstringwarmThe screening agent's first spoken line to the recipient. It is not an instruction to the agent.
destinations[].summarystringwarmCall context the screening agent uses to brief the recipient.
waitUntilAnsweredbooleanwarmWait for the recipient to answer before the tool returns.
fallbackobjectwarmWhat happens when nobody accepts: strategy is return_to_assistant, take_message, or end_call.
voicemailDetectionobjectwarmmode (agent, amd, disabled), enabled, timeoutSeconds (max 60).

The config is validated when you save the tool, and unknown keys are rejected. Names such as mode, kind, or transferType at the top level fail validation. Use defaultMode.

Browser (web) calls to cascade agents support warm transfers. The recipient's phone shows your workspace's default outbound number, the first outbound-ready number on the workspace. A blind transfer needs a phone line to hand off, so on a browser call it is refused and the agent tells the caller it cannot transfer them. Simulated test runs never dial a recipient.

The model can also pass mode, destination, reason, summary, and screeningPrompt as call arguments. A mode argument from the model overrides defaultMode and destinations[].mode. Leave mode out of the tool's parameters and set "additionalProperties": false, so the model is not offered a way to switch to warm.

Transfer webhooks

Subscribe an endpoint to call.transfer.initiated, call.transfer.completed, and call.transfer.failed to follow agent and Calls API transfers. Each attempt reports the destination tried (to), the mode, and the outcome, with a failureCause when it failed. See call control events for the payload.

Next

On this page