---
title: "Ring a number without connecting it (gate opener)"
method: POST
path: "/v1/rings"
---

# Ring a number without connecting it (gate opener)

`POST /v1/rings`

## Request

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

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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `to` string, 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.
  - `from` string: 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.
  - `ringSecs` integer: 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 `200`

Ring ordered

- object
  - `id` string, 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`.
  - `from` string, required: The voice number of your account that the target saw as the caller, in E.164 format.
  - `to` string, required: The number that was rung, in E.164 format.
  - `requestedSecs` integer, required: Seconds of ringing that were requested: the ringSecs of the request, or 10 when it was omitted.
  - `priceHal` integer, 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.

## Other responses

- `400`: Error codes: validation (request), invalid_number (request), unsupported_country (request), blocked_destination (request), on_dnc (account), cannot_call_own_number (request), cannot_call_volai_number (request).
- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account), subscription_cap_reached (account).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: from_number_not_owned (account), ring_needs_number (account).
- `409`: Error codes: idempotency_in_progress (busy), destination_busy (busy).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).
- `502`: Error codes: callback_failed (service).
- `503`: Error codes: ledger_unavailable (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)