Create phone session

POST /v1/sessions/phone — place an outbound PSTN call backed by a Speko voice session.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

to*E164

Match^\+[1-9]\d{6,14}$

from?E164

Match^\+[1-9]\d{6,14}$

agentId?string

Persisted agent to run. Required unless intent is supplied.

useDraft?boolean

Dial with the agent's unpublished draft instead of its deployed version, to hear a change before you ship it. Only applies with agentId.

runMode?string

Run mode for this call. s2s hosts the call on the default speech-to-speech model (GPT-Live) instead of the STT → LLM → TTS cascade; cascade forces the cascade. Overrides the agent's saved run mode, and is the only way a call without an agent can run speech-to-speech. If the speech-to-speech route cannot be hosted, the call runs the cascade and records an s2s.fallback event; it never fails with a 4xx.

Value in"cascade" | "s2s"

intent?

constraints?

voice?string

systemPrompt?string

Replaces the agent's system prompt for this call. Compiled as a template when variables is sent.

firstMessage?string

Replaces the agent's opening line for this call. Compiled as a template when variables is sent.

variables?

Per-call values for {{name}} placeholders in the prompt and greeting. Strings, up to 10,000 characters each. Sending this key makes an unresolved variable a 400 MISSING_TEMPLATE_VARIABLES.

toolSecrets?

Per-call values only tools can read, such as an access token. Never reach the prompt or transcript. Each value at least 6 characters.

Propertiesproperties <= 32

timezone?CallTimeZone

IANA time zone for this call. Sets the agent's clock and {{system.now}}; overrides the agent's saved timezone.

Length1 <= length <= 64

llm?

ttsOptions?

sttOptions?

telephony?

turnHandling?

Per-call turn-taking posture for an outbound phone call — e.g. dialling a number known to answer with a menu. Replaces the agent's stored turnHandling wholesale for this call.

webhookTags?

Case-sensitive routing tags for workspace webhook endpoints. Requires agentId.

Propertiesproperties <= 20

metadata?

Your own key/value pairs, stored on the session and echoed back in session reads, call reports, and webhook payloads. Opaque to Speko: it never reaches the agent's prompt and overrides nothing. Use variables for values the agent should say or use, and toolSecrets for values only tools should see.

maxDurationSeconds?integer

Hard cap on the call's duration in seconds, measured from session creation, so dialing and ringing count. The call is ended when the cap passes. Values outside 30–14,400 are clamped to that range, and a call hosted on a speech-to-speech model is held to 3,600.

Default3600

Response Body

`application/json`

{
  "sessionId": "string",
  "callControlId": "string",
  "roomName": "string",
  "status": "dialing",
  "to": "+12015551234",
  "from": "+12015551234"
}

{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "not found",
  "code": "NOT_FOUND"
}

Create phone session

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`