Połączenie

REST API

Kompletna dokumentacja API v1. Wszystko jest w JSON, a błędy mają jeden wspólny kształt. Ceny volai są liczbami całkowitymi w setnych częściach korony (sufiks Hal); połączone faktury używają jednostek podrzędnych podanej waluty.

Uwierzytelnianie

Każde żądanie zawiera klucz API w nagłówku Authorization: Bearer vk_... . Klucz otrzymają Państwo w portalu, w sekcji Dostęp i API (więcej szczegółów w Szybkim starcie).

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

Całe to API ma też opis maszynowy pod GET /openapi.json (OpenAPI 3.1, klucz API nie jest wymagany) - można z niego wygenerować klienta, kolekcję Postman albo podłączyć go bezpośrednio do n8n.

Format błędu

Błąd ma zawsze ten sam kształt, niezależnie od tego, co zawiodło:

{
  "error": {
    "code": "insufficient_credit",
    "cause": "account",
    "message": "Insufficient credit. Account balance is 3.00 CZK. Top up at volai.cz/en/credit and try again.",
    "action": "Top up the credit at https://volai.cz/en/credit (or ask the account owner to), then send the request again. Nothing was charged and volai itself is up.",
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Te pięć może pojawić się niemal wszędzie - poniższa dokumentacja endpointów wymienia poza nimi tylko kody specyficzne dla sytuacji:

400 (nieprawidłowe dane wejściowe) i 404 (nie znaleziono rekordu) mogą się pojawić niemal wszędzie, ale ich code jest specyficzny dla pola lub endpointu - dokładna lista zawsze znajduje się przy poszczególnym wywołaniu poniżej. Niektóre działania mogą też zwrócić 502 (błąd zewnętrznego dostawcy - sieci telefonicznej, ElevenLabs) albo 503 (tymczasowo niedostępne, prosimy spróbować za chwilę).

Czyja to sprawa: cause i action

Każdy błąd zawiera też cause (cztery wartości) i action (jedno zdanie po angielsku o tym, co zrobić, które można odczytać użytkownikowi dosłownie). cause to maszynowo czytelna odpowiedź na pytanie, czy błąd musi naprawić Państwa kod, Państwa konto, upływ czasu, czy my:

Dla agentów AI (Claude Code, Cursor, własne skrypty): według cause należy informować użytkownika, kto naprawia błąd. Przy request wskazać pole z message, przy account powiedzieć, co zmienić na koncie lub które id sprawdzić, przy busy odczekać i ponowić, a o problemie po stronie volai mówić tylko przy service. Nigdy nie zgłaszać request, account ani busy jako awarii volai.

Przyczynę określa kod, a nie status HTTP: limity konta (agent_limit, tool_limit, api_key_limit, relay_lease_limit) zwracają 400 i nadal są account; not_found na rekordzie to account (odpowiedź nie może ujawniać, czy cudze id istnieje), nieznana ścieżka pod /v1 to request. Pełne mapowanie kodów na przyczyny dla każdej operacji znajduje się w GET /openapi.json (opis każdej odpowiedzi z błędem).

Komunikat dla kodu validation wskazuje pole (ścieżka z kropkami w treści, na przykład dataFields.0.type), faktyczną wartość i akceptowane maksimum, na przykład Field "knowledge" is 210000 characters long, the maximum accepted is 200000. lub Field "systemPrompt" is required. Limity produktowe (60 / 6000 / 300 / 20000 znaków dla nazwy, instrukcji, celu i wiedzy agenta) przychodzą jako osobne kody invalid_name, invalid_system_prompt, invalid_goal, invalid_knowledge z dokładną liczbą. Nieznane pole w ścisłej treści (wersja robocza agenta) zwraca Unknown field "revision". Remove it; the documentation lists the accepted fields.

requestId i docsUrl

Każda odpowiedź v1 (udana lub z błędem) zawiera unikalny identyfikator żądania w nagłówku X-Request-Id (req_ i 16 znaków szesnastkowych) - błąd powtarza go też w treści jako requestId. Odtworzona odpowiedź idempotentna dostaje WŁASNY bieżący requestId - nagłówek i treść nigdy się nie rozchodzą, choć reszta odpowiedzi jest identyczna jak za pierwszym razem. Po przesłaniu tego identyfikatora pomoc techniczna znajdzie w logu dokładnie to jedno żądanie.

Treści błędów zawierają też docsUrl - link prowadzący prosto do tej sekcji.

W przypadku wersji roboczych agenta (zob. sekcja Wersje robocze agenta poniżej) błąd revision_conflict zawiera też currentRevision - bieżącą rewizję. Należy ją wczytać przez GET .../draft i przejrzeć różnice przed ponowieniem zapisu - nie należy ślepo wysyłać ponownie tej samej treści z tym samym expectedRevision.

{
  "error": {
    "code": "revision_conflict",
    "cause": "request",
    "message": "The draft has changed since you last read it. Fetch the latest revision and try again.",
    "action": "Reload the record you are changing - GET /v1/agents/{id}/draft (or the get_agent_draft tool) for an agent draft, GET /v1/tasks/{id} (or the get_task tool) for a task - reapply your change on top of its current revision and send the request again with that value in expectedRevision (agent draft) or revision (task). This is not a volai outage.",
    "currentRevision": 4,
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Błąd subscription_confirmation_required (409) zawiera też confirmUrl - link do strony portalu, na której osoba zalogowana na konto potwierdza zmianę zwiększającą kwotę, jaką wolno obciążyć zapisaną kartę (zob. PATCH /v1/subscription). Żądanie niczego nie zmieniło; link jest ważny 24 godziny i można go użyć raz.

{
  "error": {
    "code": "subscription_confirmation_required",
    "cause": "request",
    "message": "This change was not applied, because it raises what may be charged to the saved card, and only a person signed in to the portal can confirm that. Nothing was changed. Open confirmUrl in a browser signed in to the account, review the change and confirm it; the link is valid for 24 hours and can be used once.",
    "action": "Nothing was changed, on purpose: either the change raises what may be charged to the saved card, or the account is a consumer who must make the request to start the plan in person, so only that person can confirm it. Give the confirmUrl from this error to the account owner to open while signed in to the volai portal; a confirmation link is valid for 24 hours and works once, a link to the plan form stays valid. Do not send the same request again: it only produces a new link. This is not a volai outage.",
    "confirmUrl": "https://volai.cz/kredit/pausal/potvrdit?t=eyJ1aWQiOiJ1X3NhbXBsZSJ9.4f1a9c0e",
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Nagłówki

Po zweryfikowaniu klucza KAŻDA odpowiedź (udana lub z błędem) zawiera RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset (sekundy do zresetowania bieżącego okna) - 429 z limitu klucza API dodaje też Retry-After z tą samą liczbą sekund. 429 rate_limited z limitu połączeń wychodzących (POST /v1/calls) niesie własny czas oczekiwania w Retry-After - jak długo potrwa zwolnienie tego limitu, jeśli jest znany.

401 zawiera nagłówek WWW-Authenticate: Bearer realm="volai", error="invalid_token" (RFC 6750), dzięki czemu biblioteka klienta HTTP może rozpoznać przyczynę niepowodzenia bez analizowania treści.

Nieznana ścieżka i błędna metoda

Nieznana ścieżka pod /v1 (w tym samo /v1) zwraca JSON 404 o tym samym kształcie błędu co wszędzie - {"error":{"code":"not_found", ...}} - dla każdej metody (GET, POST, PUT, PATCH, DELETE, OPTIONS i HEAD). Wyjątek: błędna METODA na ISTNIEJĄCEJ ścieżce (na przykład DELETE /v1/balance) pozostaje zwykłym 405 z Next.js bez treści JSON - jedyne miejsce w całym v1, gdzie błąd nie ma udokumentowanego kształtu.

Idempotentność

POST /v1/messages, POST /v1/calls, POST /v1/rings, POST /v1/voice-messages, POST /v1/relay, POST /v1/numbers, POST /v1/numbers/orders, POST /v1/sms-numbers, POST /v1/voice-sms-numbers, POST /v1/agents, POST /v1/tools, POST /v1/agents/{id}/draft/publish, POST /v1/agents/{id}/test-call, POST /v1/integrations, POST /v1/tasks, POST /v1/tasks/{id}/start, POST /v1/tasks/{id}/process, POST /v1/credit/topup, POST /v1/credit/auto-topup/setup, POST /v1/subscription/checkout, POST /v1/subscription/pay i POST /v1/subscription/card przyjmują nagłówek Idempotency-Key. Klucz jest globalny dla danego klucza API, niezależnie od metody HTTP, ścieżki i treści. Każdemu odrębnemu działaniu logicznemu, we wszystkich endpointach i treściach żądań, należy nadać nową wartość; tę samą wartość wolno użyć ponownie tylko przy ponawianiu dokładnie tego samego żądania logicznego, zwykle po przekroczeniu czasu, gdy nie wiadomo, czy pierwsza próba się powiodła. W ciągu 24 godzin otrzymają Państwo wtedy dokładnie tę samą odpowiedź co za pierwszym razem, w tym odpowiedź z błędem, jeśli pierwsza próba się nie powiodła, a nic nie zostanie wysłane ani wywołane dwukrotnie. Można użyć identyfikatora zamówienia z własnej aplikacji plus nazwy konkretnego działania. Równoległe żądanie z tym samym kluczem, które wciąż trwa (odpowiedź nie jest jeszcze zapisana), zwraca 409 idempotency_in_progress - prosimy spróbować za chwilę.

Dla POST /v1/numbers/orders klucz jest trwale powiązany z zamówieniem, zanim zostanie wywołany operator; ponowne użycie go z innym adresem zwraca 409 idempotency_conflict. Jeśli po zakupie operator da niejednoznaczną odpowiedź, zamówienie może wymagać przeglądu statusu.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: objednavka-4471" \
  -d '{"to": "+420777123456", "body": "Dziękujemy za zamówienie."}'

Limity zapytań

60 żądań na minutę na klucz API (MCP korzysta z tego samego limitu - używa tego samego klucza). Przekroczenie zwraca 429 i nagłówek Retry-After z liczbą sekund do następnej próby.

POST /v1/messages ma ponadto własny dodatkowy limit: najwyżej jeden SMS na 2 sekundy i 100 SMS na konto dziennie. Wysyłka z numeru komórkowego (fromNumber) ma dalszy dzienny limit na konto: 20 wiadomości w pierwszych 30 dniach po zakupie numeru, potem 50. GET /v1/sms-numbers pokazuje, ile zostało i kiedy limit się resetuje (dailySendRemaining, dailySendResetsAt).

Połączenia wychodzące (POST /v1/calls, relay i połączenia testowe) mają wspólny własny limit: 10 połączeń na minutę i 1000 na dobę na konto, przy czym jednocześnie mogą trwać najwyżej 2 połączenia wbudowanego agenta.

Ile z limitu 60/min Państwu zostało, widać jeszcze przed osiągnięciem 429 - w nagłówkach RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset, które zawiera każda odpowiedź (zob. sekcja Format błędu > Nagłówki wyżej).

Stronicowanie

GET /v1/messages i GET /v1/calls przyjmują limit (maksymalna liczba zwracanych rekordów - domyślnie 50, ograniczona do 200 nawet przy większym żądaniu) oraz before (znacznik czasu w milisekundach - zwraca tylko starsze rekordy).

hasMore i nextBefore

Obie odpowiedzi zawierają też hasMore (wartość logiczna - istnieje starsza strona) i nextBefore (znacznik czasu ostatniego zwróconego rekordu albo null, gdy hasMore ma wartość false). Na następną stronę należy wysłać nextBefore z poprzedniej odpowiedzi jako nowe before - bez ręcznego liczenia offsetu.

before jest WYŁĄCZNE (zwraca tylko rekordy ściśle starsze, nigdy równie stare) - ostatni rekord poprzedniej strony nigdy nie powtarza się na następnej. W rzadkim przypadku, gdy dwa rekordy mają dokładnie ten sam znacznik czasu w milisekundach na granicy stron, drugi może wypaść. Należy deduplikować po id - nie wolno zakładać, że strony nigdy niczego nie pomijają.

GET /v1/calls?direction=in lub ?direction=out przeszukuje historię partiami z twardym limitem liczby partii - hasMore: true może więc oznaczać albo "na pewno istnieje kolejna strona", albo "przeszukano partie do limitu i nie dotarliśmy jeszcze do końca historii". false zawsze oznacza, że historia w tym kierunku naprawdę się skończyła.

Wersjonowanie

Aktualna wersja publicznego interfejsu to 1.57.0 (GET /openapi.json, pole info.version - zob. akapit o maszynowym opisie API we wstępie powyżej). Zmianą wersji rządzą trzy zasady:

1. W obrębie v1 dodawane są wyłącznie pola OPCJONALNE i nowe endpointy - istniejące pola nigdy nie znikają, nie zmieniają typu ani znaczenia. Integracja, która odczytuje tylko znane sobie pola, nigdy nie zostanie zepsuta przez aktualizację. Jedynym wyjątkiem była wersja 1.5.1, która przestała zwracać answeredBy dla połączeń PRZYCHODZĄCYCH - pole nigdy nie miało tam sensownej wartości (zob. Dziennik zmian poniżej).
2. Pole wymagane albo zmiana znaczenia istniejącego pola trafia zawsze wyłącznie w nowej wersji głównej (v2) - nigdy jako cicha zmiana w v1.
3. W przypadku wersji roboczych agenta (zob. Wersje robocze agenta powyżej) zawsze należy odsyłać dokładnie ten obiekt, który odczytano z GET .../draft - treść PUT/POST jest .strict(), więc nieznany klucz (powiedzmy z nowszej wersji, o której integracja jeszcze nie wie) zwraca 400 validation zamiast zostać po cichu odrzucony.

Dziennik zmian

• 5 Nov 2026 (1.57.0): The agent language accepts 20 values: cs, sk, en, de, pl, nl, pt, sl, ro, da, et, lv, bg, fi, el, fr, it, hu, lt, sv. A number in another country can be routed to an ElevenLabs agent; the error el_outbound_trunk_not_configured (HTTP 503, cause service) means our outbound trunk is missing. REST and MCP messages stay in English.
• 4 Nov 2026 (1.56.0): GET /v1/voice-sms-numbers/countries and the MCP tool list_voice_sms_countries return monthlyFeeHal for every country (hellers per 30 days excluding VAT). POST /v1/voice-sms-numbers with country orders the number at that country's fee from the offer; no fee confirmation is added. The MCP tool order_voice_sms_number requires confirmedMonthlyFeeHal equal to the fee of the chosen country; any other value is a validation error and nothing is ordered, while the Prague number still confirms 4900. A number record carries the monthlyFeeHal of its country and the same amount is charged by the first fee and every renewal. A country without a set fee does not appear in the offer.
• 4 Nov 2026 (1.55.0): POST /v1/voice-sms-numbers accepts an optional country (ISO 3166-1 alpha-2, uppercase); without it the Prague number is ordered as before. The countries the account may order are returned by GET /v1/voice-sms-numbers/countries and the MCP tool list_voice_sms_countries; a country outside that list is rejected with country_not_offered and nothing is charged. Number records carry country and sms, and a number outside Czechia rejects sending SMS. Outbound calls go only to Czechia, and to the country of the number only where the country_and_cz zone is enabled; the gate rejects any other destination. At most 2 numbers per country.
• 4 Nov 2026 (1.54.0): regions in GET /v1/numbers/available, the region parameter of POST /v1/numbers and the search_available_numbers and buy_number tools now know jihocesky, karlovarsky, kralovehradecky, liberecky, moravskoslezsky, olomoucky, pardubicky, plzensky, stredocesky, ustecky, vysocina, zlinsky. Regional stock is small, so pool_empty is more common there: use join_number_waitlist or order_number_from_region.
• 4 Nov 2026 (1.53.0): The offer catalogue now knows all 14 regions. A regional offer (jihocesky, karlovarsky, kralovehradecky, liberecky, moravskoslezsky, olomoucky, pardubicky, plzensky, stredocesky, ustecky, vysocina, zlinsky) appears in regions of GET /v1/numbers/available and in the MCP descriptions only once it is on sale; until then it is rejected as an unknown region. The regionLabel text changes: a number from a region carries the English region name, such as Moravian-Silesian Region.
• 4 Nov 2026 (1.52.1): A header value with three asterisks in a row (a leftover of the mask, such as Bear***abc) is rejected by PUT /v1/webhook and set_webhook with invalid_webhook_headers; previously only the whole mask was. The descriptions of get_webhook, send_test_webhook and the MCP server instructions mention headers, and the docs now say the test event carries custom headers. Value limits (1 to 1000 printable ASCII characters) added to OpenAPI and the webhooks page.
• 3 Nov 2026 (1.52.0): PUT /v1/webhook and MCP set_webhook accept optional headers (at most 5 headers, values up to 1000 characters, printable ASCII only). GET/PUT /v1/webhook and get_webhook/set_webhook return a new headers field with masked values (Bear***, {} when none are set). Omitting headers keeps the stored ones, {} removes them, and a value equal to the mask keeps the stored one. Changing the URL to a different domain drops stored headers, and a mask is rejected there. host, content-type, content-length, volai-signature and hop-by-hop headers cannot be set. Headers go with every event including webhook.test and are not sent when a delivery is redirected to a different domain. New error invalid_webhook_headers (400).
• 3 Nov 2026 (1.51.0): REST POST /v1/voice-messages with the body {to, text, repeat?} (text 1 to 500 characters, repeat 1 to 3, default 1; an unknown field including ringingTimeoutSecs is rejected with validation) returns {id, status, from} and accepts an Idempotency-Key header like POST /v1/calls. The MCP tool send_voice_message calls the same service. The result is in GET /v1/calls/{id} as kind: "voice_message" with a voiceMessage block (text, repeat, repeatPlayed, completed) and in the call.completed or call.no_answer webhook; the call summary e-mail is not sent for a voice message. New errors voice_messages_disabled (503, the feature is switched off), voice_message_unavailable (503, the voice engine cannot accept messages) and email_unverified (403).
• 1 Nov 2026 (1.50.0): REST GET, PUT and DELETE /v1/account/spend-cap (response {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}; PUT takes capHal in whole hellers excluding VAT from 5,000 to 100,000,000, warnShare from 0.5 to 0.99 with a default of 0.8, and inboundAboveCap, which is not overwritten on a change when the field is omitted) and MCP get_spend_cap, set_spend_cap and clear_spend_cap, all over lib/service/spend-cap.ts like the Monthly spending cap section under Credit. Once the cap is reached, POST /v1/calls, /v1/messages, /v1/rings, /v1/relay, the test call and task dialling are refused with the new error spend_cap_reached (HTTP 402, nothing is charged); an inbound agent call without inboundAboveCap: true ends after one sentence and the call carries endReason: spend_cap. The month's spend (Europe/Prague) is counted on every account, also without a cap, and includes the part covered by the monthly plan credit. Number fees, the Done for you round and the monthly plan are not counted; the cap does not stop calls already running or CDRs booked after midnight, forwarding without an agent, or outbound calls from a number in Own SIP PBX mode with inboundAboveCap: true. Warning and reached e-mails go at most once a month and are released again when the cap changes. REST POST /v1/agents/{id}/draft/knowledge-import with a body of {url} or {text, filename} (a .txt or .md file up to 1 MB; the portal takes a file up to 800 kB), optionally mode (append by default, or replace), preview (only returns the result, writes nothing) and expectedRevision. The MCP tool import_agent_knowledge (id, url or text + filename, the same optional fields) calls the same service, lib/service/knowledge-import.ts. The text is written into knowledge of the DRAFT and the source into the new knowledgeSources field (at most 20 sources: url or filename, importedAt, chars), which the agent shape now also returns (GET /v1/agents/{id}, list and detail). What does not fit into 20,000 characters is summarized by a model (method: summarized) or cut (truncated). Errors: invalid_import_url, private_address, invalid_knowledge, import_too_large, revision_conflict, rate_limited (10 imports per hour per account). A fetched page is third-party text: the preview and the misuse check when the draft is saved guard against it, and REST saves it right away without preview. REST POST /v1/account/cancellation-request with a body of {reason, note?} (reason is one of too_expensive, callers_hang_up, missing_feature, not_needed, other; note at most 500 characters) and the MCP tool request_account_cancellation call lib/service/account-cancellation.ts, the same service as the form in Settings. Response {cancellationRequest: {reason, note, requestedAt, alreadyRequested}}; a repeated request returns the original record with alreadyRequested: true (HTTP 200) and sends no further e-mail. There is at most one request per account, it changes the account in no way and deletes nothing; the volai owner gets an alert with the reason and the customer a confirmation in the account language. Errors: validation, user_not_found. When you click thumbs down in the call e-mail, the rating is saved right away and on the page that opens you can pick a reason and add a note in a single form. Before, there were only five separate buttons and no note. When you write to podpora@volai.cz, you get an automatic confirmation that the message arrived, saying that we usually reply within one business day, with a link to the status page. At volai.cz/en/trust (in Czech volai.cz/duvera) you find in one place where the data of calls, SMS and your account lies, who touches it, how long we keep it, how we protect it and what we cannot do yet. The website gains a Call from your browser button that lets you try the volai demo agent with a call right from your browser, without signing up. The call is a demo, it is recorded and the agent speaks Czech. We are switching it on gradually, so it may appear only after a while. public/llms.txt, public/SKILL.md, /docs/api and /docs/mcp (cs and en) match the code: create_calendar_event creates an appointment only with confirm: true and the calendar deletes nothing; the number for calls and SMS is in pilot mode (voiceSmsNumbersMode() is admin), other accounts get voice_sms_numbers_unavailable (until 3 Nov 2026; since then the mode is on and any account orders the number itself). The trial call's remainingLine states that an unanswered call also counts towards the limit of 3 calls per 24 hours.
• 1 Nov 2026 (1.49.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-11-15T23:00:00+01:00 (22:00 UTC; previously 2026-11-14T23:00:00+01:00) and PETCENTER_REMINDER_DISPATCH_END stays 2026-11-21T19:55:00+01:00 (18:55 UTC). petcenterCampaignQuotaActive() and the runPetcenterOutboundTaskTick tick therefore dial the main campaign until 15 November 22:00 UTC and coupon_reminder tasks still until 21 November 18:55 UTC. The stored quota of the campaign agent (call-quota:agent) has its own validUntil, which is moved separately via PUT /api/admin/call-quotas from 2026-11-14T22:00:00Z to 2026-11-15T22:00:00Z. The other conditions of the exception (the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, account, agent, outbound task, eight relay names) are unchanged.
• 30 Oct 2026 (1.49.0): POST /v1/tools, PATCH /v1/tools/{id} and MCP create_tool and update_tool accept an optional requireConfirmation field (boolean, default false; any other type is 400 validation). Responses that carry a tool (GET /v1/tools, GET /v1/tools/{id}, POST, PATCH, MCP list_tools) always return it as a boolean; POST /v1/tools/test does not have it. A PATCH without the field keeps the stored value (neither an older client nor a stale portal page switches the gate off), false switches it off. The engine receives require_confirmation: true only for a tool with the gate on and only for an agent on the engine in cs or sk; false is never sent explicitly. An agent in en, de or pl and an ElevenLabs agent ignore the field, and saving the tool is not refused because of language, since a tool belongs to the account and is shared by several agents. Editing a tool does not rewrite agents on the engine: the flag reaches them at the agent's next save (PATCH /v1/agents/{id}) or publish (POST /v1/agents/{id}/draft/publish). With a running campaign, re-publishing an unchanged tested draft keeps the tested mark and the task carries on, now with a gate the test did not cover; a direct PATCH /v1/agents/{id} clears the mark and the task stops with agent_version_changed. A PATCH that changes only requireConfirmation does not call ElevenLabs and does not re-verify the tool address (no DNS lookup), so the gate can be switched even while the tool's domain is unreachable. The gate reads only the caller's last utterance and does not know the agent's question: it catches an unclear consent, not every “yes” given to a different question. Portal: the tool editor (/en/agent/tools/new and /en/agent/tools/[id]) stores the choice in the same field with the switch Require the caller's clear consent; a hidden form flag distinguishes an unchecked switch from a form that did not know the switch, so a stale page cannot silently switch the gate off, and after saving a changed gate the form says that for a running agent it takes effect only after that agent is published. The method, the parameter type and source are submitted from form state and the description is a controlled field, because React 19 resets the form after every form action and the second save after an error used to send the first option of a select and the old description. GET /v1/subscription and MCP get_subscription: available says whether a NEW plan can be started right now, and it is true only when the offer is on for the account and the account has no running plan (active, past_due); otherwise it is false. It used to be true for a subscriber too, although POST /v1/subscription/checkout returned 409 subscription_exists. It is true again once the plan has ended (canceled). A client that used available to tell whether the account has a plan should read subscription instead. recommendation does not depend on available and a subscriber still receives it. PATCH /v1/subscription and MCP update_subscription: a tier the account is already switching to (nextTier) counts as done (200, not 400 invalid_tier), so the same body can be sent again after an outage in the middle and finishes what is left. Exceptions: the current tier with no scheduled change stays invalid_tier; going back to the current tier (it cancels the scheduled change) does not count as done on a repeat and ends with invalid_tier; on a plan set to end a tier alone still returns invalid_state (with cancelAtPeriodEnd: true in the body it is a repeat and goes through). invalid_state is now also listed among the errors of PATCH /v1/subscription in OpenAPI and in the documentation. GET /v1/balance and MCP get_balance: the notices subscription_exhausted_topup, subscription_cap_reached and subscription_runway carry a new optional field cancelAtPeriodEnd: true (present only when true: the plan does not renew, renewsAt is the end of the plan and no new monthly credit arrives). The format of renewsAt (epoch ms) does not change and is documented as the same moment as subscription.periodEnd (ISO 8601). The e-mails about a failed renewal and about the end of a plan have their own wording when the account has no saved card (the card is missing, nothing was charged). An outbound agent call on the engine that stayed ringing or initiated without a conversationId and was closed as failed with price 0 by the watchdog (or by the task reconcile) after two hours now behaves in a task like relay_not_routed: the attempt has items[].attempts[].countsAsAttempt: false and errorCode: "no_provider_report", uses up neither maxAttempts nor the lorela_enterprise schedule, the budget reservation is released, nothing is charged, and the contact gets nextAttemptAt no sooner than 60 seconds later. relay_not_routed and no_provider_report attempts are added together in one series: after the third uncounted attempt in a row the contact goes to review with the reviewReason of the last one, that is call:no_provider_report; earlier only when the next attempt does not fit before expiresAt or the lorela_enterprise policy allows no further attempt. A call that a late post-call completed with a conversationId was seen by the engine, so it counts as before. Items that an earlier call of this kind had already sent to review (call:failed, or call:unknown with the policy) are not reopened automatically. errorCode and reviewReason are free strings, only a new value was added; an integration that reads reports from tasks should expect one more uncounted attempt and one more review reason. A pause (POST .../pause, the batch pause for a campaign) between the dial intent being written and the provider request used to leave reviewReason: "dispatch_in_flight", the active claim, the reservation and an in_progress item with no call and no attempt; start then returned task_needs_attention, resolve returned item_not_resolvable, DELETE returned task_not_deletable and reconcile changed nothing. After such a pause the task processing now releases the intent, the claim and the reservation itself and returns task_paused (no call was placed): the contact is pending again (or failed with a free attempt) and the task is paused without a reviewReason, so the first start succeeds. The cleanup is retried up to three times on a concurrent write (revision_conflict), as is the cleanup at the last gate before the provider, whose result used to be discarded. reconcile (the cron, POST /v1/tasks/{id}/reconcile, MCP reconcile_task) additionally releases an intent that has no call record and no attempt result and whose claim and five-minute margin after it have both expired, that is at the earliest 15 minutes after the dial began (the claim lives for 10 minutes): it returns the reservation and puts the contact back to waiting, or completes it after a verified callback. A task that the expired claim had meanwhile stopped (dispatch_claim_expired) ends paused without a reason and has to be started again (start); a task the claim did not stop keeps running. An uncertain dial and a call that may have been created are left as they are. Tasks that got stuck earlier are repaired by a single reconcile and end as paused without a reason (the pause was intentional), they do not restart on their own. Response shapes do not change. POST /v1/dnc and MCP add_to_dnc accept either e164 (one number, the response { "added": true, "e164": ... } is unchanged) or the new field e164s (1 to 500 numbers, written with a single SADD command). Both fields together, neither, an empty array and more than 500 entries are 400 validation; in OpenAPI both fields are optional and the rule "exactly one of them" is enforced by validation only. An entry of e164s must be a string of at most 256 characters, any other entry fails the whole request with 400. The response to e164s carries addedCount, alreadyOnListCount, rejectedCount and rejected (entries { index, input, reason: "invalid_number" }, where input is the entry as sent, cut to 32 characters). addedCount + alreadyOnListCount + rejectedCount always equals the number of entries sent; a number repeated in the request or written in another format counts as already on the list. An entry that is not a valid number (including longer text, for example two numbers in one cell) does not fail the request, the valid entries are always added, and an input of only invalid entries is still 200, so check rejectedCount after every response. The request is idempotent (repeating it returns addedCount: 0). In OpenAPI the response of POST /v1/dnc is an anyOf of both shapes and the boolean added stays only in the single-number response. Numbers are still removed one at a time (DELETE /v1/dnc/{e164}). The destination check at dial time reads one SISMEMBER instead of the whole set, so a list with thousands of numbers no longer transfers tens of kB on every dial; the listings GET /v1/dnc and list_dnc are unchanged. REST POST /v1/tasks/{id}/items/{itemId}/resolve and MCP resolve_task_item accept reason with the value customer_purchased or, new, unsubscribed on the audited skip (action: "skip" with operationId and evidenceRef). evidenceRef is an opaque reference to the purchase or unsubscribe record, never a phone number or e-mail. Conditions are unchanged: a draft task (contact pending) or a paused task (contact pending or failed), no active claim, dial intent or reservation, and the skip does not resolve contacts in review. Attempts, costs and the do-not-call list stay as they are. The reason is part of the fingerprint (resolution.fingerprint), so repeating the same operation writes nothing and the same operationId with a different reason or evidenceRef returns 409 revision_conflict. items[].resolution.reason in every response that carries a task (GET /v1/tasks, GET /v1/tasks/{id}, POST .../resolve, MCP list_tasks, get_task, resolve_task_item) is now the enum customer_purchased | unsubscribed (a constant in OpenAPI before): a client that validates responses against the old specification must allow unsubscribed. An unknown reason in the request returns 400 validation. Descriptions in OpenAPI, MCP and the API, MCP and Tasks documentation are updated.
• 26 Oct 2026 (1.48.0): REST: GET /v1/voice-sms-numbers, POST /v1/voice-sms-numbers (no body, Idempotency-Key supported, returns 202 with the number in the awaiting_registration state), GET /v1/voice-sms-numbers/{e164}, PATCH /v1/voice-sms-numbers/{e164} (routing: agent on the in-house engine, or none), POST /v1/voice-sms-numbers/{e164}/cancel (cancelling before the registration is approved is free) and DELETE /v1/voice-sms-numbers/{e164} (releasing an active number is irreversible and the period already paid is not refunded; when the cancellation with the carrier fails, the number stays in the releasing state and the response is 502 release_failed). MCP: list_voice_sms_numbers, order_voice_sms_number (confirmedMonthlyFeeHal must be 39000, otherwise nothing is ordered), set_voice_sms_number_routing and cancel_voice_sms_number; releasing is deliberately not available over MCP. Number states: awaiting_registration, active, rejected, releasing. SMS from the number are sent with fromNumber in POST /v1/messages and send_sms (+420 recipients only, no deliveryStatus), received SMS are still read with GET /v1/messages?direction=in and the message.received webhook; calls from the number are placed by an agent (POST /v1/calls with agentId, to +420 only, one outbound call at a time); a bridge between two numbers with from and a ring from it are not available (unsupported_for_number_type). New error codes: voice_sms_numbers_unavailable, voice_sms_number_limit (at most 2 numbers per account, ordering needs a first top-up), voice_sms_order_limit, voice_sms_number_out_of_stock, unsupported_for_number_type (forward and sip are not supported for this number) and destination_not_allowed (the number can call +420 numbers only). The fee of 390 CZK per 30 days is charged as number_fee; the number_fee notice in GET /v1/balance and MCP get_balance counts these numbers too, and a debt older than 7 days releases the number just like other numbers.
• 26 Oct 2026 (1.47.0): GET /v1/account and MCP get_account return a new testCalls field next to account, with max (3), remaining (test calls left in the current window) and resetAt (when the window ends, epoch ms; the window runs 24 hours from the first attempt; null when there was no attempt in the last 24 hours). POST /v1/agents/{id}/test-call and MCP test_call carry the same field right after dialing. Every dialed attempt counts, including an unanswered one, which is not charged; an attempt that never dialed (agent, credit or capacity error) does not count. The field is additive, existing response shapes do not change. PATCH /v1/account does not return it.
• 23 Oct 2026 (1.46.1): POST /v1/tasks/{id}/reconcile, MCP reconcile_task and the task cron settle a task after recovery by the work that is left: paused while any contact is waiting for another attempt (pending, failed, in_progress), even if other contacts are in review; needs_attention only when nothing is left to dial but a contact in review (the task's reviewReason is the reason of the first such item); completed when nothing is left. reviewReason is set only for needs_attention and empty otherwise; after a pause in the middle of a dial and after an expired claim activeItemId, activeClaimToken and activeClaimUntil are released as well. It applies to four recoveries: after a pause in the middle of a dial (dispatch_in_flight), after an expired claim (dispatch_claim_expired), after a call with a previously unknown price is settled (billing_unknown) and after an uncertain dial is resolved (dial:*). Before, recovery put review before work, so pausing a running task sent a task with hundreds of waiting contacts to needs_attention, which start and PATCH (task_not_editable) refused. An uncertain dial for which no call can be found keeps the task in needs_attention (the contact holds an unresolved dial intent and start would refuse it) until POST .../items/{itemId}/resolve decides that contact; the same applies after a call with an unknown price is settled (billing_unknown) while another contact holds an unresolved dial intent. A running task and task-level reasons (for example variables_limit) are not changed by reconcile. With the retryPolicy: "lorela_enterprise" policy the state of a contact after the last allowed attempt (maxAttempts) changes too: a no_answer, missed, busy, completed voicemail without a human or an answered call in which the person said nothing closes it as skipped with reviewReason: "retry_policy_exhausted", like retry_age_expired when the horizon runs out (before: review); the link to the last call (providerCallId) stays. An uncertain result of the last attempt stays in review with the same reason, and the policy still rejects a manual resolve with retry. A verified human callback after this closing turns the contact into completed (after retry_age_expired and task_expired it stays skipped with callbackContactCallId). Tasks without the policy do not change. POST .../items/{itemId}/resolve does not change: the last resolved item in review turns a task with work left into paused. Tasks that got stuck in needs_attention before the rollout do not repair themselves (their reason is derived from an item): resolve with skip over the items in review frees them once.
• 23 Oct 2026 (1.46.0): POST /v1/tasks, PATCH /v1/tasks/{id}, MCP create_task and update_task accept optional retryMaxAgeDays: a whole number 1 to 30, the retry horizon of the retryPolicy: "lorela_enterprise" policy in days from the recipient's first counted attempt. The public task (GET /v1/tasks, GET /v1/tasks/{id}, the create and PATCH responses, MCP get_task and list_tasks) returns it only when it was set; an absent field means the default 5 days as before, so tasks without the field behave unchanged. The field needs the policy (in the same body at creation, in the body or already stored on the task on PATCH), otherwise validation is returned with the field retryMaxAgeDays; so is a value outside 1 to 30 or a non-integer. Omitting it on PATCH preserves the value. Unlike retryPolicy, it can be changed after attempts have started, in the states PATCH has always accepted (running and completed still not: task_not_editable). Raising the value on a paused task returns items that are skipped with reviewReason: "retry_age_expired" to pending with a new nextAttemptAt when they have a counted attempt, a free attempt below maxAttempts, no verified callback and their first counted attempt + the new horizon (and expiresAt, when set) is in the future; lowering it reopens nothing and contacts outside the new horizon stay skipped. The attempt ladder (8 minutes after the first, the 08:00-09:00 and 17:00-19:00 windows, four attempts) does not change, only the horizon does. Portal: the task detail of a task with the policy shows a line about the retry schedule and horizon, the calling rules have a Retry horizon (days) field and offer four attempts for a task with the policy. OpenAPI, the MCP tool descriptions, SKILL.md and the Tasks guide are updated.
• 23 Oct 2026 (1.45.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-11-14T23:00:00+01:00 (22:00 UTC; previously 2026-10-31T23:00:00Z) and PETCENTER_REMINDER_DISPATCH_END is 2026-11-21T19:55:00+01:00 (18:55 UTC; previously 5 November). petcenterCampaignQuotaActive() and the runPetcenterOutboundTaskTick tick therefore dial the main campaign until 14 November 22:00 UTC and coupon_reminder tasks until 21 November 18:55 UTC. The stored quota of the campaign agent (call-quota:agent) has its own validUntil and is moved separately via PUT /api/admin/call-quotas. The other conditions of the exception (the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, account, agent, outbound task, eight relay names) are unchanged.
• 23 Oct 2026 (1.45.0): The number's relay names are set up in the background right after purchase (POST /v1/numbers, buy_number, portal) and after an order is fulfilled (POST /v1/numbers/orders, order_number_from_region), whatever the number's routing. A lease (POST /v1/relay, create_relay_lease), an agent call or a transfer from a number that does not have them yet triggers the setup again. The create_relay_lease description spells out a rule that already applied: a lease connects exactly one call, dialing the same sipName again is rejected with SIP 603, so create a new lease before every attempt and turn off automatic redialing in your platform. Response shapes are unchanged.
• 22 Oct 2026 (1.43.0): New agent field recordingNotice (boolean) in POST/PATCH /v1/agents, MCP create_agent/update_agent and agent drafts (PUT /v1/agents/{id}/draft, save_agent_draft). The response always carries it (false when unset). The sentence is appended only with recordingNotice: true and recordCalls on; in a draft an absent key means unchanged. The greeting length estimate (first_message_too_long) counts the sentence only when it is on. This changes what recordCalls implies: recording alone no longer adds the sentence. It was removed on 22 Oct 2026 from existing agents that had it added automatically; a sentence written into firstMessage itself stays as it is.
• 22 Oct 2026 (1.42.3): An attempt's reservation (reservedBudgetHal, the item's estimatedCostHal) is the call leg plus the agent leg, each rounded up to a heller exactly as billing does (previously a single rounding of the combined rate, which came out one heller lower for some caps). A call with a duration cap (outbound task) is billed for min(durationSecs, maxDurationSecs); the stored durationSecs stays as measured. A transferred leg of such a call gets at most the remainder up to the attempt's highest price. An agent with recordCalls: false on volai's engine (provider: "engine") has no recording: hasRecording is false and GET /v1/calls/{id}/recording returns no_recording. Saving such an agent requires an engine that knows the flag; otherwise the engine write fails instead of recording silently.
• 21 Oct 2026 (1.42.2): checkCallRateLimit (POST /v1/calls, MCP make_call, outbound tasks) counts the attempts per 24 hours of a call covered by an agent's stored quota (call-quota:agent:{agentId}) or by the PetCenter campaign exception with a daily limit above 1,000 in its own counter ratelimit:callsday-agent:{userId}:{agentId} and compares them with the quota's daily limit. Calls with the default limits, calls without an agent (the website test call, bridge, relay) and calls with a quota that does not raise the daily limit (1,000 or less) still share the account counter ratelimit:callsday:{userId}; a call of the same agent outside the quota's scope (outboundTaskOnly, taskPurposes, after validUntil) follows the campaign exception when it applies, and otherwise uses the default limit of 1,000 and the account counter. The concurrency slots agentcallslot:{userId} (relay_lease_limit) and the per-minute counter ratelimit:calls:{userId} stay shared per account. The code rate_limited, HTTP status 429, the message texts and the default limits of 2 concurrent, 10 per minute and 1,000 per 24 hours do not change; only an admin stores a quota. resolveAgentCallLimitsWithSource in lib/service/call-quotas.ts returns the source of the limits (stored, campaign, default) next to them from a single quota read, and usesAgentDailyCounter picks the counter from them.
• 18 Oct 2026 (1.42.1): An inbound call that the voice engine turned away because the cap on concurrent calls was used up now has status: "missed", endReason: "capacity", durationSecs: 0 and priceHal: 0 in REST (GET /v1/calls, GET /v1/calls/{id}) and MCP (list_calls, get_call); no credit is charged. The call.missed webhook is sent once per call, and an SMS to the caller only for an agent with missedCallSms turned on (as for every missed inbound call); no summary e-mail is sent for it. When the carrier reported the unanswered call first, call.missed is sent at that moment (possibly without endReason) and the existing record is then completed with endReason: "capacity"; no second record and no second webhook are created. Until now such a call stayed in status: "in_progress" forever, because the engine sends no post-call for it. The record is now created by the reconciliation of engine calls, within a few minutes of the rejection. Existing stuck records from the last seven days that are older than two hours are closed retroactively by the hourly check, only with evidence from the engine's call log and without a webhook; if the carrier created its own record for them, they are merged into it. The values missed and capacity already existed in the enumerations, and the response shapes do not change. In the outcome filter (GET /v1/calls, list_calls) such a call counts as no_answer; for an outbound call nothing changes about capacity (relay pool full).
• 18 Oct 2026 (1.42.0): GET /v1/subscription and MCP get_subscription: recommendation has a new field steady, whether the spend is not just a one-off peak: usage over the last 14 Prague days scaled to 30 days, plus the monthly number fees of the 30-day window counted once, reaches at least the price of the recommended tier. The portal offers the plan personally and the MCP sentence suggests it only when worthIt and steady are both true; worthIt and the other fields do not change. The recommendation comes from one function for the portal, REST and MCP; for REST and MCP it is cached next to the credit runway (10 minutes, cleared by every credit movement). Nothing else in the API changes.
• 18 Oct 2026 (1.41.0): GET /v1/subscription and MCP get_subscription: new field previousPeriod, a summary of the paid period before the current one (subscription.periodStart) with the same figures as the renewal e-mail: tier, periodStart and periodEnd (ISO 8601), creditHal, usedHal, usedPercent (rounded down), overHal (spending beyond the monthly credit; with top-ups without debt that the next credit paid off, with the cap including debt; null when the credit history cannot prove it), expiredHal, exhaustionMode and exhaustedAt (ISO 8601, null when the credit did not run out or the history cannot show when). It is saved at every renewal, by card (also when the payment_intent.succeeded webhook completes it) or by a manual payment, and kept for 45 days; it is returned only while the plan is active, whatever available says, and is null without a plan, with status past_due or canceled, in the first period and when the usage cannot be proven. MCP get_subscription also adds a sentence about the last period with Prague dates. GET /v1/balance and MCP get_balance: on an active plan the notice {kind:"subscription_runway",renewsAt,runsOutAt} now computes runsOutAt from the plan's cautious pace, the same as the outlook on the plan card in the portal: the highest of the 28-day average (with a complete credit history), the average usage over the last 7 Prague days without number fees and the average since the current period started (after its first week), instead of the 28-day average. The shape and conditions of the notice do not change (nothing while auto top-up is on) and runway.dailyAverageHal and runway.runwayDays stay the 28-day average. The renewal e-mail for a renewal that the webhook completes now also leaves out the advice when a tier change is scheduled. Nothing else in the API changes.
• 18 Oct 2026 (1.40.1): POST /v1/outbound/dispatch-scopes/petcenter/registrations decoded the result of its Lua script with JSON.parse even when the default Upstash client (redis() with automatic deserialization; only redisRaw() has none) already returns it as an object. Every request therefore ended with the exception SyntaxError: "[object Object]" is not valid JSON and a 500 response. The exception happened after the script had run and before the result was mapped, so a newly stored registration (or a replay of the same operation) showed up as a 500 to the client, and a Lua refusal never reached it as 409 revision_conflict (operation_conflict, manifest_cas_conflict, task_changed_during_registration with error.details), 404 not_found or 400 validation. registerPetcenterDispatchScope now decodes the result with the helper decodeLuaJsonObject: JSON.parse only over a real string, and an object passes unchanged. A script reply that is not an object (valid JSON of another shape, or text that is not JSON) throws and the route answers 500, because the script may already have written the change and the outcome is uncertain; the client then asks for the operation result with GET /v1/outbound/dispatch-scopes/petcenter/registrations?operationId=.... An empty result still ends in registration_failed. The batch pause decodes its results with the same helper and its behavior and error message do not change. The contract does not change: request and response shapes, idempotency by operationId (replayed: true on a repeat), expectedManifestSha, the status codes and the providerActionStarted flag. The only client-visible difference is that the former 500 responses are now 200, 409, 404 or 400 according to the script result; 500 remains only for an unexpected shape of its reply.
• 18 Oct 2026 (1.40.0): GET /v1/subscription and MCP get_subscription: new field recommendation, or null (no plan offer for the account, or less than 30 Prague days of credit history). It holds spendHal (spend over the last 30 Prague days on calls, the agent, numbers and SMS, minus SMS refunds), days (30), cheapestPath (per_second or plan), tier and tierTotalHal (the cheapest tier with top-ups and its cost at that spend), savingsHal, worthIt (a saving of at least 50 CZK and 5%, the same threshold as the portal) and options (every way to pay for the same spend: {path, tier, totalHal} for paying by the second and for each tier). For a subscriber MCP get_subscription also adds a sentence with advice under the same rule as the portal and the e-mail. Nothing else in the API changes.
• 18 Oct 2026 (1.39.1): PUT /api/admin/call-quotas loads the agent (getAgent) and refuses the write when the agent does not exist or is deleted (404 agent_not_found), or when userId in the body is not the agent's owner (400 validation, the message does not reveal the real owner). A refused write stores nothing in call-quota:agent:{agentId}, in the index call-quota:index or in user:{userId}:admin-log. userId stays required in the body so the stored shape from GET can be sent back. The relay_lease_limit message when placing an agent call (POST /v1/calls, MCP make_call, outbound tasks) now reads This agent can have at most 3 running calls at once, and that many are already running on your account. Try again in a moment. (Czech: Tento agent může mít najednou nejvýš 3 běžící hovory a tolik jich teď na tvém účtu už běží. Zkus to za chvíli znovu.; the Czech noun and adjective agree with the count: 1 reads běžící hovor, 2 to 4 běžící hovory, 5 or more běžících hovorů). The number is the threshold of the calling agent from resolveAgentCallLimits (a stored quota, otherwise the default 2, after the pool clamp); the running calls come from the account-wide counter agentcallslot:{userId}, so a slot may be held by another agent of the same account. Before, the message said the maximum was per account although the agent decides the threshold, and the Czech text used the same plural form for every count. The code relay_lease_limit, the HTTP status 400, the counter, the threshold and the way outbound tasks wait on this code do not change. The history table heading on the customer detail page in the admin is now Admin action history (Historie admin akcí), the rows do not change.
• 18 Oct 2026 (1.39.0): New admin endpoint GET/PUT/DELETE /api/admin/call-quotas (admin session, not an API key; writes check the Origin) stores an agent's quota in call-quota:agent:{agentId}: concurrent 1 to 30, perMinute 1 to 60, daily 1 to 20,000, a mandatory note, outboundTaskOnly and the optional taskPurposes (standard, coupon_reminder) and validUntil (milliseconds since the epoch). Every change is written to user:{userId}:admin-log as call_quota_set or call_quota_deleted. resolveAgentCallLimits in lib/service/call-quotas.ts applies it ahead of the PetCenter exception and the default { concurrent: 2, daily: 1000, perMinute: 10 }, only for the same account, an outbound task (when outboundTaskOnly is set), an allowed purpose and a time before validUntil. Concurrency is clamped to min(stored, max(2, number of distinct names in ODORIK_RELAY_NAMES - 2)), the per-minute and daily limits are not. Without a stored quota behaviour is unchanged. Placing a call on a relay name waits for its turn (one shared pointer in Redis, spacing RELAY_PLACEMENT_GAP_MS 3 s, at most RELAY_PLACEMENT_MAX_WAIT_MS 10 s; on a Redis outage the call is placed at once and relay placement spacing unavailable is logged): agent calls (POST /v1/calls, MCP, tasks) and trial calls on the engine and on ElevenLabs, the transfer bridge claim for at most 4 s; not the BYO relay lease (POST /v1/relay) and not callback calls without a relay name. POST /v1/calls and a trial call can therefore take up to 10 s longer during a burst of calls; maxDuration is 100 s for POST /v1/calls and 70 s for POST /v1/agents/{id}/test-call. The outbound task tick starts no further task after TICK_DISPATCH_BUDGET_MS (90 s), the rest waits for the next run. An engine rejection because of the concurrent-call cap carries Retry-After: 30, which volai already forwards (retryAfterSecs, the Retry-After header, items[].nextAttemptAt): once the engine with this cap is deployed, contacts wait 30 s instead of 5 minutes; an engine without the header still means 300 s.
• 18 Oct 2026 (1.38.3): No change in API behaviour. The plan offer is on for every account (PAUSAL_MODE=on), so GET /v1/subscription returns available: true; pausal_unavailable (404) remains for when the offer is switched off. The documentation (/en/docs/credit, SKILL.md, llms.txt) no longer says the plan is limited to some accounts and describes renewals as hourly.
• 18 Oct 2026 (1.38.2): agentCallLimits in lib/service/call-quotas.ts keeps returning { concurrent: 6, daily: 6000, perMinute: 15 } after CAMPAIGN_QUOTA_EXPIRES_AT (2026-10-31T23:00:00Z) when the quota context carries the new optional taskPurpose: "coupon_reminder" and petcenterReminderQuotaActive() holds, that is, the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch is on and the time is before PETCENTER_REMINDER_DISPATCH_END (2026-11-05T19:55:00+01:00, 18:55 UTC; the constant moved into call-quotas.ts and the dispatch tick reads it from there). makeAgentCall passes the purpose to the quota only after it has verified the link to an approved reminder. A call without a purpose gets the default { concurrent: 2, daily: 1000, perMinute: 10 } after 31 October. The other conditions (the exact account, agent and internal outbound-task context match and at least eight distinct ODORIK_RELAY_NAMES) apply to reminders as well; the main campaign still dials nothing after 31 October, petcenterCampaignQuotaActive and the tick logic are unchanged. API behaviour for other accounts is unchanged.
• 18 Oct 2026 (1.38.1): GET /v1/balance and MCP get_balance: an eighth notice shape {kind:"subscription_runway",renewsAt,runsOutAt} (at the recent pace the balance runs out before the renewal; returned to subscribers instead of {kind:"runway"}, nothing while auto top-up is on). POST /v1/subscription/checkout and MCP create_subscription_link: consumerConsent is ignored for an account with a company ID, VAT ID or company name (Stripe metadata get 0); a consumer without a company ID still gets a confirmUrl. Nothing else in the API changes.
• 17 Oct 2026 (1.38.0): New REST endpoints: GET /v1/subscription (response {subscription, tiers, topupBalanceHal, available}; subscription is null without a plan, tiers lists {id, priceHal, creditHal} in hellers excluding VAT, available says whether a plan can be started on the account), POST /v1/subscription/checkout (body {tier, exhaustionMode, consumerConsent?} where tier is "490", "990" or "1990" and exhaustionMode is topup or cap with no default; returns {checkoutUrl}, nothing is charged until a person pays in Checkout; an account without a company ID must send consumerConsent), PATCH /v1/subscription (body {tier?, cancelAtPeriodEnd?, exhaustionMode?}), POST /v1/subscription/pay (a Checkout link to pay a failed renewal by hand, only in status past_due, otherwise invalid_state) and POST /v1/subscription/card (a Checkout link in setup mode to replace the saved card, nothing is charged); the POST endpoints accept Idempotency-Key. PATCH applies a lower tier (from the next period), cancelAtPeriodEnd: true and exhaustionMode: "cap" at once and returns {subscription}; a higher tier, cancelAtPeriodEnd: false (resuming a plan set to end) and exhaustionMode: "topup" change nothing and return 409 subscription_confirmation_required with a confirmUrl (single use, valid for 24 hours) that a person must open and confirm in the portal. The subscription object carries tier, status (active, past_due or canceled), periodStart and periodEnd as ISO 8601 strings (unlike ts in the ledger, which is epoch milliseconds), monthlyCreditHal, monthlyRemainingHal, exhaustionMode, cancelAtPeriodEnd, nextTier and card (brand, last4). GET /v1/balance and the MCP tool get_balance now also carry subscription (null without a plan) and topupBalanceHal (top-up credit alone, negative when the account is in debt); balanceHal is still the total of both. The ledger (GET /v1/credit/ledger, MCP list_ledger) has two new type values, subscription_grant and subscription_expire; a ledger entry for a charge covered by the monthly credit also carries fromSubscriptionHal (the part the monthly credit paid), other entries do not have the field. Five new MCP tools: get_subscription, create_subscription_link, update_subscription, cancel_subscription and create_subscription_payment_link; replacing the card stays REST and portal only. New error codes: 402 subscription_cap_reached (returned instead of insufficient_credit by calls, test calls, gate rings, SMS and purchases of numbers, SMS numbers and relay leases when the plan runs with exhaustionMode: "cap", the monthly credit is used up and the remaining credit does not cover the action), 409 subscription_exists, 404 subscription_missing, 409 subscription_canceled, 409 subscription_confirmation_required, 400 consumer_consent_required, 404 pausal_unavailable (the offer is not enabled for the account), 400 invalid_tier and 409 subscription_cap_active (auto top-up cannot be turned on while the plan runs with the cap); the confirmation page in the portal (not REST) can also end in the state confirm_invalid, confirm_expired or confirm_used. Once the offer is on for an account, the portal shows a plan card on the Credit page and pages to start or change the plan and to confirm a confirmUrl link. Accounts without a plan see no change in existing fields, statuses or codes.
• 16 Oct 2026 (1.37.5): The engine sends rationale and reason as null in every item of analysis.evaluation_criteria_results when they have no value. The post-call webhook schema rejected null and dropped the evaluation of all criteria, so goal in GET /v1/calls, GET /v1/calls/{id} and in the MCP tools list_calls and get_call was null for calls on the engine, the goal filter counted them as not_evaluated and the after-call e-mail had no goal line. The schema now treats null as a missing field for every optional field where null means nothing, and a malformed evaluation item drops only itself. Where null carries meaning (for example recording_url: null = a call without a recording), it stays. No field or endpoint changes. Calls from 16 September to 16 October 2026 do not have an evaluation yet.
• 15 Oct 2026 (1.37.4): Three new agent fields turnDigitTailFloorMs, turnLongSpeechFloorMs (integer, 0 = off, otherwise 400 to 2300 ms; the gap 1 to 399 returns validation) and turnLongSpeechSecs (1 to 30, decimals allowed) on POST /v1/agents, PATCH /v1/agents/{id} (a number sets it, null removes the stored value, an omitted key leaves it unchanged), GET /v1/agents and GET /v1/agents/{id} (always present, a number or null when not set, the engine uses its defaults 0 / 0 / 5), in the draft snapshot (PUT/GET /v1/agents/{id}/draft; an absent key means unchanged, null removes it) and in the MCP tools create_agent/update_agent/save_agent_draft. They are sent to the engine in the turn block as digit_tail_floor_ms, long_speech_floor_ms and long_speech_secs on EVERY save of the agent (the engine does not carry the fields over from the previous version; a missing value goes as the engine default) and the read-back compares them (engine contract ch. 3.5af and 3.5ag). Stored for either provider, read only on the engine in smart_turn mode; ElevenLabs ignores them. Engine guidance: step 1 = 800 for Czech agents that take dictated numbers, step 2 = 1200, practical ceiling 1500; dates, postcodes and years get the floor too. The counters of applied floors stay in the engine (its dump and GET /v1/calls), they are not in volai webhooks. In the portal, the "End of reply" card in the Advanced tab.
• 15 Oct 2026 (1.37.3): New agent field sttLanguageHintsStrict: boolean on POST /v1/agents, PATCH /v1/agents/{id} (true turns it on, false or null turns it off, an omitted key leaves it unchanged), GET /v1/agents and GET /v1/agents/{id} (always a boolean, false when not set), in the draft snapshot (PUT/GET /v1/agents/{id}/draft; an absent key means unchanged, null turns it off) and in the MCP tools create_agent/update_agent/save_agent_draft. It is sent to the engine as stt.language_hints_strict on EVERY save of the agent (the engine does not carry the field over from the previous version) and the read-back compares it. Stored for either provider, read only by the engine (Soniox); best effort, only for engine agents with language cs and outbound calls, never for sk. The call detail GET /v1/calls/{id}, MCP get_call and the call.completed webhook (and call.failed with endReason: "engine_error") carry a new engine: { protectedUtterances: [{ timeInCallSecs?, atSecs, message, words, reason }], protectedUtterancesCount } block - utterances of the person who answered that the engine dropped during the greeting window (metadata.engine.protected_utterances from the engine post-call, contract ch. 3.5ae): not in the transcript, the agent did not react to them; reason is first_message_protect, greeting_courtesy or greeting_identification (open list), at most 10 items, message up to 200 characters, the count covers them all. The block is present only on engine calls from the 15 Oct 2026 build on ([] and 0 when nothing was dropped); older calls, the GET /v1/calls list and agents on ElevenLabs do not have it. In the portal a switch on the Advanced tab and a "What the person said during the greeting" card in the call detail.
• 15 Oct 2026 (1.37.2): cdr-sync: the second leg of an answered ring (same from/to, different active_call_id, starting shortly after the first leg, first leg answered) is matched to the same kind: "ring" record without the per-attempt fee; seconds are billed only when length > 0. The ring.rangSecs description in OpenAPI and the docs: the carrier's figure is usually 1 to 3 s above ringSecs. No field or endpoint changes.
• 15 Oct 2026 (1.37.1): New optional agent field inboundVariables: Record<string, string> on POST /v1/agents, PATCH /v1/agents/{id}, GET /v1/agents and GET /v1/agents/{id}, in the draft snapshot (PUT /v1/agents/{id}/draft, GET .../draft) and in the MCP tools create_agent/update_agent/save_agent_draft: default values for {{variable}} placeholders on INBOUND calls. The initiation webhook merges them into dynamic_variables only for names the call does not supply itself (caller_number, called_number, attempt_id, volai_*, trial_* and system__* take precedence and validation rejects such names); outbound calls (POST /v1/calls, relay, tasks) do not use them. At most 10 keys matching [A-Za-z0-9_]{1,40}, values are trimmed strings up to 200 characters. On PATCH an object replaces the stored values entirely, null or {} removes them and an omitted key leaves them unchanged; the response omits the key when the agent has none. In a draft an absent key means unchanged. The prompt_variables_unavailable_inbound and first_message_empty warnings skip a variable that has a default. Works for either provider - the engine and ElevenLabs read the same webhook.
• 15 Oct 2026 (1.37.0): New POST /v1/rings with body {to, from?, ringSecs?} (from = your active volai number, defaults to the first number of the account; ringSecs 3 to 30, default 10) replies right after the carrier accepts the order with {id, status: "initiated", kind: "ring", from, to, requestedSecs, priceHal}. The result arrives by webhook (call.no_answer for rang and ended_early, call.completed for answered) and in GET /v1/calls/{id} (also with ?waitSecs=) in the new ring: {requestedSecs, outcome, rangSecs} block; outcome is rang, ended_early, answered or unknown. kind has the new value ring; the body of every call webhook now carries kind and, for rings, the ring block. MCP tool ring_number takes the same fields. Limits: 30 rings per minute and 500 per day per account, 120 per hour per target; the manual do-not-call list applies, the automatic 30-day block is neither applied nor fed. Idempotency-Key is supported. New error code: ring_needs_number (account without an active number).
• 13 Oct 2026 (1.36.2): PATCH /v1/numbers/{e164} and MCP set_number_routing return validation when routing.mode is sip, sipUri points at <credentialId>.sip.vapi.ai or <credentialId>.sip.eu.vapi.ai, and sipUsername with sipPassword are sent or stored from before. A Vapi BYO trunk recognises our calls by the IP in its gateways (IP 81.31.45.0, netmask 24) and does not connect authenticated routing. Vapi's native SIP numbers (sip:<name>@sip.vapi.ai) are not affected. A number that already has such routing stored is fixed by sending both fields as empty strings. The set_number_routing description and the /en/integrations/vapi, /en/docs/bring-your-own-agent and /en/docs/sip pages say so; for a failed call to a Vapi BYO trunk, the portal points at the login fields, the gateways and the region.
• 13 Oct 2026 (1.36.1): An outbound agent call through the relay whose route never reached the carrier (the routing webhook did not answer within five seconds) still has status: "no_answer", but now endReason: "rejected" instead of "no_answer", and it does not count towards the automatic destination block (3 failures in 24 hours). In tasks such an attempt has countsAsAttempt: false and errorCode: "relay_not_routed", uses up neither maxAttempts nor the lorela_enterprise schedule, and the contact gets nextAttemptAt no sooner than 60 seconds later. After the third such attempt in a row the contact goes to review with reviewReason: "call:relay_not_routed".
• 12 Oct 2026 (1.36.0): The new internal POST /v1/outbound/dispatch-scopes/petcenter/registrations accepts a durable operationId, manifest SHA-256 and ordered task IDs. The first manifest is pinned to the approved 19-task list; later manifests can only append. GET returns registration state and operation readback. The new /api/cron/outbound-tasks/petcenter cron uses a separately and fairly rotated queue; the general cron and atomic claim both enforce separation. Limits of 6 concurrent calls, 15 attempts per minute and 6,000 per day remain unchanged. GET /v1/tasks?ids=id1,id2 reads one to five selected tasks owned by the authenticated account, reports subset completeness and rejects responses over 4 MiB. POST /v1/outbound/dispatch-scopes/petcenter/pauses safely pauses up to five registered tasks with revision checks; GET returns durable outcomes and an input hash for safe reconciliation.
• 11 Oct 2026 (1.35.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take two new fields: firstMessageProtectSecs: number | null (0 to 20 seconds, decimals allowed, outbound calls only; while the first line plays, a short reaction from the person who answered does not interrupt it: a reply without an interrupting word (for example stop, no, wait) is dropped in the protected window, so it does not interrupt the line, is not in the transcript and the agent does not react to it, while an interrupting word always interrupts it; the interrupting words follow the agent's language, so an English agent is interrupted by stop, no, wait or hold; null or 0 turns the protection off) and silencePromptText: string | null (your own silence reminder sentence, up to 80 characters, spoken word for word instead of the default reminder for the agent's language ("Are you still there?" in English); an empty string or null restores the default text). Unlike silencePromptSecs, WITHOUT a forced default: a missing field on POST is not stored, GET /v1/agents returns it as null for an older agent, and a PATCH without the key leaves the stored value alone, so nothing changes for existing agents. Both fields are accepted and stored for EITHER provider, but only heard on an agent running on volai's own engine. A value outside the bounds fails with the generic validation error (validation, 400), no new code. A transcript turn (transcript[] in GET /v1/calls/{id}, MCP get_call and the call.completed webhook) carries an optional interrupted: true on an agent line the caller interrupted, with message still the full planned text; it is absent on calls handled by ElevenLabs and on calls without an interruption.
• 10 Oct 2026 (1.34.5): GET and POST /v1/sms-numbers and the MCP tools list_sms_numbers and buy_sms_number return dailySendLimit for each SMS number (20 SMS per 24-hour window during the number's first 30 days, 50 after that), dailySendRemaining (0 for a number being released) and dailySendResetsAt (Unix ms when the window ends, null when none is running). The window starts with the first SMS from any SMS number of the account, is shared by all of them and also counts attempts over the limit and SMS the carrier rejected. The message.sent webhook body has a new smsNumber field: the E.164 SMS number for a message sent from an SMS number, null for the shared sender SMSinfo. The internal_error and send_failed_operator messages for SMS now say "The error is on our side and we know about it", sms_number_out_of_stock no longer promises a restock and the rate_limited message for a used-up SMS number limit says how long until the window ends; error codes do not change. In the portal the /en/messages form shows the limit of the selected SMS number and the SMS messages card on the overview also counts received SMS.
• 10 Oct 2026 (1.34.4): agentCallLimits in lib/service/call-quotas.ts returns { concurrent: 6, daily: 6000, perMinute: 15 } for the campaign scope; the condition of at least eight distinct ODORIK_RELAY_NAMES stays and guarantees two free names for other callers. The account default (2, 1000, 10), the enablement conditions and the shared account counters are unchanged; API behaviour for other accounts is unchanged.
• 10 Oct 2026 (1.34.3): The action for send_unknown no longer says that unknown is always final: for an SMS sent from an SMS number it can still change on its own to sent with a deliveryStatus, or to failed with the credit refunded; for an SMS from the shared sender SMSinfo it stays final. The action for rate_limited no longer promises a Retry-After header in every case: the daily cap for sending from an SMS number (20 SMS a day per account during the first 30 days after buying the number, 50 after that) resets the next day, and a number purchase already running finishes within seconds. POST /v1/messages lists blocked_destination (400, premium-rate numbers) among its errors. Messages received on an SMS number have source: "inbound", the received-message list holds at most the 1,000 newest messages per account, and the message.received webhook is not sent above 300 received messages per hour on one number (the messages are still stored). In message.received, from is an E.164 number or a text sender name (at most 32 characters); a message that was not picked up at once is added by a periodic check within about 15 minutes and its event then arrives late. Neither the delivery report (deliveryStatus) nor a late failed triggers an event; read them from GET /v1/messages/{id}. Releasing an SMS number is not available over MCP, only in the portal and with DELETE /v1/sms-numbers/{e164}.
• 9 Oct 2026 (1.34.2): agentCallLimits in lib/service/call-quotas.ts returns { concurrent: 8, daily: 6000, perMinute: 15 } for the campaign scope; the account default (2, 1000, 10), the enablement conditions and the shared account counters are unchanged. The rate_limited message for the daily limit now says 6000.
• 9 Oct 2026 (1.34.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-10-31T23:00:00Z; the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, the exact account, agent and internal outbound-task context match and at least eight distinct ODORIK_RELAY_NAMES still apply. API behaviour for other accounts is unchanged.
• 9 Oct 2026 (1.34.0): New endpoints GET /v1/sms-numbers, POST /v1/sms-numbers (no body, Idempotency-Key supported, returns 201) and DELETE /v1/sms-numbers/{e164} (irreversible, the paid period is not refunded), and MCP tools list_sms_numbers and buy_sms_number (confirmedMonthlyFeeHal must equal the current fee in hellers, otherwise nothing is bought). GET /v1/messages and MCP list_messages take direction (out by default, in, all) and also return messages received on an SMS number; messages now carry direction, smsNumber and deliveryStatus (delivered or undelivered, only for SMS sent from a number), status has a new value received and failReason a new value opted_out. POST /v1/messages and MCP send_sms take fromNumber (an active SMS number of the account; Czech +420 recipients only; 1.90 CZK per segment). New webhook event message.received with {id, from, to, body, segments, receivedAt} (receivedAt is Unix ms); the text of a received SMS is untrusted third-party content and MCP marks it with securityNotice. Received SMS are kept for 90 days. New error codes: sms_numbers_unavailable, sms_number_limit, sms_number_out_of_stock, invalid_from_number, from_number_unsupported_destination and recipient_opted_out; the existing codes recipient_rejected, sms_gateway_failed, recipient_is_virtual_number (an SMS from the shared sender to a volai SMS number) and release_failed also apply to SMS numbers. The message from field is still the internal label volai for a message sent without fromNumber, the SMS number itself for one sent from it, and the sender for a received message.
• 8 Oct 2026 (1.33.0): The callback-routing policy accepts an optional missedFirstMessage (up to 500 characters): it replaces firstMessage when the verified preceding outbound call had no conversation with the customer (not answered, voicemail, voice menu, nobody spoke, or the call is not closed yet). Initiation sends the engine volai_callback_kind (missed/contacted) next to volai_call_mode=campaign_callback. The engine post-call may carry caller_optout_requested (outbound calls only): the call then exposes optOutRequested: true in the list and detail, the called number is added to the account's do-not-call list (GET /v1/dnc) and the lorela_enterprise policy schedules no further attempt for that item. An engine call with answered_by: unknown stays unknown - the portal no longer guesses a voicemail from a short reply ("Yes." after the intro), so hasConversation of such a call follows the transcript; a voicemail detected by the engine (voicemailReason present) gets another attempt under the lorela_enterprise policy despite the carrier greeting in the transcript. New reason voicemailReason: digits (a carrier greeting reading the called number digit by digit). Everything is additive; existing policies, calls and tasks are unchanged.
• 8 Oct 2026 (1.32.1): The message from field stays the internal label volai, and OpenAPI now describes it; the source field description says the value inbound never occurs for messages. The MCP server instructions, SKILL.md and the llms files say the same. API behaviour is unchanged.
• 8 Oct 2026 (1.32.0): Save an explicit allowlist of owned active engine agents for returning callers with a unique real outbound call from this number within lookbackSecs (60-604800 seconds). Unknown, ambiguous or unverified callers keep the default agent. Empty agentIds disables the policy. Optional firstMessage applies only to verified callbacks. engineSyncRequired: true means the default agent engine configuration must separately activate webhooks.inbound_route_url with readback; this request does not rewrite live engine configuration. Verified incoming calls expose callbackOf.callId and optional server-owned taskId and taskItemId in call details. New REST GET/PUT /v1/numbers/{e164}/callback-routing and MCP get_callback_routing / set_callback_routing. Signed incoming tool context carries direction=in and empty dispatch/task/item fields. Server-owned volai_call_mode=campaign_callback is set only for verified callbacks. Verified inbound human contact stops later scheduled retries of the same task item without creating an outbound attempt or charge. An already running call and its billing finish normally. The server-owned dispatch/task/item binding is retained for eight days to cover the callback window.
• 8 Oct 2026 (1.31.0): POST /v1/tasks, PATCH /v1/tasks/{id}, create_task and update_task accept optional retryPolicy: "lorela_enterprise" and expiresAt (positive safe-integer Unix milliseconds); both fields are returned in the public task. Without a policy, maxAttempts remains 1-3 with a creation default of 1; with the policy it is 1-4 with a creation default of 4. PATCH without a limit preserves it. The policy can be enabled only before the first dispatch attempt. The second attempt is no earlier than eight minutes after the first real attempt starts, within 08:00-22:00 Europe/Prague; the third uses the next other 08:00-09:00 or 17:00-19:00 window; the fourth uses the opposite window on the following calendar day. A narrower callingWindow, including weekdays, still applies. Only no_answer, missed, busy or completed voicemail without human contact can retry; uncertain results and engine failures need review. The policy rejects manual resolve with action: "retry" and stops calling five days after the first real attempt. expiresAt also works without a policy and prevents any new dial at or after the deadline, including the first attempt; a call already in progress finishes normally. DNC and automatic blocking after three failures within 24 hours are not bypassed, so the fourth attempt is not guaranteed.
• 5 Oct 2026 (1.30.2): A call for which the engine does not send caller_loop in the post-call (the caller first talked to the agent and only afterwards just a repeated message was left on the line) has endReason: "completed" and the regular price, like any other completed call. The fallback sync of a lost post-call (the engine's GET /v1/calls) now reads metrics.caller_loop_reported: the value 1 means the engine sent caller_loop in the post-call, and caller_loop is taken over as before; the value 0 means an ordinary call, which is closed and billed with endReason: "completed" regardless of metrics.caller_loop_released. For an older engine without this field, the existing rule with metrics.caller_loop_released applies (a positive value means an ordinary call). REST and MCP response shapes, the endReason values and the outcome filter do not change.
• 4 Oct 2026 (1.30.1): endReason: "caller_loop" and priceHal: 0 are now given only to an inbound call with a positive durationSecs; an outbound call, or a call with zero duration, for which the engine sends termination_reason: "caller_loop" takes the regular path (endReason: "completed" and regular billing; a zero-duration call stays unclosed as before). The fallback sync of a lost post-call (the engine's GET /v1/calls) takes over caller_loop only when metrics.caller_loop_released is missing or 0; with a positive value (a person spoke up during the wait) the call is closed and billed like any other completed call with endReason: "completed", and call.completed carries the price, the same as when the post-call arrives on its own. A call with endReason: "caller_loop" is never listed in the portal among calls needing attention (Overview and the Calls filter), and the weekly e-mail summary does not count it as a handled call or a caller and does not list it among calls that need a reaction. REST and MCP response shapes, the endReason values and the outcome filter do not change.
• 4 Oct 2026 (1.30.0): New endReason: "caller_loop" value (REST GET /v1/calls and GET /v1/calls/{id}, MCP list_calls and get_call, webhook call.completed): an inbound call whose caller was an automated system repeating the same message (a queue, a dialer), ended by the engine's guard. The source is metadata.engine.termination_reason: "caller_loop" in the engine's post-call (for a lost post-call, the same field from the engine's GET /v1/calls). The call has status: "completed", a positive durationSecs and priceHal: 0, and no credit is charged; the price of 0 applies up to five minutes of call duration - a longer call is billed at the regular rates and keeps endReason: "caller_loop". The call.completed webhook carries endReason: "caller_loop". A call where a person spoke up during the wait and the engine carried on with them does not get caller_loop. In the outcome filter (GET /v1/calls, list_calls) such a call counts as agent.
• 4 Oct 2026 (1.29.6): PATCH /v1/agents/{id}, update_agent and draft publish: changing language from a language in which new agents start on ElevenLabs (today en, de, pl) to one in which they start on the engine (cs, sk) triggers, for an agent with provider: "elevenlabs", the same post-save engine switch attempt as turning on transferTo. On success the agent has provider: "engine" and the engine's default voice for the new language (milena, katarina); on failure it stays on ElevenLabs. A change between cs and sk moves nothing. voicemail_requires_engine has new wording: on creation it points to useForOutboundTasks: true, on an existing agent to support.
• 4 Oct 2026 (1.29.5): POST /v1/agents and create_agent return a new code elevenlabs_by_explicit_choice ({code, message: {cs, en}}) in warnings when the request sent useForOutboundTasks: false, the deployment default would have picked the engine for the agent's language, and the agent really stayed on ElevenLabs (a transferTo handoff may have switched it to the engine). The agent is created as before and the code blocks nothing. PATCH /v1/agents/{id}, draft publish and rollback never return it.
• 3 Oct 2026 (1.29.4): Documentation only, the API behavior does not change. maxAttempts (1-3) is the highest number of automatic dials of one contact, the first call included; 1 means no retries. A contact that you give resolve with action: "retry" after its attempts are used up gets one more dial. Every attempt where the call could have happened counts (unanswered, declined by the person called, or with an uncertain result). An attempt rejected before dialing does not count and has items[].attempts[].countsAsAttempt: false.
• 3 Oct 2026 (1.29.3): For attempts recorded from this version on, items[].attempts[].countsAsAttempt is false for every code where the call provably never happened, so they do not count toward maxAttempts: agent_not_found, agent_no_number, insufficient_credit, invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, capacity_busy, call_rejected, validation, rate_limited, relay_lease_limit, invalid_workflow, engine_not_configured and destination_busy. Previously the permanent problems with the number (invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number) were counted, so after lifting a block and another rejection a contact showed more attempts than allowed although nothing was dialed. Attempts written before this version are not rewritten retroactively (the exception is an attempt whose dial intent the accounting repair closes). Uncertain dial errors (for example engine_unavailable) still count, because the call may have happened. A permanent problem still sends the contact to review (you decide), a repairable code (missing credit, an agent without a number and the like) pauses the task; rate_limited and relay_lease_limit leave the task running and only wait. Nothing is dialed in a loop because of this. A contact you return via resolve with retry after its attempts are used up now stays pending after a repairable dial error without a call (for example insufficient_credit) and is dialed again once the cause is fixed; before, it stayed failed and the task could not be started (task_not_startable).
• 3 Oct 2026 (1.29.2): destination_busy while dialing from a task (the call provably never happened): the contact keeps waiting (failed when it already had a counted attempt and has another free one, otherwise pending) with items[].lastError: "destination_busy" and items[].nextAttemptAt from the remaining time of the number lock (at least 30 s, at most 16 min, 90 s without a lock), the attempt has countsAsAttempt: false, the reservation in reservedBudgetHal is released and the other contacts keep running; the task's lastError is not set, only a stale waiting rate_limited or relay_lease_limit is cleared, because a busy result proves the limit passed. After the 6th busy result in a row (5 waits) the contact goes to review with reviewReason: "dial:destination_busy". The seven permanent codes (on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, invalid_number, unsupported_country, blocked_destination) send the contact to review with reviewReason: "dial:<code>", but the task stays running and moves to needs_attention only when no other work is left (previously immediately). Over the API and MCP a block is lifted with two calls: POST /v1/dnc/{e164}/unblock (unblock_destination), then resolve with action: "retry" (resolve_task_item); for your own number, a number of another volai account, an invalid number, a number outside Czechia and Slovakia and a premium-rate line only skip helps. A contact in review can now appear while the task is still running; resolve then returns 409 task_not_editable, so wait for needs_attention or pause the task. POST /v1/calls does not change.
• 2 Oct 2026 (1.29.1): items[].providerCallId points only to the call of the latest attempt: a contact in failed that is waiting for another attempt does not carry it; the call of every attempt stays in items[].attempts[].providerCallId. Previously the item kept the call of the first attempt, the next dialed call was not recorded on the task, and the contact was dialed again without counting the attempt and without adding the price to spentHal. The errors on_dnc, destination_auto_blocked, cannot_call_own_number and cannot_call_volai_number while dialing from a task are provably no call: the attempt gets outcome: "failed", the reservation in reservedBudgetHal is released right away and the contact goes to review with reviewReason: "dial:<code>" (previously outcome: "unknown" and a held reservation). POST /v1/tasks/{id}/start no longer returns 409 task_needs_attention because of a reservation that no contact holds; POST /v1/tasks/{id}/reconcile settles such a reservation and also closes an older open dispatch intent left after an attempt that was never dialed.
• 2 Oct 2026 (1.29.0): New endpoint POST /v1/numbers/orders/{id}/cancel (no body) and MCP tool cancel_number_order: a pending order moves to the new status cancelled (a new status value of the order in GET /v1/numbers/orders and list_number_orders); provisioning returns 409 in_progress, done and failed 409 invalid_transition, a foreign or unknown id 404 not_found; cancelling again returns the order unchanged. A cancelled order no longer counts toward the first top-up gate (one number per account without a top-up). callingWindow.end of tasks is inclusive of the whole minute (current <= end): a 00:00-23:59 window covers the whole day and window_closed no longer occurs in the end minute itself.
• 30 Sep 2026 (1.28.1): PATCH /v1/numbers/{e164} (MCP set_number_routing) with mode: "forward" returns 402 insufficient_credit when the account has never topped up and the number is not forwarded yet. A number that is already in forward can be pointed at a different target without a top-up. POST /v1/numbers (MCP buy_number) and POST /v1/numbers/orders (MCP order_number_from_region) return 402 insufficient_credit when asked for an additional number while an account without a top-up already holds an active number or has an open order (pending, provisioning). Same code and cause (account) as for SMS, different message text - it says what to do (make the first credit top-up); nothing is charged. After the first credit top-up (card, auto top-up) the restriction is gone.
• 25 Sep 2026 (1.28.0): New suspended: boolean field on the agent object (REST and MCP, GET/POST/PATCH /v1/agents). New error codes agent_suspended and account_suspended (403, cause: "account") - account_suspended on every REST call with an API key and every MCP tool (after the rate limit) except reading tax documents (GET /v1/billing/documents, /{id} and /{id}/pdf, the MCP tools list_billing_documents and get_billing_document), which stay available; agent_suspended on POST /v1/calls, POST /v1/agents/{id}/test-call and POST /v1/tasks/{id}/start. An inbound call blocked by a suspension of the agent or the account carries endReason: "suspended" (a new value next to credit_blocked, price 0). An account_suspended/agent_suspended response is never stored under an Idempotency-Key, so the same key succeeds once restored. Custom variable keys (variables on POST /v1/calls and make_call) can no longer start with the volai_ prefix - it is reserved for variables volai fills in itself (such as volai_block_reason), and such a request returns 400 validation; in tasks, such a key is only refused when the contact is dialed. Suspending and resuming is done only by the operator in the admin panel - there is no REST or MCP tool for it. The sentence a caller hears on a blocked line (debt or suspension) is now spoken in the agent's language (cs, sk, en, de, pl).
• 25 Sep 2026 (1.27.3): No interface change: the same warnings code agent_misuse_suspected in the same REST and MCP responses, only broader recognition.
• 24 Sep 2026 (1.27.2): Outbound tasks: relay_lease_limit from dialing (the quota of 2 concurrent agent calls per account) now behaves like rate_limited - the task stays running, sets lastError: "relay_lease_limit", the attempt does not count (countsAsAttempt: false) and waiting contacts get items[].nextAttemptAt one minute later. Previously the item went to review with reviewReason: "dial:relay_lease_limit" and the task to needs_attention. The engine sync (GET /v1/calls) reads the new attempt_id field of an outbound call and uses it to match an initiated record after an uncertain dial (no call_sid, also for an agent without its own number); once matched, call.completed is sent with the price and the relay line and quota are released. Requires an engine that lists attempt_id; an older listing behaves as before.
• 24 Sep 2026 (1.27.1): POST /v1/calls with agentId on an agent on volai's own engine, a trial call with systemPrompt, MCP make_call and outbound tasks: when dialing on the engine ends with a timeout, a dropped connection, a 500/504 response or an unreadable 2xx, the response is still 502 engine_unavailable, but the call stays initiated (no priceHal), the relay line is not released and the same to stays locked for 15 minutes (destination_busy); the concurrent call quota is released right away. If the call happened, the post-call or the engine sync fills in the outcome and price (the post-call now finds it by the attempt identifier even without a call_sid, including agents without a number of their own) and call.completed is sent; if not, the watchdog closes it after 2 h as failed with priceHal: 0. The call.failed webhook is not sent for an uncertain dial. A certain failure (no connection to the engine at all or a timed-out connection attempt, 4xx, 502/503) behaves as before: failed, priceHal: 0, call.failed.
• 24 Sep 2026 (1.27.0): New warnings code agent_misuse_suspected ({code, message: {cs, en}}). Appears in POST/PATCH /v1/agents, PUT /v1/agents/{id}/draft, POST /v1/agents/{id}/simulate, POST .../draft/publish, POST .../draft/rollback, POST /v1/calls (the trial call prompt or variables), POST/PATCH /v1/tasks, POST/PATCH /v1/tools and the matching MCP tools (create_agent, update_agent, save_agent_draft, simulate_agent_draft, publish_agent_draft, rollback_agent_draft, make_call, create_task, update_task, create_tool, update_tool). The warnings field is optional, absent when there is nothing to flag, and /openapi.json describes it on all of these responses.
• 24 Sep 2026 (1.26.3): POST /v1/calls with from (bridge) and MCP make_call: when the connection order to the phone operator ends with a network error, a timeout or a 429/5xx response, the call is returned as a success with status: "initiated" instead of 502 callback_failed and stays initiated until cdr-sync pairs it with the CDR (and bills it), or the watchdog closes it after 24 h as failed with priceHal: 0. callback_failed now means only a provable rejection by the operator (an error response or 4xx). The call.failed webhook is not sent for an uncertain order; the same to number stays locked for about 10 minutes (destination_busy).
• 24 Sep 2026 (1.26.2): The per-account cap on calls within 24 hours (shared by POST /v1/calls with an agent or a bridge, relay and trial calls, MCP make_call and outbound tasks) is now 1000 instead of 200. Exceeding it still returns 429 rate_limited with the daily-limit message; 10/min, concurrency and the engine budget are unchanged.
• 24 Sep 2026 (1.26.1): Outbound tasks: a call record in failed with no conversationId and no priceHal (the engine refused or did not confirm the dial) now settles at 0 in reconcile - previously the item kept reviewReason: "billing_unknown" and the task stayed needs_attention forever. resolve with skip on a billing_unknown item moves a task with remaining work to paused (the original call's reservation keeps counting in reservedBudgetHal, and start accepts it); retry still waits for the price. A decision right after a dial error (reviewReason: "dial:...") no longer loses the link to the call or its reservation. rate_limited while dialing (engine limit, 10 calls per minute, 200 per day) keeps the task running with lastError: "rate_limited" and sets waiting items' nextAttemptAt to the end of the limit (from Retry-After, otherwise in 5 minutes, at most 24 hours) instead of paused; the attempt does not count. invalid_workflow and engine_not_configured while dialing are provably no call (the task becomes paused, the attempt does not count). Every call by an agent on volai's own engine that the engine never dialed (outbound tasks as well as POST /v1/calls, MCP make_call and the portal) has priceHal: 0 and durationSecs: 0 in GET /v1/calls instead of missing values; the call.failed webhook is unchanged.
• 24 Sep 2026 (1.26.0): POST /v1/calls with agentId on an agent on volai's own engine (and MCP make_call): a rejection by the engine's outbound-minute limit (hourly and daily bucket per account) or by full engine concurrency is now 429 rate_limited instead of 502 engine_unavailable; the minute limit adds a Retry-After header (seconds until the end of the hourly window, or until midnight UTC for the daily one). Nothing was dialed or charged; the call stays in the history as failed and the call.failed webhook carries reason: "rate_limited". Outbound tasks treat rate_limited (including the 10 calls/min and 200/day limits) as provably no call: the item is failed without counting an attempt, and the task is paused instead of needs_attention. The POST /v1/calls error table now also lists 502 engine_unavailable - for an agent on volai's own engine it means only a real engine outage, not a limit.
• 23 Sep 2026 (1.25.0): New optional event_id field in the webhook envelope ({event, data, ts, event_id}) for call.completed/call.failed/call.no_answer/call.missed - message.sent and the webhook.test test event are unchanged. A failed delivery of those four events no longer stops after 3 attempts (3s apart): it stays queued and retries over the following minutes, up to 5 rounds; a repeat delivery carries a byte-identical body. GET /v1/webhook/deliveries (and MCP list_webhook_deliveries) now also show rounds before the final one, attempts is the sum of attempts across all rounds, and there is a new optional eventId field.
• 23 Sep 2026 (1.24.1): Two new warnings codes: prompt_variables_unavailable_inbound (an agent with numberE164 whose systemPrompt/firstMessage uses a {{variable}} outside the set an inbound call actually supplies) and first_message_empty (a firstMessage with no letter or digit left in it outside the variables once every {{...}} block is removed). Both REST (POST/PATCH /v1/agents, publish and rollback) and MCP (create_agent, update_agent, publish_agent_draft, rollback_agent_draft) read the same source as the portal's agent editor (agentWarnings).
• 20 Sep 2026 (1.24.0): New optional busyCalendarIds field on the agent (POST/PATCH /v1/agents, MCP create_agent/update_agent, drafts) and on agent-less slot search and booking (POST /v1/integrations/{id}/availability, POST /v1/integrations/{id}/events, MCP find_free_slots, create_calendar_event). The calendars are read in parallel; if any of them fails, the whole lookup fails, so no time is offered over an event we simply could not see. At most four, without duplicates and without calendarId; otherwise 400 calendar_invalid_rules, an unknown calendar 400 calendar_invalid_calendar.
• 20 Sep 2026 (1.23.4): The error tables of POST /v1/agents, PATCH /v1/agents/{id} and draft publish/rollback add the six codes validateCalendar returns: 404 calendar_integration_not_found and 400 calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules. This flows into openapi.json, the /docs/api reference, SKILL.md and llms-full.txt.
• 20 Sep 2026 (1.23.3): maybeQueueMissedCallSms now also fires for an outbound call with answeredBy: "voicemail" (previously only status: "no_answer" and inbound missed). A voice menu (ivr) or unknown does not trigger it. All other conditions (CZ/SK number only, DNC, blocked destinations, one SMS per number per 24 h, quiet hours, last task attempt) are unchanged; CallRecord.missedSms is written the same way.
• 19 Sep 2026 (1.23.2): A timestamp with milliseconds was formatted with a time zone offset one minute short (+01:59 instead of +02:00) - this affected the now field in the agent tools and the start of a created event when a client sent start with fractional seconds. Alternatives returned with 409 calendar_slot_taken (POST /v1/integrations/{id}/events, MCP create_calendar_event) are now computed from the requested time, the same as find_free_slots with a time.
• 19 Sep 2026 (1.23.1): The agent calendar field (POST/PATCH /v1/agents, MCP create_agent/update_agent and drafts) rejects a calendar whose accessRole is reader or freeBusyReader with 400 calendar_invalid_calendar, because the agent writes appointments into the same calendar. list_calendars returns the role as accessRole where the provider reports it; a calendar without a role is accepted as before. No other error codes change.
• 19 Sep 2026 (1.23.0): New CallRecord.rating field (value: "good" | "bad", reason?, note?, at, source: "portal" | "email" | "api" | "mcp") and CallRecord.missedSms; PATCH /v1/calls/{id} and MCP annotate_call accept rating/ratingReason/ratingNote (patchCallAnnotation calls rateCall with source: "api"/"mcp"). New AgentRecord.missedCallSms { enabled, text? } field (variables {firma}, {cislo}, {agent}) on POST/PATCH /v1/agents, GET /v1/agents/{id} and MCP create_agent/update_agent/get_agent/save_agent_draft. GET/PATCH /v1/account and MCP get_account/update_account have companyName (max 80 chars, empty string clears it), and GET now returns notifications.weeklySummary. The test call in the agent editor shows the outcome based on the call goal (call.evaluation.goal) and the collected data.
• 18 Sep 2026 (1.22.0): New endpoints POST /v1/integrations/{id}/availability (free slots without a saved agent - windows omitted means 24 hours every day) and POST /v1/integrations/{id}/events (create an appointment, requires confirm: true, optional idempotencyKey for safe retries; 409 calendar_slot_taken on a collision), MCP tools find_free_slots and create_calendar_event with the same shape. DELETE /v1/integrations/{id} now returns affectedAgents - agents whose calendar field was turned off by disconnecting this integration. New calendar field on POST/PATCH /v1/agents, GET /v1/agents/{id} and MCP create_agent/update_agent/get_agent: integrationId, calendarId, timezone, slotMinutes, minNoticeMinutes, horizonDays, bufferMinutes, windows (an array of {from,to} windows per weekday). Works only on volai's own engine (provider: "engine") - on an agent hosted on ElevenLabs the field is saved and waits for the calendar_pending_engine_switch warning until the agent switches. Eleven new error codes with cause/action: calendar_slot_taken, calendar_confirmation_required, calendar_invalid_range, calendar_integration_not_found, calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules, calendar_too_many_events, calendar_unavailable.
• 18 Sep 2026 (1.21.0): New ledger movement type setup_revision (GET /v1/credit/ledger, MCP) for a done-for-you setup order's revision round beyond the package, amount SETUP_EXTRA_REVISION_HAL (490 CZK excl. VAT). Tax documents (GET /v1/billing/documents, .../{id}, list_billing_documents, get_billing_document) now always carry a kind field ("invoice" - default, or "credit_note"), plus optional correctsNumber and correctionReason fields; a done-for-you setup refund's credit note is numbered in its own OD series and carries positive amounts (the minus sign is added by the PDF). credit() (lib/service/balance.ts) gained an internal notifyTelegram parameter - a done-for-you payment now sends just one Telegram alert ("Na klíč: zaplaceno"), not two. New public landing page at /receptionist-done-for-you (Czech canonical /recepcni-na-klic).
• 18 Sep 2026 (1.20.0): New laughter field (auto/on/off) on POST/PATCH /v1/agents and MCP create_agent/update_agent: auto follows the engine's sensitive-topic detection (debt collection, healthcare, authorities, funeral services), on overrides that detection, off always suppresses it; an omitted key is stored and returned as auto, never absent. GET /v1/agents/{id} and the new MCP tool get_agent (previously missing parity for a single agent's detail) add laughterEffective ({active, reason, sensitiveCategory} | null) nested inside the returned agent object, computed fresh for the published configuration; null means it could not be determined right now (the engine did not respond within 3 seconds, was down, or returned a silent 404 on an older build) - never a guess. MCP update_agent returns the same object as a top-level field next to agent instead, since PATCH /v1/agents/{id} never returns it. The field is accepted and stored for an agent on ElevenLabs too, but has no audible effect there - only a Czech Cartesia voice on volai's own engine plays it.
• 18 Sep 2026 (1.19.0): New REST API v1 and MCP area - source setup-orders, capability area setup (after credit). Seven endpoints (POST /v1/setup-orders, GET /v1/setup-orders, GET/POST /v1/setup-orders/{id}, .../messages, .../checkout, .../launch, .../cancel) and seven matching MCP tools (create_setup_order, list_setup_orders, get_setup_order, message_setup_order, checkout_setup_order, launch_setup_order, cancel_setup_order) over the same service layer, lib/service/setup-orders.ts. The quote is always computed by the catalog in code (lib/setup-catalog.ts); the model only picks items from the conversation. New error codes: setup_order_not_found, order_closed, invalid_transition, quote_pending_confirmation, checkout_open, turn_in_progress, advisor_no_quote, advisor_unavailable, setup_orders_disabled. Documentation at /docs/done-for-you (Czech /docs/na-klic).
• 17 Sep 2026 (1.18.0): The agent draft (PUT/GET /v1/agents/{id}/draft, POST /v1/agents/{id}/draft/publish) and the MCP save_agent_draft tool now treat numberE164 as three-state: an absent key leaves the agent's number untouched, null disconnects it, and a string attaches that number - parity with the semantics PATCH /v1/agents/{id} already had. Reading a draft also reconciles it against the live agent: published.numberE164 always mirrors the live number, and draft.numberE164 does too whenever the draft made no explicit choice, so the editor's pre-publish check and outbound tasks see the true state even after a number was attached or moved outside the editor; "no explicit choice" also covers a string that matches the agent's current LIVE number - that value behaves the same as an absent key, re-checked on every draft read against whatever number is live at that moment; if the number later moves to a different agent outside this draft, the same stored value becomes an explicit choice again and the next publish or rollback reattaches it here - not silently: publish and rollback responses (REST and both MCP tools) now carry a new number_changed_by_publish warning with from/to (E.164, or null for no number) in that case, without blocking the operation either. One read-side compatibility note: draft.numberE164 can now come back as null (an explicit "no number" choice) where the key used to be simply absent - treat it the same as an absent key, meaning the agent has no number. The "tested" marker and the agent fingerprint pinned to a running outbound task are now computed WITHOUT the phone number too (behaviorFingerprint, not draftFingerprint), so attaching or moving a number outside the editor no longer requires a fresh test and no longer stops a running campaign; a draft with a number saved BEFORE this change has its marker computed the old way, including the number, so it asks to be re-earned once - one test or publish after the update restores it, and the new rule applies from then on.
• 15 Sep 2026 (1.17.0): A new goal display state, GoalDisplayState (success/failure/unclear/no_conversation/not_evaluated), replaces the AgentGoalResult triple in the portal's display, in the /hovory filters and in the overview. REST and MCP gained answeredBy: "ivr", goal.reason ("no_caller_speech"/"evaluation_error"), and hasConversation (boolean | null). The goal parameter (GET /v1/calls, MCP list_calls) accepts five new values alongside the existing unknown, which stays backward compatible - it still covers records with no clear result (goal.result missing or unknown): always unclear and not_evaluated, and no_conversation only when its result is also unknown.
• 13 Sep 2026 (1.16.0): A new endReason: "engine_error" value (status failed) appears when the engine sends metadata.engine.termination_reason as engine_stall or engine_error for a call that was actually handled - previously that field was discarded for such calls. priceHal is set to 0 only when the call has no price yet (otherwise it is left unchanged, with an ALERT log). The call.failed customer webhook gained four new optional fields: durationSecs, priceHal, transcript, summary - populated only for this technical branch, missing everywhere else as before. GET /v1/calls/{id} and MCP get_call return the same endReason value. Outbound tasks (POST /v1/outbound-tasks, MCP) treat engine_error as a retryable attempt (the same path as no_answer), not a reason to stop the campaign, and do not record it toward the automatic 30-day destination block.
• 13 Sep 2026 (1.15.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take a new silencePromptSecs: number | null field (a whole number 3 to 25, null turns it off), bounds matching the engine (engine/types.py, U1). A missing field on POST/create_agent saves the default of 10 - unlike voicemail, the field is accepted and returned for EITHER provider (GET /v1/agents returns the stored value even for provider: "elevenlabs"). A value outside the bounds fails with the generic validation error (validation, 400), no new code. Existing agents on the engine get the default of 10 via a one-off re-sync script (scripts/resync-silence-prompt.mts) that changes only this one field.
• 13 Sep 2026 (1.14.7): OpenAPI adds descriptions to every operation and request field, including nested variants. Agent, tool, SMS and call constraints use product limits shared with the service layer instead of permissive parser ceilings. Automated checks validate all request and response examples against their schemas. API behavior, error codes and provider settings are unchanged.
• 13 Sep 2026 (1.14.6): POST /v1/messages and MCP send_sms return insufficient_credit (HTTP 402, cause account) until the account has a positive topup (card or auto top-up) or admin (manual owner adjustment) ledger entry. The previous cap of 3 SMS for accounts without an active number of their own is gone, and an active number no longer grants an exception. The first top-up is kept as a permanent account flag, so a long ledger history never blocks a customer.
• 13 Sep 2026 (1.14.5): New workflow_node_tool_missing code in warnings on POST/PATCH /v1/agents, on draft publish and rollback, and on MCP create_agent, update_agent, publish_agent_draft and rollback_agent_draft. It applies to both providers, because a deleted tool does not reach the phase on volai's own engine either. workflow_node_tool_not_synced now only covers a tool that is on the account but not among the agent's own. The Reception template also recommends two sentences for the base prompt: do not guess operational details, and ask about one thing at a time.
• 12 Sep 2026 (1.14.4): Setup distinguishes OAuth grant identifiers from API keys when restoring older saved choices. An unavailable status check is not treated as revoked access.
• 12 Sep 2026 (1.14.3): Added the catalog files katty-studio.mp3 and katty-telefon.mp3 using the same generator and content as the other voices. The agent voice, provider and phone service settings are unchanged.
• 12 Sep 2026 (1.14.2): Copy labels and next-step guidance match the selected connection method. Codex desktop with an API key points to config.toml. Closing the mobile menu preserves focus restoration.
• 12 Sep 2026 (1.14.1): Sign-in preserves the assistant setup destination. The workspace preference is stored per account separately from actual MCP verification. Manual guides cover Claude Code, Codex CLI and desktop, with API keys as an alternative. Help and the names Voice agents, Phone numbers and Data & integrations are consistent.
• 12 Sep 2026 (1.14.0): When useForOutboundTasks is omitted, selection depends on VOLAI_ENGINE_DEFAULT_FOR_NEW, engine availability and VOLAI_ENGINE_DEFAULT_FOR_NEW_LANGUAGES (unset means cs,sk). Language alone does not guarantee the engine. Explicit true requests the engine; false starts on ElevenLabs. Applies to the portal, POST /v1/agents and MCP create_agent. Read back provider and voiceId after creation; handoff may trigger a subsequent provider switch attempt.
• 12 Sep 2026 (1.13.0): The workflow field is available in POST and PATCH /v1/agents, in the agent draft, and in the create_agent, update_agent and save_agent_draft MCP tools. A call that went through phases carries workflowPath in GET /v1/calls and GET /v1/calls/{id}. New workflow_*, workflow_not_synced_to_provider and workflow_node_tool_not_synced warnings flag phase configuration issues.
• 12 Sep 2026 (1.12.5): voiceId for an ElevenLabs agent: katty (default, the template voice) or a raw ElevenLabs id; jana is gone from the catalog and from ElevenLabs (the two agents from the afternoon of 12 Sep were switched to Katty and the voice was removed from the workspace). GET /v1/voices?provider=elevenlabs and MCP list_voices with provider: elevenlabs return katty. The engine's ElevenLabs fallback for Milena, Tereza and Katarina is Katty as well.
• 12 Sep 2026 (1.12.4): Polling no longer interrupts a slow status request. Successful MCP read evidence is found by active access even if writing the helper index failed. Verification still requires get_balance or list_agents through MCP.
• 12 Sep 2026 (1.12.3): Fixed the English calendar privacy link and kept an active goal filter visible even without previous evaluations. Both languages have regression coverage for links and unavailable integrations.
• 12 Sep 2026 (1.12.2): The MCP guide uses existing evidence of successful reads through an active API key or OAuth grant, with no simulated verification. The goal=unknown filter in GET /v1/calls and MCP list_calls also includes records without a goal evaluation. Technical completion does not mean a goal was met. REST and MCP still return individual records; the portal groups them into conversations.
• 12 Sep 2026 (1.12.1): voiceId for an ElevenLabs agent: jana (default, the template voice) or a raw ElevenLabs id; anet passes only on an agent that already has it, otherwise a 400 validation with an explanation (previously a 502 eleven_labs_error from ElevenLabs voice_live_moderated_not_allowed). GET /v1/voices?provider=elevenlabs and MCP list_voices with provider: elevenlabs return jana. An ElevenLabs agent without voiceId gets Jana explicitly (the record carries her id). SIP registration: the carrier returned 403 INVALID_USER for lines bought through its API until the line's SIP protocol was toggled off and on once; fixed for all lines and done automatically when a new line is bought.
• 12 Sep 2026 (1.12.0): OAuth authorization code + PKCE S256, DCR, resource-bound opaque tokens, refresh rotation/replay detection, OIDC discovery/JWKS/userinfo and revocation. Access tokens last 10 minutes, refresh tokens up to 30 days, grants up to 90 days. Password changes invalidate OAuth access. MCP annotations explicitly distinguish overwrites, paid actions, messages and external side effects.
• 12 Sep 2026 (1.11.0): GET /v1/numbers/{e164}/sip and MCP get_sip_credentials: outboundTrunkAddress = sip.volai.cz (volai's own SIP proxy with digest auth, realm sip.volai.cz; measured: the platform refuses an INVITE larger than the UDP MTU, the same call passes over TCP), transport = tcp (schema is now enum [tcp, udp], UDP works too), port 5060 unchanged. The watchdog monitors the proxy healthz (SIP_PROXY_HEALTHZ_URL): ops e-mail when unreachable, when the auth data sync stalls or when the certificate has under 14 days left. The ElevenLabs post-call webhook has its HMAC secret in production and is enabled per agent (ELEVENLABS_POST_CALL_WEBHOOK_ID).
• 12 Sep 2026 (1.10.0): GET /v1/numbers/{e164}/sip and MCP get_sip_credentials: outboundTrunkAddress is driven by its own configuration (it may equal server), field descriptions no longer mention a realm; inboundSignallingCidrs unchanged. The ElevenLabs post-call webhook matches inbound calls via metadata.phone_call.call_sid (it used to read the SIP Call-ID call_id, which never matched the call:sid key written by the initiation webhook) through findExistingCallByKeys shared with the conversations-sync cron (order call:conv -> call:attempt -> call:sid). Per-agent post-call webhook settings (platform_settings.workspace_overrides.webhooks) are migrated by the cron once ELEVENLABS_POST_CALL_WEBHOOK_ID is set; until then the cron keeps closing calls. The engine post-call accepts phone_call.external_number: null and caller_presentation; the uri_ caller prefix is stripped as in the initiation webhook. The call transfer target (transfer_to_number) is built from a separate VOLAI_SIP_TRANSFER_HOST, not from the public SIP domain. New internal source of auth data for the SIP proxy (GET /api/internal/sip-subscribers, outside v1, bearer + IP allowlist + rate limit).
• 12 Sep 2026 (1.9.0): POST/PATCH /v1/agents and MCP create_agent/update_agent can now return a second warnings code: first_message_too_long, independent of first_message_no_ai_disclosure - and publishing an agent draft (POST /v1/agents/{id}/draft/publish, MCP publish_agent_draft) and rolling it back to an earlier revision (POST /v1/agents/{id}/draft/rollback, MCP rollback_agent_draft) now return the same warnings too, which they previously omitted entirely - both of them write the first line to the live agent. The estimate counts words, digits per character, and all-caps abbreviations up to four characters; a longer all-caps word counts as one word, so a company name written in capitals no longer inflates the estimate. The single threshold (an estimated duration over 7 seconds) is measured against what the caller actually hears - the greeting plus the call-recording notice, when enabled. An unchanged default greeting template never gets the warning, only a line the customer has edited.
• 12 Sep 2026 (1.8.2): Documentation, integration guides and error actions point to AI assistant for access management. MCP makes clear that the voice engine is required to start an outbound task; a task can also be created with an ElevenLabs agent.
• 12 Sep 2026 (1.8.1): OpenAPI now describes Idempotency-Key for 14 supported operations, response headers and the optional revision JSON body when deleting a task. Documentation corrections without changing paid-action behavior: useForOutboundTasks distinguishes true/false/omission, tasks support 1000 recipients and billing_unknown retains the original call and reservation until its price is known. Credit tax documents are available over REST and MCP; an API key can revoke only itself over REST; integration disconnect is REST/portal. Correction to 1.6.1: preview_task_csv is not an MCP tool; use POST /v1/tasks/csv-preview or the portal. Install commands share the onboarding generator, example tabs have unique anchors and Python preserves JSON values.
• 11 Sep 2026 (1.8.0): The new REST POST /v1/dnc/{e164}/unblock and the corresponding MCP tool unblock_destination lift an automatic destination block; they also work for blocks created before this deployment. Older blocks may be absent from GET /v1/dnc and list_dnc because they predate the listing index, but direct unblock by phone number still works. Indexed blocks are returned in a blocked: [{e164, blockedAt, expiresAt}] array (times are Unix milliseconds) alongside the unchanged numbers. After a block is lifted, the failed-attempt counter starts over - three new failed attempts to the same number block it again, and lifting it again is not limited. groupCallsByConversation (the shared primitive behind /hovory, the CSV export, the Previous/Next navigation, and the stats) now sorts by representative.startedAt descending; it used to sort by key, i.e. alphabetically by conversation id. TestCallOutcome has a new no_answer value kept separate from failed, so the panel never claims a cause it doesn't know. A name written in ALL CAPS now gets an ALL CAPS vocative form (RADEK -> RADKU) in both the e-mail and the Overview header.
• 11 Sep 2026 (1.7.1): agent_busy (HTTP 409, cause: "busy") was added to the shared error map PUBLIC_ERROR_HTTP/PUBLIC_ERROR_CAUSE (lib/types.ts). It is returned by switchAgentProvider (lib/service/engine-provider.ts) - the only portal admin action that switches an agent's provider; REST v1 and MCP have no such input (agents.switch_provider in the capability catalog, lib/capabilities.ts). The check uses a new GET /v1/calls/active client (lib/engine.ts listActiveCalls): the agent's call is matched PRIMARILY by the agent_id field, which the engine carries on an active call since the version that added it was deployed; the number stays a fallback for an older engine without it.
• 11 Sep 2026 (1.7.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take a new voicemail: {enabled, action: "mark"|"hangup"|"message", message?} field - only for an agent with provider: "engine", otherwise voicemail_requires_engine; message is required when action: "message", up to 400 characters (invalid_voicemail_message). GET /v1/agents returns the configured value. The engine's post-call now carries answered_by/voicemail_reason/voicemail_message_left/voicemail_detected_at_secs; answered_by takes precedence over the previous transcript-based estimate (lib/answered-by.ts) only with human and voicemail - unknown is treated as "the engine didn't decide" and the transcript-based estimate is used instead. GET/list_calls/get_call for an outbound call handled by the engine also return voicemailReason (a fourth value, human_reply, for a short human reply), voicemailMessageLeft, and voicemailDetectedAtSecs.
• 11 Sep 2026 (1.6.5): For an outbound call ended before answer the engine deletes the room and delivers a post-call webhook: empty transcript, call_duration_secs: 0 and the new additive field metadata.engine.termination_reason (no_answer or disconnected_before_answer). The call gets status: no_answer, endReason: no_answer and price 0 as before, only immediately. The GET /v1/calls reconciliation pairs engine outbound calls by call_sid and sends zero duration for calls that never connected. GET /openapi.json: answeredBy now carries a description about the outbound-only limitation.
• 11 Sep 2026 (1.6.4): POST /v1/tasks and PATCH /v1/tasks/{id} (and create_task/update_task in MCP) accept up to 1000 recipients, POST /v1/tasks/csv-preview up to 1000 rows. A new task record size check (2 MB of serialized JSON) returns validation with field recipients.
• 11 Sep 2026 (1.6.3): ElevenLabs initiation webhook: the payload's agent_id is now checked against the routed agent's elevenAgentId OR id - a foreign agent_id gets only a minimal response without conversation_config_override; the same check guards closing the conversation in the post-call webhook and the conversations-sync cron. CDR-sync cron: an unrecognized outbound CDR record from your own line (excluding the demo number), older than 600s and without an ambiguously matching existing record, is now billed as kind: "sip" at the outbound rate with no agent surcharge (it shows up in GET /v1/calls with kind: "sip"; the chargedSip counter is only in the cron's own response, not in the public API); a younger or ambiguously matching record is still just held for manual review. CallKind extended with "sip". The CDR shape of a real SIP client call has no production evidence yet (no registered softphone) - hence both safeguards.
• 11 Sep 2026 (1.6.2): New endpoint POST /v1/tasks/{id}/items/{itemId}/resolve with body { action: "retry" | "skip", revision } and the MCP tool resolve_task_item; new error code item_not_resolvable (409, account), task_not_editable for a running or completed task. The engine call sync matches the account's own outbound leg by relay line and start time, closes an unanswered outbound call as no_answer and releases the tenant concurrency quota after closing. relay_lease_limit while dialing a task is a transient state that does not consume an attempt.
• 11 Sep 2026 (1.6.1): POST /v1/tasks/csv-preview and the portal recognise the phone column regardless of case, surrounding spaces and a trailing colon and accept aliases (telefon, tel, mobile, phone number); the response always names the column phone. A single-column input without a header whose first value is a phone is treated as data. Without a phone column the preview returns a single phone error on the header instead of Phone is required on every row. The agent_not_ready contract is unchanged. Documentation correction, 12 Sep 2026: the original MCP-tool claim was incorrect; CSV preview is REST/portal-only.
• 11 Sep 2026 (1.6.0): GET /v1/numbers/{e164}/sip and the MCP get_sip_credentials tool now also return outboundTrunkAddress, port, transport and inboundSignallingCidrs alongside server/username/password; MCP create_relay_lease and the get_sip_credentials description now explicitly distinguish server (registration) from outboundTrunkAddress (a platform's outbound trunk). The /en/docs/bring-your-own-agent guide, the ElevenLabs integration page and the blog post no longer put server into outbound_trunk_config.address - only outboundTrunkAddress.
• 11 Sep 2026 (1.5.1): GET /v1/calls, GET /v1/calls/{id}, the call.completed webhook and MCP list_calls/get_call: answeredBy is present only when direction: "out" (older records included). POST /v1/messages and send_sms: an account without an active number and without a positive topup/refund/admin ledger entry gets insufficient_credit (HTTP 402, cause account) after three sent SMS.
• 8 Sep 2026 (1.5.0): New REST endpoints: GET/PATCH /v1/account, PUT /v1/account/billing, GET /v1/api-keys, DELETE /v1/api-keys/{id} (self-revoke); PATCH /v1/calls/{id} and GET /v1/calls extended with from, to, agentId, flagged, goal, outcome query parameters; POST /v1/tools/test, POST /v1/tools/{id}/test, DELETE /v1/webhook, and GET /v1/tools/{id} now additionally returns agents; POST /v1/agents/{id}/draft/rollback; GET /v1/numbers/{e164}, GET/POST /v1/numbers/waitlist, DELETE /v1/numbers/waitlist/{offerId}, GET /v1/numbers/{e164}/sip/status; POST /v1/integrations, DELETE /v1/integrations/{id}, POST /v1/integrations/{id}/events/{eventId}/propose; GET /v1/changelog (no API key, x-volai-version on every v1 response including errors, 429 and /openapi.json). 16 matching new MCP tools: get_account, update_account, update_billing_details, list_api_keys, annotate_call, test_tool, remove_webhook, list_webhook_deliveries, rollback_agent_draft, reconcile_agent_draft_operation, test_call, get_number, join_number_waitlist, leave_number_waitlist, get_sip_status, get_changelog - revoking someone else's API key, creating an API key, and disconnecting an integration or card stay REST-only or portal-only (spec §3). The new capability catalog holds a capability field on every endpoint and tool; guard tests verify the error table and response example on /docs/api match the real error codes for every endpoint. Additive only - no existing status or code changed. The new content/changelog.json file is the single source of truth: /en/changelog, the changelog section on /docs/api, the Versioning section in SKILL.md, RSS (/en/feed/<area>), GET /v1/changelog and the MCP get_changelog tool are all generated views over it. Additive only - no existing content disappeared. New REST endpoints: GET/POST /v1/tasks, GET/PATCH/DELETE /v1/tasks/{id}, POST /v1/tasks/{id}/start, POST /v1/tasks/{id}/pause, POST /v1/tasks/{id}/reconcile, POST /v1/tasks/csv-preview. 7 matching new MCP tools: list_tasks, get_task, create_task, update_task, pause_task, reconcile_task, start_task (which requires repeating the real recipient count and budget, otherwise it returns an error with the real numbers) - deleting a task and previewing a CSV stay REST and portal only (spec §3). Portal: a Delete task button on the task detail page with type-to-confirm. Additive only - no existing status or code changed. New REST endpoints: GET /v1/credit/ledger, POST /v1/credit/topup, GET/PATCH /v1/credit/auto-topup, POST /v1/credit/auto-topup/setup, POST/DELETE /v1/credit/auto-topup/card, GET /v1/billing/documents, GET /v1/billing/documents/{id}, GET /v1/billing/documents/{id}/pdf; GET /v1/balance now additionally returns runway and notice. 6 matching new MCP tools: list_ledger, create_topup_link, get_auto_topup, disable_auto_topup, list_billing_documents, get_billing_document (get_balance extended with the same runway/notice) - get_billing_document does not return the PDF, which stays REST-only via GET /v1/billing/documents/{id}/pdf (binary output); turning auto top-up on and changing its amount or card stay behind a Stripe Checkout link only, MCP has neither (spec §2, §3). Additive only - no existing status or code changed. GET /v1/account now returns a new notifications.productUpdates field (on by default); there is a matching toggle in portal Settings. The daily email digest (cron 0 6 * * * UTC) only sends to accounts with a verified email and productUpdates !== false, at most one email per account per day. The List-Unsubscribe header and cookie-free one-click unsubscribe now also cover the reactivation email when UNSUBSCRIBE_SECRET is configured on the server - without it the email still sends, just without the unsubscribe link. Additive only - no existing status or code changed.
• 8 Sep 2026 (1.4.3): Every input property of all 44 MCP tools carries its own description (clients see it in tools/list; the PATCH .../events/{eventId} and PUT /v1/agents/{id}/draft bodies expose it in openapi.json too). The invoice endpoints GET /v1/integrations/{id}/invoices[/{invoiceId}] list their error codes by real reachability in the docs and in OpenAPI - integration_storage_error was removed, it never came from the API - and their query validation returns the human-readable message like the rest of v1 (same for GET .../events). Additive only - no status or code changed.
• 8 Sep 2026 (1.4.2): Fixed Apple event reads and confirmed updates: iCloud rejects UID searches, so event lists now return opaque CalDAV resource IDs. Pass externalId unchanged as eventId; reload any Apple event IDs saved from earlier versions. Invalid Apple IDs return 400 calendar_invalid_query. Google identifiers are unchanged.
• 8 Sep 2026 (1.4.1): POST /v1/agents and create_agent accept useForOutboundTasks (choosing volai's own voice engine at creation, the same choice as the portal checkbox "Use for outbound tasks"; omitted = the deployment default, today ElevenLabs). Additive only - no status or code changed.
• 8 Sep 2026 (1.4.0): Apple Calendar shares the same calendar flow over REST and MCP as Google. Fakturoid and ABRA Flexi added GET /v1/integrations/{id}/invoices[/{invoiceId}] plus the list_invoices and get_invoice tools (the interface only reads invoices). GET /v1/integrations and list_integrations also return providers with setup readiness and a browser connection URL. Provider credentials still require connection in the portal. Additive only - no status or code changed.
• 7 Sep 2026 (1.3.0): Google Calendar entered the public interface - GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET/PATCH /v1/integrations/{id}/events/{eventId} and six MCP tools (list_integrations, list_calendars, list_calendar_events, get_calendar_event, propose_calendar_update, confirm_calendar_update), which takes REST to 50 endpoints and MCP to 42 tools. Every error response also carries cause (request / account / busy / service - who fixes it) and action (one sentence on what to do). validation messages name the field, the actual value and the accepted maximum instead of the raw validator text; the input caps for an agent's name, instructions, goal and knowledge are ten times the product limits, so the limit is always reported by the product error with the exact number. MCP errors carry the same fields in structuredContent.error (including requestId) and a text prefixed by cause. Additive only, no status or code changed.
• 6 Sep 2026 (1.2.0): The /v1/agents/{id}/draft* and /simulate endpoints lost the ok wrapper and plain-string errors - errors now share the same shape, {error:{code,message,requestId,docsUrl}}, as the rest of v1; revision in request bodies was renamed to expectedRevision; added hasMore/nextBefore pagination fields, X-Request-Id and RateLimit-* headers, POST /v1/webhook/test, GET /v1/webhook/deliveries, and GET /openapi.json. The draft endpoints were already public from 5 Sep 2026, but without a stable contract - they are therefore excluded from the versioning guarantee (rule 1 of the Versioning section) up to and including 1.2.0.

Pełna, stale aktualizowana lista znajduje się na stronie Dziennik zmian (dostępna również jako kanał RSS).

Konwencje

Zasady obowiązujące we wszystkich endpointach - nie tylko w jednym z nich.

Identyfikatory

Każdy identyfikator ma prefiks wskazujący typ rekordu i poza tym jest nieprzezroczysty (nie należy go dalej analizować):

vk_ klucz API, ag_ agent, ad_ wersja robocza agenta, ado_ operacja na wersji roboczej, c_ połączenie, msg_ wiadomość SMS, tl_ narzędzie, whd_ dostarczenie webhooka, rl_ dzierżawa relay, int_ połączona integracja, inv_ dokument podatkowy (GET /v1/billing/documents), l_ wpis w księdze salda, task_ zadanie wychodzące, item_ odbiorca zadania, attempt_ próba połączenia na pozycji zadania, req_ identyfikator żądania (zob. Format błędu powyżej).

Znaczniki czasu

Znaczniki czasu są prawie wszędzie milisekundami uniksowymi (createdAt, startedAt, boughtAt, issuedAt, taxableAt) - WYJĄTKIEM są pola połączonego kalendarza ORAZ połączonych faktur: start, end, fetchedAt (kalendarz) i parametry timeMin/timeMax to ciągi RFC 3339 (2026-09-08T10:00:00.000Z), nigdy liczby; GET /v1/integrations/{id}/invoices i .../invoices/{externalId} również zwracają ciągi - fetchedAt ma ten sam kształt RFC 3339, a dueDate to zwykła data (2026-09-08) wprost z Fakturoid/ABRA Flexi albo null, gdy dostawca jej nie podał. Drugim wyjątkiem jest abonament miesięczny: periodStart i periodEnd (/v1/subscription, /v1/balance) to ciągi ISO 8601 w UTC, a nie milisekundy.

Stronicowanie - trzy schematy oraz listy bez żadnego

GET /v1/messages, GET /v1/calls i GET /v1/billing/documents przyjmują limit + before (znacznik czasu w ms, wyłączny) i odpowiadają hasMore/nextBefore - szczegóły w sekcji Stronicowanie powyżej. Wydarzenia połączonego kalendarza (GET /v1/integrations/{id}/events) używają zamiast tego nieprzezroczystego pageToken/nextPageToken - timeMin/timeMax/search muszą pozostać niezmienione między stronami, a sam pageToken tego nie gwarantuje. GET /v1/credit/ledger przyjmuje tylko limit (1-200, domyślnie 50) i w ogóle nie ma kursora - zawsze zaczyna od najnowszego wpisu. GET /v1/tasks bez ids zwraca najwyżej 100 ostatnich zadań; ids odczytuje do pięciu wskazanych zadań na żądanie, nie rościjąc sobie prawa do pełnego spisu zasobów najemcy. GET /v1/webhook/deliveries również nie ma kursora i zwraca najwyżej ostatnie 50 dostarczeń (udanych, nieudanych i testowych). Wyszukiwanie połączonych faktur też po cichu ma limit - pierwsze 40 wierszy z Fakturoid lub 50 z ABRA Flexi, bez kursora do dalszych; zamiast tego należy zawęzić wyszukiwanie. Wszystko inne, co zwraca listę (agenci, numery, numery komórkowe, narzędzia, klucze API, lista zakazu dzwonienia, głosy), zwraca cały zbiór w jednej odpowiedzi - nie ma czego stronicować.

Nieznane parametry i parametry o czeskich nazwach

Nieznany parametr zapytania jest prawie wszędzie po cichu ignorowany (żeby starszy klient nie psuł się przez jeden dodatkowy parametr) - wyjątkiem są endpointy połączonego kalendarza i połączonych faktur (/v1/integrations/{id}/...), które odrzucają nieznany parametr błędem 400 validation, ponieważ przekazują go dalej do dostawcy, a po cichu odrzucony filtr wyglądałby tam na brakujące dane, a nie na błąd; oraz, z niezwiązanego powodu, GET /v1/credit/ledger i GET /v1/billing/documents, których schematy zapytań są celowo ścisłe, aby literówka w limit/before kończyła się głośnym błędem, a nie cichym zignorowaniem.

Kilka pól celowo zachowuje czeską nazwę: przepływ adresu numeru (GET /v1/numbers/address-options, następnie POST /v1/numbers/orders - zwykłe POST /v1/numbers przyjmuje tylko e164/region i ignoruje adres) przekazuje psc, obec, cobce, ulice (tylko tam, gdzie adres ma ulicę) i cp - dokładne nazwy pól rejestru RÚIAN (własnej listy kodów adresowych operatora), z którego zamawiany jest numer, dzięki czemu wartość przekazywana tam i z powrotem nigdy nie zostanie po cichu błędnie przetłumaczona. GET /v1/calls/{id}/recording?stahnout=1 to jedyny parametr o czeskiej nazwie poza tym przepływem (pobranie jako załącznik zamiast wyświetlenia w przeglądarce). Cała reszta - identyfikatory, pola i parametry - jest po angielsku.

Limity zebrane w jednym miejscu

Każdy limit jest też wspomniany przy swoim endpoincie powyżej - to tylko zestawienie:

• 60 żądań/min na klucz API (REST i MCP dzielą go, zob. Limity zapytań powyżej)
• SMS: 1 na 2 s i 100/dzień na konto, dopiero po pierwszym doładowaniu salda
• SMS wysłane z numeru komórkowego (fromNumber): dodatkowo 20 wiadomości dziennie na konto w pierwszych 30 dniach po zakupie numeru, potem 50; najwyżej dwa numery komórkowe na konto
• Połączenia wychodzące (agent, most, próbne): 10/min i 1000/dzień na konto, jednocześnie najwyżej 2 połączenia wbudowanego agenta
• Dzwonki (POST /v1/rings): 30/min i 500/dzień na konto oraz 120/godzinę na jeden numer, niezależnie od limitów połączeń
• Wiadomości głosowe (POST /v1/voice-messages): najwyżej 200 na 24 godziny na konto, oprócz zwykłych limitów połączeń
• Połączenie próbne bez własnego numeru (POST /v1/calls z systemPrompt zamiast agentId/from): dodatkowo 3/24 h na konto ORAZ wspólny limit 30/godzinę dla WSZYSTKICH kont łącznie - wspólny limit może Państwa dotknąć bez Państwa winy.
• POST /v1/agents/{id}/test-call: 3/dzień na konto
• POST /v1/tools/test i .../{id}/test: 10/min na konto
• POST /v1/agents/{id}/simulate: 20/godzinę na konto
• POST /v1/webhook/test: 10/godzinę na konto
• GET /v1/changelog: 30/min na adres IP (bez klucza API)
• Zadania: uruchomione zadanie dzwoni w jednym takcie crona do najwyżej JEDNEGO odbiorcy. Kolejka ogólna pozostaje na */2 * * * * i obejmuje najwyżej 20 zadań ze wszystkich kont; zarejestrowane zadania PetCenter używają osobnego taktu * * * * * i kolejki, z tymi samymi limitami współbieżności i tempa połączeń. Obie kolejki obracają się sprawiedliwie, gdy czeka więcej niż 20 zadań.

Ponowienia webhooków

Nieudane dostarczenie dostaje do 3 prób w odstępie 3 sekund w ramach tej samej wysyłki. Dla zdarzeń połączeń (call.completed, call.failed, call.no_answer, call.missed) oraz dla message.received to nie koniec: zdarzenie pozostaje w kolejce, a dostarczenie jest ponawiane jeszcze kilka razy w ciągu następnych minut, łącznie do 5 rund - w rzadkim przypadku, gdy dotrze więcej niż raz, należy deduplikować po event_id z treści. message.sent i zdarzenie testowe webhook.test nie mają kolejki: po niepowodzeniu jest ono tylko zapisywane w logu i nie jest wysyłane ponownie. Postęp, w tym rundy przed ostatnią, można sprawdzić przez GET /v1/webhook/deliveries (lub list_webhook_deliveries) - attempts oznacza tam sumę prób ze WSZYSTKICH rund.

Wycofywanie

v1 dotąd tylko się rozszerzało (zob. Wersjonowanie powyżej) - jedynym wyjątkiem była wersja 1.5.1, która przestała zwracać answeredBy dla połączeń PRZYCHODZĄCYCH (pole nigdy nie miało tam sensownej wartości; dla połączeń wychodzących bez zmian). volai nie wycofało jeszcze w pełni żadnego pola. Gdy to nastąpi, pole zostanie oznaczone deprecated: true w GET /openapi.json, a odpowiedź będzie zawierać nagłówki Deprecation/Sunset z wyprzedzeniem co najmniej 90 dni, zaś odpowiedź MCP, która go dotyka, dostanie wpis w warnings (to samo pole, którego dziś używa się do ostrzeżenia o ujawnieniu AI Act) - samo usunięcie trafia zawsze wyłącznie w nowej wersji głównej (v2), nigdy po cichu w v1.

Połączenia a rozmowy - przed zsumowaniem liczników zob. akapit o tej samej nazwie w sekcji Połączenia poniżej.

Dane logowania (hasło, token, hasło do aplikacji) należy przekazywać wyłącznie wtedy, gdy użytkownik umieścił je już w miejscu, które można odczytać (zmienna środowiskowa lub plik, który wskazał) - nigdy nie należy o nie prosić w rozmowie ani ich powtarzać; dziś dotyczy to Kalendarza Apple i ABRA Flexi (zob. sekcje kalendarza i faktur poniżej).

Czego API nie potrafi

Całą stroną telefoniczną sterują Państwo przez API i MCP - numery, połączenia, SMS, agenci, webhooki, relay i lista zakazu dzwonienia. Profil, adres do faktury i dane firmy również obsługuje API (sekcja Konto powyżej). Kilka rzeczy z założenia pozostaje wyłącznie w portalu:

W drugą stronę brakuje celowo więcej niż jednej rzeczy: zwolnienie kupionego numeru (DELETE /v1/numbers/{e164}), numeru komórkowego (DELETE /v1/sms-numbers/{e164}) lub produktu "numer do połączeń i SMS" (DELETE /v1/voice-sms-numbers/{e164}) istnieje zarówno w REST API, jak i w portalu, ale nie ma go wśród narzędzi MCP - nieodwracalne działanie jest tam o jedno źle zrozumiane zdanie od zbyt dużego ryzyka. Celowo brakuje też: pobierania nagrania (treść binarna, GET /v1/calls/{id}/recording), szczegółów pojedynczej wiadomości lub narzędzia (listy list_messages/list_tools zawierają już te same pola, tylko nie dla jednego ID naraz) oraz osobnego narzędzia do połączenia testowego - make_call z agentId wykonuje to samo połączenie co POST /v1/agents/{id}/test-call, tylko bez jego surowszego dziennego limitu 3 połączeń.

Konto

Profil, adres alarmowy, dane do faktury i przegląd kluczy API. Tworzenie nowych kluczy API (POST /v1/api-keys) nie jest udostępnione - klucz, który tworzy klucze, zamieniłby utratę jednego z nich w trwały dostęp. Nowy klucz utworzą Państwo w portalu (sekcja Dostęp i API). Powiadomienia e-mail (callSummary, lowCredit, reactivation, productUpdates) są w tym interfejsie tylko DO ODCZYTU - zapis jest możliwy wyłącznie w portalu, ponieważ lowCredit to jedyny hamulec między wyczerpaniem salda a cichym wyłączeniem usługi.

curl https://volai.cz/v1/account \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "account": {
    "id": "u_8f2a1c9d3b47",
    "email": "radek@example.com",
    "name": "Radek Klein",
    "locale": "cs",
    "emailVerified": true,
    "createdAt": 1755000000000,
    "companyName": "Ukázková s.r.o.",
    "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "billing": null,
    "notifications": { "callSummary": true, "lowCredit": true, "reactivation": true, "productUpdates": true, "weeklySummary": true }
  },
  "testCalls": { "max": 3, "remaining": 2, "resetAt": 1755086400000 }
}

curl -X PATCH https://volai.cz/v1/account \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale":"en"}'

{
  "account": {
    "id": "u_8f2a1c9d3b47",
    "email": "radek@example.com",
    "name": "Radek Klein",
    "locale": "en",
    "emailVerified": true,
    "createdAt": 1755000000000,
    "companyName": "Ukázková s.r.o.",
    "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "billing": null,
    "notifications": { "callSummary": true, "lowCredit": true, "reactivation": true, "productUpdates": true, "weeklySummary": true }
  }
}

curl -X PUT https://volai.cz/v1/account/billing \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"Ukázková s.r.o.","dic":"SK9999999999","address":{"street":"Na Zámku 636","city":"Nehvizdy","zip":"250 81"}}'

{
  "billing": {
    "company": "Ukázková s.r.o.",
    "ico": null,
    "dic": "SK9999999999",
    "dicCountry": "SK",
    "dicVerified": true,
    "dicName": "Ukázková s.r.o."
  },
  "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
  "vies": { "dic": "SK9999999999", "country": "Slovakia", "name": "Ukázková s.r.o." }
}

curl -X POST https://volai.cz/v1/account/cancellation-request \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"callers_hang_up","note":"Volající zavěšují po první větě."}'

{
  "cancellationRequest": {
    "reason": "callers_hang_up",
    "note": "Volající zavěšují po první větě.",
    "requestedAt": 1793520000000,
    "alreadyRequested": false
  }
}

curl https://volai.cz/v1/api-keys \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "apiKeys": [
    {
      "id": "3f9a2c8e1b04",
      "label": "Production integration",
      "prefix": "vk_8h2j4kx",
      "createdAt": 1750000000000,
      "lastUsedAt": 1757280000000
    }
  ]
}

curl -X DELETE https://volai.cz/v1/api-keys/3f9a2c8e1b04 \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "revoked": true
}

Saldo

balanceHal i każda stawka w tym API są podane bez VAT - volai jest płatnikiem VAT, ale VAT jest naliczany dopiero przy doładowaniu salda kartą w portalu (zob. stronę /cenik), samo API go nie uwzględnia. Pełny opis z przykładami przepływów znajduje się pod /docs/kredit.

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "balanceHal": 8730,
  "balanceCzk": 87.30,
  "currency": "CZK",
  "runway": { "dailyAverageHal": 2910, "runwayDays": 3 },
  "notice": { "kind": "runway", "days": 3 },
  "topupBalanceHal": 8730,
  "subscription": null
}

curl "https://volai.cz/v1/credit/ledger?limit=3" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "ledger": [
    { "id": "l_9f2a1c8e", "ts": 1757280000000, "type": "call_out", "amountHal": -420, "grossHal": null, "description": "Outbound call" },
    { "id": "l_7c1e9a2f", "ts": 1757193600000, "type": "number_fee", "amountHal": -9900, "grossHal": null, "description": "Monthly number fee for +420601234567" },
    { "id": "l_3b7e1c9a", "ts": 1757107200000, "type": "topup", "amountHal": 50000, "grossHal": 60500, "description": "Card top-up" }
  ]
}

curl -X POST https://volai.cz/v1/credit/topup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup-2026-09-08-01" \
  -d '{"amountCzk": 500}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl https://volai.cz/v1/credit/auto-topup \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "autoTopup": {
    "enabled": true,
    "thresholdHal": 10000,
    "amountHal": 50000,
    "card": { "brand": "visa", "last4": "4242" },
    "spentThisMonthHal": 50000,
    "monthlyCapHal": 1000000,
    "disabledReason": null
  }
}

curl -X PATCH https://volai.cz/v1/credit/auto-topup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thresholdHal": 20000}'

{
  "autoTopup": {
    "enabled": true,
    "thresholdHal": 20000,
    "amountHal": 50000,
    "card": { "brand": "visa", "last4": "4242" },
    "spentThisMonthHal": 50000,
    "monthlyCapHal": 1000000,
    "disabledReason": null
  }
}

curl -X POST https://volai.cz/v1/credit/auto-topup/setup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: autotopup-setup-2026-09-08-01" \
  -d '{"thresholdHal": 10000, "amountHal": 50000}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X POST https://volai.cz/v1/credit/auto-topup/card \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X DELETE https://volai.cz/v1/credit/auto-topup/card \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "removed": true
}

curl https://volai.cz/v1/account/spend-cap \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "spendCap": {
    "enabled": true,
    "capHal": 500000,
    "warnShare": 0.8,
    "inboundAboveCap": false,
    "month": "2026-11",
    "monthSpendHal": 183400,
    "remainingHal": 316600,
    "reached": false,
    "updatedAt": 1793520000000
  }
}

curl -X PUT https://volai.cz/v1/account/spend-cap \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capHal": 500000, "warnShare": 0.8, "inboundAboveCap": false}'

{
  "spendCap": {
    "enabled": true,
    "capHal": 500000,
    "warnShare": 0.8,
    "inboundAboveCap": false,
    "month": "2026-11",
    "monthSpendHal": 183400,
    "remainingHal": 316600,
    "reached": false,
    "updatedAt": 1793520000000
  }
}

curl -X DELETE https://volai.cz/v1/account/spend-cap \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "spendCap": {
    "enabled": false,
    "capHal": null,
    "warnShare": null,
    "inboundAboveCap": null,
    "month": "2026-11",
    "monthSpendHal": 183400,
    "remainingHal": null,
    "reached": false,
    "updatedAt": null
  }
}

curl "https://volai.cz/v1/billing/documents?limit=2" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "documents": [
    {
      "id": "inv_4kX9mQ2pRtLz",
      "number": "VF2026000042",
      "issuedAt": 1757280000000,
      "taxableAt": 1757280000000,
      "netHal": 50000,
      "vatHal": 10500,
      "grossHal": 60500,
      "vatRatePercent": 21,
      "reverseCharge": false,
      "kind": "invoice",
      "description": "Prepaid credit for volai telecommunications services",
      "customer": { "name": "Radek Klein", "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
      "paymentRef": "pi_3PQr7s2eZvKYlo2C1a2b3c4d",
      "pdfUrl": "https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf"
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "document": {
    "id": "inv_4kX9mQ2pRtLz",
    "number": "VF2026000042",
    "issuedAt": 1757280000000,
    "taxableAt": 1757280000000,
    "netHal": 50000,
    "vatHal": 10500,
    "grossHal": 60500,
    "vatRatePercent": 21,
    "reverseCharge": false,
    "kind": "invoice",
    "description": "Prepaid credit for volai telecommunications services",
    "customer": { "name": "Radek Klein", "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "paymentRef": "pi_3PQr7s2eZvKYlo2C1a2b3c4d",
    "pdfUrl": "https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf"
  }
}

curl https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -o invoice.pdf

Abonament miesięczny

Abonament miesięczny obciąża zapisaną kartę raz w miesiącu i dodaje miesięczne saldo, które jest zużywane przed saldem z doładowań i wygasa z końcem okresu. Każdy poziom ma cenę i większe miesięczne saldo, oba bez VAT (zob. tiers w GET /v1/subscription). Pieniądze ruszają tylko wtedy, gdy przy karcie jest człowiek: to API nigdy samo nie rozpoczyna ani nie zwiększa płatności cyklicznych. Rozpoczęcie abonamentu, opłacenie nieudanego odnowienia i wymiana karty zwracają link Stripe Checkout, a podniesienie poziomu, wznowienie abonamentu ustawionego na zakończenie lub przejście na doładowania z karty zwraca confirmUrl, który człowiek musi potwierdzić w portalu. Pełny opis znajduje się pod /docs/kredit.

curl https://volai.cz/v1/subscription \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "subscription": {
    "tier": "990",
    "status": "active",
    "periodStart": "2026-10-17T08:00:00.000Z",
    "periodEnd": "2026-11-17T09:00:00.000Z",
    "monthlyCreditHal": 130000,
    "monthlyRemainingHal": 98500,
    "exhaustionMode": "topup",
    "cancelAtPeriodEnd": false,
    "nextTier": null,
    "card": {
      "brand": "visa",
      "last4": "4242"
    }
  },
  "tiers": [
    {
      "id": "490",
      "priceHal": 49000,
      "creditHal": 60000
    },
    {
      "id": "990",
      "priceHal": 99000,
      "creditHal": 130000
    },
    {
      "id": "1990",
      "priceHal": 199000,
      "creditHal": 280000
    }
  ],
  "topupBalanceHal": 8500,
  "available": false,
  "recommendation": {
    "spendHal": 105500,
    "days": 30,
    "cheapestPath": "plan",
    "tier": "490",
    "tierTotalHal": 94500,
    "savingsHal": 11000,
    "worthIt": true,
    "steady": true,
    "options": [
      {
        "path": "per_second",
        "tier": null,
        "totalHal": 105500
      },
      {
        "path": "plan",
        "tier": "490",
        "totalHal": 94500
      },
      {
        "path": "plan",
        "tier": "990",
        "totalHal": 99000
      },
      {
        "path": "plan",
        "tier": "1990",
        "totalHal": 199000
      }
    ]
  },
  "previousPeriod": {
    "tier": "990",
    "periodStart": "2026-09-17T08:00:00.000Z",
    "periodEnd": "2026-10-17T08:00:00.000Z",
    "creditHal": 130000,
    "usedHal": 105500,
    "usedPercent": 81,
    "overHal": 0,
    "expiredHal": 24500,
    "exhaustionMode": "topup",
    "exhaustedAt": null
  }
}

curl -X POST https://volai.cz/v1/subscription/checkout \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: plan-2026-10-17-01" \
  -d '{"tier": "990", "exhaustionMode": "cap", "consumerConsent": true}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X PATCH https://volai.cz/v1/subscription \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": "490"}'

{
  "subscription": {
    "tier": "990",
    "status": "active",
    "periodStart": "2026-10-17T08:00:00.000Z",
    "periodEnd": "2026-11-17T09:00:00.000Z",
    "monthlyCreditHal": 130000,
    "monthlyRemainingHal": 98500,
    "exhaustionMode": "topup",
    "cancelAtPeriodEnd": false,
    "nextTier": "490",
    "card": {
      "brand": "visa",
      "last4": "4242"
    }
  }
}

curl -X POST https://volai.cz/v1/subscription/pay \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: plan-pay-2026-11-18-01"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X POST https://volai.cz/v1/subscription/card \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: plan-card-2026-11-18-01"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

Zadania

Zadanie dzwoni do listy odbiorców jednym agentem, według reguł ustalonych z góry (budżet, okno dzwonienia, liczba prób) - nic nie jest wykręcane, dopóki sami go nie uruchomią Państwo (POST .../start). Pełny przewodnik z importem CSV, statusami i globalną przepustowością znajduje się pod /docs/ukoly. Agent z produktem "numer do połączeń i SMS" dzwoni w kampanii wyłącznie na numery czeskie (+420) i z numeru trwa naraz tylko jedno połączenie: kontakt z jakimkolwiek innym numerem trafia do przeglądu, podczas gdy zadanie dzwoni dalej do pozostałych, a zajęty numer sprawia, że zadanie chwilę czeka.

curl https://volai.cz/v1/tasks \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "tasks": [
    {
      "id": "task_9f3a2c1d",
      "name": "Payment reminder - September",
      "agentId": "ag_4e91a2f0",
      "taskType": "custom",
      "purpose": "standard",
      "source": "manual",
      "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
      "maxAttempts": 2,
      "maxDurationSecs": 120,
      "budgetHal": 50000,
      "reservedBudgetHal": 0,
      "spentHal": 0,
      "status": "draft",
      "revision": 0,
      "createdAt": 1757280000000,
      "updatedAt": 1757280000000,
      "items": [
        { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
      ]
    }
  ]
}

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/registrations \
  -H "Authorization: Bearer vk_YOUR_KEY"

{"registration":null,"operation":null}

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/registrations \
  -H "Authorization: Bearer vk_YOUR_KEY" -H "Content-Type: application/json" \
  --data-binary @petcenter-manifest-operation.json

{"registration":{"manifestSha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","taskCount":19,"updatedAt":1791802800000},"operation":{"operationId":"registration-2026-10-12","manifestSha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","taskCount":19,"acceptedAt":1791802800000,"replayed":false}}

curl 'https://volai.cz/v1/outbound/dispatch-scopes/petcenter/pauses?operationId=pause-batch-2026-10-12-01' \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "operation": {
    "operationId": "pause-batch-2026-10-12-01",
    "manifestSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "requestHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "tasks": [{ "taskId": "task_abcdefgh", "revision": 12 }],
    "acceptedAt": 1791802800000,
    "complete": true,
    "outcomes": [{ "taskId": "task_abcdefgh", "outcome": "paused", "revision": 13 }]
  }
}

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/pauses \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"pause-batch-2026-10-12-01","manifestSha":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","tasks":[{"taskId":"task_abcdefgh","revision":12}]}'

{
  "operation": {
    "operationId": "pause-batch-2026-10-12-01",
    "manifestSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "requestHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "tasks": [{ "taskId": "task_abcdefgh", "revision": 12 }],
    "acceptedAt": 1791802800000,
    "complete": true,
    "outcomes": [{ "taskId": "task_abcdefgh", "outcome": "paused", "revision": 13 }]
  }
}

curl -X POST https://volai.cz/v1/tasks \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-2026-09-08-01" \
  -d '{
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "maxAttempts": 2,
    "budgetHal": 50000,
    "recipients": [
      { "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" } }
    ]
  }'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 50000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 0,
    "createdAt": 1757280000000,
    "updatedAt": 1757280000000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl https://volai.cz/v1/tasks/task_9f3a2c1d \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 50000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 0,
    "createdAt": 1757280000000,
    "updatedAt": 1757280000000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ],
    "issues": []
  }
}

curl -X PATCH https://volai.cz/v1/tasks/task_9f3a2c1d \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 0, "budgetHal": 80000}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 1,
    "createdAt": 1757280000000,
    "updatedAt": 1757280060000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/start \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-start-2026-09-08-01" \
  -d '{"revision": 1}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "running",
    "revision": 2,
    "createdAt": 1757280000000,
    "updatedAt": 1757280120000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/pause \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 2}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "status": "paused",
    "revision": 3,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 684,
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "createdAt": 1757280000000,
    "updatedAt": 1757280180000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "completed", "attempts": [{ "id": "attempt_5d4c3b", "startedAt": 1757280100000, "finishedAt": 1757280160000, "providerCallId": "c_7a2b9c1d", "outcome": "completed", "costHal": 684 }], "actualCostHal": 684 }
    ]
  }
}

curl "https://volai.cz/v1/tasks/task_reminder_9f3a/items/item_1a2b3c/reminder-call?callId=c_reminder_7e2d" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "reminderCall": {
    "callId": "c_reminder_7e2d",
    "tenantId": "u_4a8d2c",
    "agentId": "ag_4e91a2f0",
    "taskId": "task_reminder_9f3a",
    "taskItemId": "item_1a2b3c",
    "dispatchIntentId": "dispatch_8d2a4f",
    "purpose": "coupon_reminder",
    "phoneSha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "direction": "out",
    "status": "no_answer",
    "startedAt": 1791882000000,
    "durationSecs": 0,
    "priceHal": 0,
    "endReason": "no_answer",
    "optOutRequested": false,
    "hasConversation": false,
    "quality": {
      "turnFailures": { "observed": false, "count": null },
      "toolFailures": { "observed": false, "count": null },
      "dismissReminder": { "observed": true, "invoked": false }
    }
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/items/item_1a2b3c/resolve \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "retry", "revision": 5}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 2400,
    "spentHal": 0,
    "status": "needs_attention",
    "revision": 6,
    "createdAt": 1757280000000,
    "updatedAt": 1757280240000,
    "reviewReason": "billing_unknown",
    "items": [
      {
        "id": "item_1a2b3c",
        "phone": "+420777123456",
        "variables": { "jmeno": "Jana Novakova" },
        "paymentStatus": "not_applicable",
        "status": "pending",
        "attempts": [
          { "id": "attempt_7c2d", "startedAt": 1757280180000, "finishedAt": 1757280230000, "providerCallId": "c_late_price", "outcome": "completed" }
        ],
        "reviewReason": "billing_unknown",
        "providerCallId": "c_late_price",
        "estimatedCostHal": 2400,
        "reservedCostHal": 2400
      }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/reconcile \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "status": "completed",
    "revision": 3,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 684,
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "createdAt": 1757280000000,
    "updatedAt": 1757280240000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "completed", "attempts": [{ "id": "attempt_5d4c3b", "startedAt": 1757280100000, "finishedAt": 1757280160000, "providerCallId": "c_7a2b9c1d", "outcome": "completed", "costHal": 684 }], "actualCostHal": 684 }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/process \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-process-2026-10-08-tick-001" \
  -d '{"revision": 2}'

{
  "status": "idle",
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "purpose": "standard",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "running",
    "revision": 2,
    "createdAt": 1757280000000,
    "updatedAt": 1757280120000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [], "nextAttemptAt": 1757280180000 }
    ]
  }
}

curl -X DELETE "https://volai.cz/v1/tasks/task_9f3a2c1d?revision=3" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "deleted": true
}

curl -X POST https://volai.cz/v1/tasks/csv-preview \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv": "phone,jmeno\n+420777123456,Jana Novakova\nneplatne,Petr Svoboda\n"}'

{
  "headers": ["phone", "jmeno"],
  "delimiter": ",",
  "rows": [
    { "line": 2, "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "errors": [] },
    { "line": 3, "variables": { "jmeno": "Petr Svoboda" }, "errors": [{ "field": "phone", "message": "Invalid phone number", "row": 3 }] }
  ],
  "validRows": [
    { "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" } }
  ],
  "errors": [{ "field": "phone", "message": "Invalid phone number", "row": 3 }]
}

Numery

curl "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{"callbackRouting":{"agentIds":["ag_campaign"],"lookbackSecs":604800}}

curl -X PUT "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentIds":["ag_campaign"],"lookbackSecs":604800}'

{"callbackRouting":{"agentIds":["ag_campaign"],"lookbackSecs":604800},"engineSyncRequired":true}

curl https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "numbers": [
    {
      "e164": "+420601234567",
      "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
      "monthlyFeeHal": 2500,
      "boughtAt": 1756111640000,
      "region": "objednavka",
      "regionLabel": "Czech number",
      "billingMonths": 1
    }
  ]
}

curl "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "objednavka",
    "regionLabel": "Czech number",
    "billingMonths": 1
  }
}

curl -X POST https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "number": {
    "e164": "+420266266647",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "praha",
    "regionLabel": "Prague",
    "billingMonths": 1
  }
}

curl https://volai.cz/v1/numbers/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "offers": [
    { "offerId": "praha", "label": "Prague", "joined": false, "available": true },
    { "offerId": "brno", "label": "Brno", "joined": true, "available": false },
    { "offerId": "internet", "label": "Internet number", "joined": false, "available": true },
    { "offerId": "bratislava", "label": "Bratislava", "joined": false, "available": true }
  ]
}

curl -X POST https://volai.cz/v1/numbers/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offerId": "brno"}'

{
  "joined": true
}

curl -X DELETE https://volai.cz/v1/numbers/waitlist/brno \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "left": true
}

curl "https://volai.cz/v1/numbers/available?region=brno" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "region": "brno",
  "numbers": ["+420510510129", "+420510510132"],
  "regions": [
    {
      "id": "praha",
      "label": "Prague",
      "description": "A landline with a Prague area code.",
      "numbers": ["+420266266643", "+420266266645"]
    },
    {
      "id": "brno",
      "label": "Brno",
      "description": "A landline with a Brno area code.",
      "numbers": ["+420510510129", "+420510510132"]
    },
    {
      "id": "internet",
      "label": "Internet number",
      "description": "Area code 910, not tied to any region - works from anywhere.",
      "numbers": ["+420910084099"]
    },
    {
      "id": "bratislava",
      "label": "Bratislava",
      "description": "A Slovak number with the Bratislava area code +421 2. Billed three months upfront.",
      "numbers": ["+421222205798"]
    }
  ]
}

curl "https://volai.cz/v1/numbers/address-options?psc=70200&obec=554821&cobce=413950" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "obce": [{ "value": "554821", "label": "Ostrava" }],
  "casti": [{ "value": "413950", "label": "Moravská Ostrava" }],
  "ulice": [{ "value": "353710", "label": "28. října" }],
  "cp": [],
  "recap": null
}

curl -G https://volai.cz/v1/numbers/address-options \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  --data-urlencode "query=Nádražní 100, 702 00 Ostrava"

{
  "obce": [],
  "casti": [],
  "ulice": [],
  "cp": [],
  "recap": "28. října 102/1, Ostrava, 70200",
  "selection": {
    "psc": "70200",
    "obec": "554821",
    "cobce": "413950",
    "ulice": "353710",
    "cp": "3180026"
  }
}

{
  "obce": [
    { "value": "554821", "label": "Ostrava" },
    { "value": "554813", "label": "Fulnek" }
  ],
  "casti": [],
  "ulice": [],
  "cp": [],
  "recap": null,
  "selection": { "psc": "70200", "obec": "", "cobce": "", "ulice": "", "cp": "" },
  "ambiguousLevel": "obec",
  "message": "The given address is ambiguous - choose the municipality (obec) from the options. Repeat the query WITHOUT query and with the step parameters: psc=70200, obec=<value from the options>."
}

curl -X POST https://volai.cz/v1/numbers/orders \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"psc":"70200","obec":"554821","cobce":"413950","ulice":"353710","cp":"3180026"}'

{
  "order": {
    "id": "Xa3Kd9pQmR2v",
    "status": "pending",
    "address": "70200",
    "createdAt": 1756111640000,
    "updatedAt": 1756111640000
  }
}

curl https://volai.cz/v1/numbers/orders \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "orders": [
    {
      "id": "Xa3Kd9pQmR2v",
      "status": "done",
      "address": "28. října 102/1, Ostrava, 70200",
      "e164": "+420596123456",
      "createdAt": 1756111640000,
      "updatedAt": 1756118840000
    }
  ]
}

curl -X POST https://volai.cz/v1/numbers/orders/Xa3Kd9pQmR2v/cancel \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "order": {
    "id": "Xa3Kd9pQmR2v",
    "status": "cancelled",
    "address": "28. října 102/1, Ostrava, 70200",
    "createdAt": 1756111640000,
    "updatedAt": 1756112240000
  }
}

curl -X DELETE "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "agent", "agentId": "ag_kx91fa2b"}}'

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "objednavka",
    "regionLabel": "Czech number",
    "billingMonths": 1
  }
}

curl "https://volai.cz/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

curl "https://volai.cz/v1/numbers/+420601234567/sip/status" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "target": { "kind": "own_line", "host": null },
  "registration": { "registered": true },
  "lastInbound": {
    "at": 1756118900000,
    "status": "completed",
    "from": "+420777123456",
    "recent": true
  }
}

Wiadomości

curl "https://volai.cz/v1/messages?limit=20&direction=all" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "messages": [
    {
      "id": "msg_5b7e0d93",
      "to": "+420777123456",
      "from": "+420770112233",
      "body": "Potwierdzone, do zobaczenia w piątek o 10:00. - My App",
      "status": "sent",
      "failReason": null,
      "priceHal": 190,
      "segments": 1,
      "createdAt": 1756112200000,
      "source": "api",
      "direction": "out",
      "smsNumber": "+420770112233",
      "deliveryStatus": "delivered"
    },
    {
      "id": "msg_3d9b5e71",
      "to": "+420770112233",
      "from": "+420777123456",
      "body": "Dziękuję, przyjdę w piątek o 10:00.",
      "status": "received",
      "failReason": null,
      "priceHal": 0,
      "segments": 1,
      "createdAt": 1756111900000,
      "source": "inbound",
      "direction": "in",
      "smsNumber": "+420770112233",
      "deliveryStatus": null
    },
    {
      "id": "msg_7c1f9a2e",
      "to": "+420777123456",
      "from": "volai",
      "body": "Pozdrowienia z volai! - My App",
      "status": "sent",
      "failReason": null,
      "priceHal": 136,
      "segments": 1,
      "createdAt": 1756111500000,
      "source": "api",
      "direction": "out",
      "smsNumber": null,
      "deliveryStatus": null
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/messages" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_MESSAGES_ID" \
  -d '{"to":"+420777123456","body":"Pozdrowienia z volai! - My App"}'

{
  "id": "msg_7c1f9a2e",
  "status": "sent",
  "priceHal": 136,
  "segments": 1
}

status wiadomości: pending (zapisana, jeszcze w trakcie wysyłania), sent (operator przyjął wiadomość do wysłania, w tym wiadomości w kolejce; to nie jest potwierdzenie doręczenia), failed (operator ją odrzucił, w przypadku wiadomości wysłanej z numeru komórkowego możliwe, że dopiero później - nie jest naliczana, każda już pobrana opłata jest zwracana, priceHal 0), received (wiadomość odebrana na Państwa numerze komórkowym lub produkcie "numer do połączeń i SMS", zawsze z direction: "in" i priceHal 0) oraz unknown (operator nie potwierdził przyjęcia, zwykle dlatego, że jego odpowiedź przekroczyła czas) - jest nadal naliczana w pełnej cenie, ponieważ wiadomość mogła zostać dostarczona. W przypadku wiadomości wysłanej z numeru komórkowego unknown może jeszcze zmienić się samo: na sent z deliveryStatus, gdy operator potwierdzi wiadomość, albo na failed ze zwrotem opłaty, jeśli ją odrzuci. Po otrzymaniu unknown prosimy nie wysyłać wiadomości ślepo ponownie - prosimy skontaktować się z pomocą techniczną, a zwrócimy każdą zdublowaną opłatę.

Dla status: "failed" otrzymują Państwo także failReason: unsupported_characters (emoji lub znak, którego sieć nie może dostarczyć), unsupported_recipient (sieć nie przyjmuje numeru), forbidden_sender i low_balance (błąd po naszej stronie), gateway_failed (brama operatora), network_rejected (inne odrzucenie), opted_out (odbiorca odpowiedział STOP na Państwa numer komórkowy). Dla innych statusów ma wartość null.

deliveryStatus (delivered lub undelivered) to raport doręczenia operatora i istnieje tylko dla wiadomości wysłanych z Państwa numeru komórkowego. Ma wartość null dla wiadomości wysłanych pod wspólną nazwą SMSinfo, która nie ma raportów doręczenia, dla wiadomości wysłanych z produktu "numer do połączeń i SMS", który ich również nie ma, oraz dla wiadomości odebranych. sent nadal oznacza tylko, że operator przyjął wiadomość, i nie dowodzi doręczenia. Wiadomość z undelivered jest nadal naliczana, ponieważ operator ją przyjął. Jeśli operator później zgłosi niepowodzenie, status wiadomości zmieni się na failed, priceHal spadnie do 0, a opłata zostanie zwrócona na saldo. Raport doręczenia przychodzi, gdy tylko operator go zgłosi; jeśli powiadomienie o statusie nie dotrze, uzupełnia go regularna kontrola co 15 minut. Jeśli operator nigdy go nie zgłosi, pozostaje null.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "fromNumber": "+420770112233", "body": "Potwierdzone, do zobaczenia w piątek o 10:00. - My App"}'

{
  "id": "msg_5b7e0d93",
  "status": "sent",
  "priceHal": 190,
  "segments": 1
}

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Příliš žluťoučký kůň úpěl ďábelské ódy - a tahle věta má přes sedmdesát znaků, takže spadne do druhého segmentu."}'

{
  "id": "msg_9a3f1c7d",
  "status": "sent",
  "priceHal": 272,
  "segments": 2
}

curl https://volai.cz/v1/messages/msg_7c1f9a2e \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "message": {
    "id": "msg_7c1f9a2e",
    "to": "+420777123456",
    "from": "volai",
    "body": "Pozdrowienia z volai! - My App",
    "status": "sent",
    "failReason": null,
    "priceHal": 136,
    "segments": 1,
    "createdAt": 1756111500000,
    "source": "api",
    "direction": "out",
    "smsNumber": null,
    "deliveryStatus": null
  }
}

Numery komórkowe

curl https://volai.cz/v1/sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "smsNumbers": [
    {
      "number": "+420770112233",
      "status": "active",
      "createdAt": 1756111640000,
      "monthlyFeeHal": 29000,
      "nextChargeAt": 1758703640000,
      "dailySendLimit": 20,
      "dailySendRemaining": 17,
      "dailySendResetsAt": 1756198040000
    }
  ]
}

curl -X POST "https://volai.cz/v1/sms-numbers" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_SMS_NUMBERS_ID"

{
  "smsNumber": {
    "number": "+420770112233",
    "status": "active",
    "createdAt": 1756111640000,
    "monthlyFeeHal": 29000,
    "nextChargeAt": 1758703640000,
    "dailySendLimit": 20,
    "dailySendRemaining": 20,
    "dailySendResetsAt": null
  }
}

curl -X DELETE "https://volai.cz/v1/sms-numbers/+420770112233" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

Numer do połączeń i SMS

Produkt "numer do połączeń i SMS" to trzeci rodzaj numeru obok numerów głosowych i numerów komórkowych: praski numer stacjonarny (+420 2xx), który odbiera połączenia i SMS i z którego Państwa agent wykonuje połączenia i wysyła SMS. Numer głosowy nie może odbierać SMS, a numer komórkowy nie ma połączeń. Numer jest zarejestrowany u operatora na nazwę dostawcy usługi volai, a Państwo z niego korzystają; po zamówieniu jest zwykle aktywny w ciągu 1 dnia roboczego, najpóźniej w ciągu 48 godzin, a opłata jest pobierana dopiero po aktywacji. Połączenia przychodzące odbiera agent działający na własnym silniku głosowym volai, a numer obsługuje najwyżej dwa jednoczesne połączenia. Odbieranie SMS zweryfikowano w sieci O2 i nie gwarantujemy kodów weryfikacyjnych z usług. Z country w treści zamówienia otrzymują Państwo zamiast numeru praskiego produkt "numer w innym kraju": numer stacjonarny, który odbiera połączenia (odpowiada na nie agent), ale nie ma SMS (ani ich nie odbiera, ani nie wysyła) i który dzwoni tylko do kraju numeru i do Czech. Cena zależy od kraju (odczytują ją Państwo z monthlyFeeHal kraju w GET /v1/voice-sms-numbers/countries), a pozostałe zasady są takie same jak dla numeru praskiego; numer jest rejestrowany u operatora na nazwę dostawcy z adresem w tym kraju i jest aktywny zwykle w ciągu 1 dnia roboczego, najpóźniej w ciągu 3 dni roboczych (w ciągu godziny dla krajów bez rejestracji). Kraje, w których można zamawiać, się zmieniają, dlatego należy odczytywać je z GET /v1/voice-sms-numbers/countries (MCP list_voice_sms_countries) i nigdy nie wymieniać ich z pamięci. Zamawiają go Państwo sami w portalu, przez REST (POST /v1/voice-sms-numbers) lub MCP (order_voice_sms_number), po pierwszym doładowaniu salda. Gdy zamówienia są tymczasowo wstrzymane, zamówienie zwraca voice_sms_numbers_unavailable i nic nie jest naliczane; prosimy spróbować później lub skontaktować się z pomocą techniczną.

curl https://volai.cz/v1/voice-sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "voiceSmsNumbers": [
    {
      "number": "+420292000001",
      "country": "CZ",
      "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
      "status": "active",
      "routing": { "mode": "agent", "agentId": "ag_9f3a2b7c4d1e", "sipTarget": "engine", "hasSipPassword": false },
      "monthlyFeeHal": 4900,
      "smsFromNumberHal": 250,
      "nextChargeAt": 1758703640000,
      "smsInboundReady": true,
      "createdAt": 1756101640000,
      "activatedAt": 1756111640000
    }
  ],
  "pendingOrders": [{ "createdAt": 1758790000000, "country": "CZ" }]
}

curl https://volai.cz/v1/voice-sms-numbers/countries \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "countries": [
    {
      "country": "CZ",
      "name": "Czechia",
      "prefix": "+420",
      "numberKind": "landline, Prague (+420 2)",
      "sms": true,
      "outboundTo": ["CZ"],
      "activation": "within_business_days",
      "monthlyFeeHal": 4900
    },
    {
      "country": "GB",
      "name": "United Kingdom",
      "prefix": "+44",
      "numberKind": "landline, London (+44 20)",
      "sms": false,
      "outboundTo": ["CZ"],
      "activation": "within_hour",
      "monthlyFeeHal": 2900
    }
  ]
}

# Example: a number in another country (choose the country from GET /v1/voice-sms-numbers/countries)
curl -X POST https://volai.cz/v1/voice-sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"GB"}'

{
  "voiceSmsNumber": {
    "number": "+442000000001",
    "country": "GB",
    "capabilities": { "calls": true, "sms": false, "outboundTo": ["CZ"] },
    "status": "awaiting_registration",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 2900,
    "smsFromNumberHal": null,
    "nextChargeAt": null,
    "smsInboundReady": false,
    "createdAt": 1756101640000,
    "activatedAt": null
  }
}

curl -X POST "https://volai.cz/v1/voice-sms-numbers" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_VOICE_SMS_NUMBERS_ID"

{
  "voiceSmsNumber": {
    "number": "+420292000001",
    "country": "CZ",
    "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
    "status": "awaiting_registration",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 4900,
    "smsFromNumberHal": 250,
    "nextChargeAt": null,
    "smsInboundReady": false,
    "createdAt": 1756101640000,
    "activatedAt": null
  }
}

curl "https://volai.cz/v1/voice-sms-numbers/+420292000001" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "voiceSmsNumber": {
    "number": "+420292000001",
    "country": "CZ",
    "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
    "status": "active",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 4900,
    "smsFromNumberHal": 250,
    "nextChargeAt": 1758703640000,
    "smsInboundReady": true,
    "createdAt": 1756101640000,
    "activatedAt": 1756111640000
  }
}

curl -X PATCH "https://volai.cz/v1/voice-sms-numbers/+420292000001" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing":{"mode":"agent","agentId":"ag_9f3a2b7c4d1e"}}'

{
  "voiceSmsNumber": {
    "number": "+420292000001",
    "country": "CZ",
    "capabilities": { "calls": true, "sms": true, "outboundTo": ["CZ"] },
    "status": "active",
    "routing": { "mode": "agent", "agentId": "ag_9f3a2b7c4d1e", "sipTarget": "engine", "hasSipPassword": false },
    "monthlyFeeHal": 4900,
    "smsFromNumberHal": 250,
    "nextChargeAt": 1758703640000,
    "smsInboundReady": true,
    "createdAt": 1756101640000,
    "activatedAt": 1756111640000
  }
}

curl -X POST "https://volai.cz/v1/voice-sms-numbers/+420292000001/cancel" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "cancelled": true
}

curl -X DELETE "https://volai.cz/v1/voice-sms-numbers/+420292000001" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

Połączenia

curl "https://volai.cz/v1/calls?limit=20" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "calls": [
    {
      "id": "c_8f2ac1d4",
      "direction": "in",
      "from": "+420777123456",
      "to": "+420601234567",
      "status": "completed",
      "startedAt": 1756111400000,
      "durationSecs": 47,
      "priceHal": 236,
      "agentId": "ag_kx91fa2b",
      "note": null,
      "flag": null,
      "handledAt": null,
      "rating": null,
      "goal": null,
      "hasConversation": true,
      "source": "inbound",
      "kind": "inbound",
      "endReason": "completed",
      "hasRecording": true,
      "data": {
        "name": "Anna Kowalska",
        "coffee_count": 2,
        "urgency": "normal"
      }
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/calls" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_CALLS_ID" \
  -d '{"to":"+420777123456","agentId":"ag_kx91fa2b","variables":{"jmeno_zakaznika":"Jana","cislo_objednavky":"A-42"},"ringingTimeoutSecs":30}'

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+420777123456",
    "systemPrompt": "Jesteś recepcjonistą kawiarni Nula. Przyjmujesz zamówienia na odbiór osobisty, odpowiadasz krótko i uprzejmie.",
    "firstMessage": "Dzień dobry, tu próbny agent volai, w czym mogę pomóc?"
  }'

{
  "id": "c_2f7a91mn",
  "status": "initiated",
  "trial": true,
  "from": "+420266266641"
}

curl -X POST "https://volai.cz/v1/voice-messages" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_VOICE_MESSAGES_ID" \
  -d '{"to":"+420777123456","text":"Alarm: serwer api-1 nie odpowiada od pięciu minut. Prosimy o sprawdzenie jego stanu.","repeat":2}'

{
  "id": "c_k4m8p2q7r1s5",
  "status": "ringing",
  "from": "+420266266641"
}

{
  "call": {
    "id": "c_k4m8p2q7r1s5",
    "direction": "out",
    "from": "+420266266641",
    "to": "+420777123456",
    "status": "completed",
    "kind": "voice_message",
    "durationSecs": 17.4,
    "voiceMessage": {
      "text": "...",
      "repeat": 2,
      "repeatPlayed": 2,
      "completed": true
    }
  }
}

curl -X POST "https://volai.cz/v1/rings" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_RINGS_ID" \
  -d '{"to":"+420777123456","from":"+420601234567","ringSecs":10}'

{
  "id": "c_x7f2k9a1b3c4",
  "status": "initiated",
  "kind": "ring",
  "from": "+420601234567",
  "to": "+420777123456",
  "requestedSecs": 10,
  "priceHal": 25
}

{
  "call": {
    "id": "c_x7f2k9a1b3c4",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "no_answer",
    "startedAt": 1756111640000,
    "durationSecs": 0,
    "priceHal": 25,
    "source": "api",
    "kind": "ring",
    "ring": { "requestedSecs": 10, "outcome": "ended_early", "rangSecs": 2 },
    "note": null,
    "flag": null,
    "handledAt": null,
    "rating": null,
    "goal": null,
    "hasConversation": false,
    "endReason": "no_answer"
  }
}