Ring a number without connecting it (gate opener)

Rings to from one of your own voice numbers (from) and never connects the call: the ringing stops after about ringSecs seconds (a whole number from 3 to 30, default 10), or earlier when the target declines it; the carrier ends the ringing with a delay of up to 3 seconds, so the ringing time in the record (ring.rangSecs) is a little longer. It is meant for GSM gates, locks and boxes that open when they recognise the calling number. The target sees exactly from as the caller (without from, your first active number is used), so the gate must have it on its list of allowed numbers. The response comes RIGHT after the carrier accepted the order, within about a second and before the ringing has finished: status is initiated and there is no result yet. The result arrives by webhook (call.no_answer for rang and ended_early, call.completed for answered) and is in GET /v1/calls/{id} as ring.outcome (with ?waitSecs= the server waits until the attempt has finished). The value of ring.outcome is rang, ended_early, answered or unknown (the last one while the result is still being settled from the carrier's records). One attempt costs 0.25 CZK excluding VAT, charged once the carrier accepted the order; if the target picks up, volai hangs up at once and the connected seconds are billed on top as an outbound call. Rings do not count towards the automatic destination block, but your do-not-call list applies. Limits per account, independent of the call limits: 30 rings per minute, 500 per day and 120 per hour to one number. Supports the Idempotency-Key header.

post/v1/rings

Request

  • Base URL: https://volai.cz
  • URL: https://volai.cz/v1/rings
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional key for one logical request. Its scope is global to this API key, independent of the HTTP method, path, or body: use a new value for every distinct logical action across all endpoints and request bodies, and reuse it only to retry the exact same logical request. Reusing a non-blank key within 24 hours returns the stored response; a concurrent request with the same key returns 409 idempotency_in_progress. A missing or whitespace-only value disables idempotency.

Request body

tostring required

Number to ring, with Czech +420 or Slovak +421 country code, normalized to E.164. The call is never connected: ringing stops after about ringSecs seconds (the carrier ends it with a delay of up to 3 seconds), or earlier when the target declines it. Rejected when the number is on your do-not-call list; the automatic 30-day block after repeated unanswered calls does not apply to rings.

fromstring

Active voice number of your account to ring from, in E.164 format (see GET /v1/numbers). The target sees exactly this number as the caller, so it must be on the allow list of the gate you open. Omit it to use your first active number; an account without an active number gets ring_needs_number.

ringSecsinteger

How long to ring before volai hangs up, in whole seconds, 3-30. Defaults to 10. A gate usually opens as soon as it sees the call, so a short value is enough. Values outside the range are rejected, not clamped.

Response

Ring ordered

idstring required

Id of the ring attempt. It is also the call id for GET /v1/calls/{id}.

status'initiated' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'missed' | 'no_answer' required

Status of the ring attempt's call record: initiated right after the carrier accepted the order. The result arrives by webhook (call.no_answer or call.completed) or in GET /v1/calls/{id}, where ring.outcome says how the attempt ended.

kind'ring' required

Always ring.

fromstring required

The voice number of your account that the target saw as the caller, in E.164 format.

tostring required

The number that was rung, in E.164 format.

requestedSecsinteger required

Seconds of ringing that were requested: the ringSecs of the request, or 10 when it was omitted.

priceHalinteger required

Price of this attempt in hellers (1/100 CZK), excluding VAT, charged once the carrier accepted the order. 0 means nothing was charged in this response: either the carrier gave no clear answer to the order, or charging failed after the carrier had confirmed it. The price is then charged later, once the carrier's call record confirms the attempt. Seconds the target actually answers are billed on top of this later, at the outbound call rate.

Changes

No recorded changes to this operation across all 1 revision of this API.