Originate outbound call | Voice Platform

Originate a new outbound call. Returns immediately with the new session_uuid; call progress is delivered via webhooks.

Triggered webhooks: command.session.dial.accepted, session.ringing_started, session.early_media_started (optional, NOT an answer), session.answered, session.ended

Originate a new outbound call. Returns immediately with the new `session_uuid`; call progress is delivered via webhooks. **Triggered webhooks:** `command.session.dial.accepted`, `session.ringing_started`, `session.early_media_started` (optional, NOT an answer), `session.answered`, `session.ended`

Authentication

AuthorizationBearer

Application auth. Send Authorization: Bearer <app_uuid>:<api_key>. See Authentication for details.

Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>`. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]+$"<=128 characters

Optional client-generated key for a mutating endpoint. It identifies one method, route, query, content type, and exact raw body within the authenticated app. Reusing it for a different request returns 422. While its record exists, a retry replays the original accepted response when available. Keys are valid for 1 hour. Allowed characters: letters, digits, dot, hyphen, underscore; max 128 characters. See the Idempotency guide.

Request

This endpoint expects an object.

fromstringRequiredformat: "^\+[1-9]\d{1,14}$"

Caller ID to present, in the same E.164 format with leading + as to (e.g. +972527121102). The schema validates canonical syntax only. Runtime country policy must support the number, and it must be on the app’s caller-ID allow-list. A supported but non-allow-listed value is rejected with 403 forbidden (no call is placed, no webhooks fire). Branch on the response code, not the human message. The gateway does not substitute a default caller ID; an SDK MAY catch 403 forbidden for this operation and retry with its own configured approved default.

Caller ID to present, in the same E.164 format with leading `+` as `to` (e.g. `+972527121102`). The schema validates canonical syntax only. Runtime country policy must support the number, and it must be on the app's caller-ID allow-list. A supported but non-allow-listed value is rejected with `403 forbidden` (no call is placed, no webhooks fire). Branch on the response `code`, not the human message. The gateway does not substitute a default caller ID; an SDK MAY catch `403 forbidden` for this operation and retry with its own configured approved default.

max_duration_secintegerRequired1-14400

Maximum total call duration in seconds. A typical value is 3600.

ring_timeout_secintegerRequired1-300

Pre-answer ring timeout in seconds, measured from when dialing begins (the moment the request is accepted / command.session.dial.accepted is emitted), NOT from when the destination phone starts ringing. Call setup and routing consume part of this budget, so the callee experiences less ring time than the value set here. On expiry the dial ends with session.ended (answered=false, hangup_cause=“timeout”). Distinct from max_duration_sec, the post-answer cap.

Pre-answer ring timeout in seconds, measured from when dialing begins (the moment the request is accepted / `command.session.dial.accepted` is emitted), NOT from when the destination phone starts ringing. Call setup and routing consume part of this budget, so the callee experiences less ring time than the value set here. On expiry the dial ends with `session.ended` (answered=false, hangup_cause="timeout"). Distinct from `max_duration_sec`, the post-answer cap.

tostringRequiredformat: "^\+[1-9]\d{1,14}$"

Destination number in international E.164 format with leading + (e.g. +972527121102). The schema validates canonical syntax only. Runtime country and trunk policies determine whether the destination is currently dialable; an unsupported destination is rejected with 400 invalid_request.

Response

Dial accepted

session_uuidstring

statusenum

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

413

Content Too Large Error

415

Unsupported Media Type Error

422

Unprocessable Entity Error

500

Internal Server Error

503

Service Unavailable Error

$	curl -X POST https://api.telekesher.dev/v1/sessions:dial \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"from": "+972747713001",
>	"max_duration_sec": 3600,
>	"ring_timeout_sec": 30,
>	"to": "+972527121102"
>	}'