Vorbal API Documentation

Start an outbound call and return its new session_uuid after the request is admitted. A 202 Accepted response confirms only admission; it does not confirm that the destination rang or answered. Call progress and completion are reported through webhooks.

Triggered webhooks: session.ringing_started, session.answered, and session.ended. The optional session.early_media_started webhook does not indicate an answer.

See Session lifecycle events for complete payload schemas and examples.

Start an outbound call and return its new `session_uuid` after the request is admitted. A `202 Accepted` response confirms only admission; it does not confirm that the destination rang or answered. Call progress and completion are reported through webhooks. **Triggered webhooks:** `session.ringing_started`, `session.answered`, and `session.ended`. The optional `session.early_media_started` webhook does not indicate an answer. See [Session lifecycle events](/api/sessions#lifecycle-events) for complete payload schemas and examples.

Authentication

AuthorizationBearer

Application auth. Send Authorization: Bearer <app_uuid>:<api_key> using any active key in the app’s collection. See Authentication for details.

Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>` using any active key in the app's collection. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

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. +972500000000). 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 platform 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. `+972500000000`). 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 platform 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 returns 202 Accepted), 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 returns 202 Accepted), 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. +972500000000). 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": "+972740000000",
>	"max_duration_sec": 3600,
>	"ring_timeout_sec": 30,
>	"to": "+972500000000"
>	}'

Originate outbound call

Authentication

Headers

Request

Response

Errors