Napojení

REST API

Kompletní reference API v1. Vše je JSON a chyby mají jednotný tvar. Ceny volai jsou celá čísla v haléřích (přípona Hal); připojené faktury používají nejmenší jednotky uvedené měny.

Autentizace

Každý požadavek nese API klíč v hlavičce Authorization: Bearer vk_... . Klíč získáš v portálu v sekci Přístupy a API (podrobněji v Quickstartu).

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

Celé tohle API má i strojově čitelný popis na GET /openapi.json (OpenAPI 3.1, bez API klíče) - vygeneruj si z něj klienta, kolekci do Postmanu, nebo ho napoj rovnou do n8n.

Formát chyb

Neúspěch má vždy stejný tvar, ať selže cokoli:

{
  "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"
  }
}

Těchhle pět kódů se může objevit prakticky kdekoli - u jednotlivých endpointů níž jsou dopsané jen situační kódy navíc:

400 (neplatný vstup) a 404 (záznam neexistuje) taky můžou přijít prakticky kdekoli, ale jejich code je specifický pro dané pole nebo endpoint - přesný výčet je vždy u konkrétního volání níž. Pár akcí navíc může vrátit 502 (chyba u externího poskytovatele - telefonní síť, ElevenLabs) nebo 503 (dočasně nedostupné, zkus to za chvíli).

Kdo za chybu může: cause a action

Každá chyba nese navíc cause (čtyři hodnoty) a action (jedna anglická věta, co udělat, kterou můžeš uživateli přečíst doslova). cause je strojově čitelná odpověď na otázku, jestli má chybu opravit tvůj kód, tvůj účet, čas, nebo my:

Pro AI agenty (Claude Code, Cursor, vlastní skripty): podle cause řekni uživateli, kdo chybu opraví. U request vyjmenuj pole z message, u account řekni, co v účtu změnit nebo které id zkontrolovat, u busy počkej a zopakuj, a jen u service mluv o problému na straně volai. Nikdy nehlas request, account ani busy jako výpadek volai.

Příčina je určená kódem, ne HTTP statusem: kvóty účtu (agent_limit, tool_limit, api_key_limit, relay_lease_limit) vrací 400, a přesto jsou account; not_found u záznamu je account (z odpovědi nejde poznat, jestli cizí id existuje), u neznámé cesty pod /v1 je request. Úplné přiřazení kódů k příčinám je u každé operace v GET /openapi.json (popis chybových odpovědí).

Hláška u kódu validation říká pole (tečkovaná cesta v těle, například dataFields.0.type), skutečnou hodnotu a přijatý strop, například Field "knowledge" is 210000 characters long, the maximum accepted is 200000. nebo Field "systemPrompt" is required. Produktové limity (60 / 6000 / 300 / 20000 znaků u jména, instrukcí, cíle a podkladů agenta) hlásí vlastní kódy invalid_name, invalid_system_prompt, invalid_goal, invalid_knowledge s přesným číslem. Neznámé pole ve striktních tělech (koncept agenta) vrací Unknown field "revision". Remove it; the documentation lists the accepted fields.

requestId a docsUrl

Úplně každá odpověď v1 (úspěšná i chybová) nese v hlavičce X-Request-Id jedinečné ID požadavku (req_ + 16 hex znaků) - u chyby je stejná hodnota navíc přímo v těle jako requestId. Přehraná idempotentní odpověď (viz Idempotence níž) dostane VLASTNÍ aktuální requestId - hlavička a tělo se u ní nikdy neliší, i když zbytek odpovědi je doslova stejný jako napoprvé. Pošli tohle ID podpoře a najde přesně tenhle jeden požadavek v logu.

Chybové tělo nese navíc docsUrl - odkaz rovnou sem, na tuhle sekci.

U konceptu agenta (viz sekci Koncept agenta níž) chyba revision_conflict nese navíc currentRevision - aktuální revizi. Načti ji přes GET .../draft a porovnej rozdíl, než uložení zopakuješ - neposílej naslepo to samé tělo se stejnou 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"
  }
}

Chyba subscription_confirmation_required (409) nese navíc confirmUrl - odkaz na stránku v portálu, kde člověk přihlášený k účtu potvrdí změnu, která zvyšuje, kolik se smí z uložené karty strhnout (viz PATCH /v1/subscription). Požadavek nic nezměnil; odkaz platí 24 hodin a jde použít jednou.

{
  "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"
  }
}

Hlavičky

Po ověření klíče nese KAŽDÁ odpověď (úspěšná i chybová) hlavičky RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset (vteřin do konce aktuálního okna) - u 429 z limitu API klíče navíc Retry-After se stejným počtem vteřin. 429 rate_limited z limitu odchozích hovorů (POST /v1/calls) nese v Retry-After vlastní čekání do uvolnění toho limitu, když je známé.

401 nese hlavičku WWW-Authenticate: Bearer realm="volai", error="invalid_token" (RFC 6750) - HTTP knihovna z ní pozná důvod selhání, aniž by musela parsovat tělo.

Neznámá cesta a špatná metoda

Neznámá cesta pod /v1 (i holé /v1) vrací JSON 404 se stejným tvarem chyby jako kdekoli jinde - {"error":{"code":"not_found", ...}} - pro všechny metody (GET, POST, PUT, PATCH, DELETE, OPTIONS i HEAD). Výjimka: špatná METODA na EXISTUJÍCÍ cestě (například DELETE /v1/balance) zůstává obyčejná Next.js 405 bez JSON těla - tohle je jediné místo v celém API v1, kde neúspěch nemá popsaný tvar chyby.

Idempotence

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 a POST /v1/subscription/card umí hlavičku Idempotency-Key. Rozsah klíče je globální pro daný API klíč, bez ohledu na HTTP metodu, cestu nebo tělo. Každá odlišná logická akce napříč všemi endpointy a těly proto potřebuje novou hodnotu; stejnou hodnotu použij jen při opakování přesně téhož logického požadavku, typicky po timeoutu, kdy nevíš, jestli první pokus prošel. Do 24 hodin pak dostaneš zpátky přesně tutéž odpověď jako napoprvé, včetně chybové, dopadl-li první pokus chybou, a nic se neodešle ani nezavolá podruhé. Klidně použij ID objednávky ze své appky doplněné o název konkrétní akce. Souběžný požadavek se stejným klíčem, který ještě běží (odpověď se teprve ukládá), vrátí 409 idempotency_in_progress - zkus to prosím za chvíli znovu.

U POST /v1/numbers/orders se klíč trvale spojí s objednávkou ještě před voláním operátora; stejný klíč s jinou adresou vrátí 409 idempotency_conflict. Pokud operátor po nákupu vrátí nejasnou odpověď, může být potřeba kontrola stavu objednávky.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: objednavka-4471" \
  -d '{"to": "+420777123456", "body": "Děkujeme za objednávku."}'

Rate limity

60 požadavků za minutu na jeden API klíč (MCP sdílí stejný limit - používá tentýž klíč). Po překročení přijde 429 a hlavička Retry-After s počtem vteřin do dalšího pokusu.

POST /v1/messages má navíc vlastní strop: nejvýš jedna SMS za 2 vteřiny a 100 SMS denně na účet. Odesílání ze SMS čísla (fromNumber) má navíc denní strop na účet: 20 zpráv v prvních 30 dnech od koupě čísla, potom 50. Kolik ještě zbývá a kdy se limit obnoví, ukazuje GET /v1/sms-numbers (dailySendRemaining, dailySendResetsAt).

Odchozí hovory (POST /v1/calls, relay i zkušební hovor) mají dohromady vlastní strop: 10 hovorů za minutu a 1000 za den na účet, a souběžně můžou běžet nejvýš 2 hovory zabudovaného agenta.

Kolik ti z limitu 60/min zbývá, zjistíš bez čekání na 429 - v hlavičkách RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset, které nese úplně každá odpověď (viz sekci Formát chyb > Hlavičky výš).

Stránkování

GET /v1/messages a GET /v1/calls berou limit (kolik záznamů max - výchozí 50, strop 200 i při vyšší zadané hodnotě) a before (ms timestamp - vrátí jen starší záznamy).

hasMore a nextBefore

Obě odpovědi nesou navíc hasMore (boolean - existuje starší stránka) a nextBefore (razítko posledního vráceného záznamu, nebo null, když hasMore je false). Pro další stránku pošli nextBefore z předchozí odpovědi jako nový before - žádné ruční počítání offsetu.

before je EXKLUZIVNÍ (vrátí jen záznamy starší, ne stejně staré) - poslední záznam předchozí stránky se v další stránce nikdy nezopakuje. Výjimečně mohou mít dva záznamy úplně stejné milisekundové razítko přesně na hranici stránky - v tom vzácném případě může druhý z nich vypadnout. Deduplikuj proto podle id, nespoléhej na to, že stránky nikdy nic nevynechají.

GET /v1/calls?direction=in nebo ?direction=out prohledává historii po dávkách s tvrdým stropem počtu dávek - hasMore: true proto může znamenat i jen to, že jsme prohledali dávky až do stropu a ještě jsme nenarazili na konec historie, ne jistotu další stránky. false naopak vždy znamená, že historie v daném směru doopravdy skončila.

Verzování

Aktuální verze veřejného rozhraní je 1.55.0 (GET /openapi.json v poli info.version - viz odstavec o strojově čitelném popisu API v úvodu stránky výš). Tři pravidla, podle kterých se verze mění:

1. V rámci v1 přibývají jen NEPOVINNÁ pole a nové endpointy - stávající pole nikdy nezmizí, nezmění typ ani význam. Integrace, která čte jen pole, o kterých ví, nikdy nic nerozbije. Jedinou výjimkou byla verze 1.5.1, která u PŘÍCHOZÍCH hovorů přestala vracet answeredBy - pole u nich nikdy nemělo smysluplnou hodnotu (viz Historie změn níž).
2. Povinné pole nebo změna významu existujícího pole přijde vždy jako nová hlavní verze (v2), nikdy jako tichá úprava v1.
3. U konceptu agenta (Koncept agenta výš) vždy posílej zpátky přesně ten objekt, který jsi přečetl z GET .../draft - tělo PUT/POST je .strict(), takže neznámý klíč (třeba z novější verze, kterou tvá integrace ještě nezná) vrátí 400 validation místo tichého zahození.

Historie změn

• 4. 11. 2026 (1.55.0): POST /v1/voice-sms-numbers přijímá volitelné country (ISO 3166-1 alpha-2 velkými písmeny), bez něj se objedná pražské číslo jako dřív. Seznam zemí, které účet smí objednat, vrací GET /v1/voice-sms-numbers/countries a MCP nástroj list_voice_sms_countries; zemi mimo seznam služba odmítne chybou country_not_offered a nic se neúčtuje. Záznamy čísel nesou country a sms, číslo mimo Česko odmítne odeslání SMS. Odchozí hovory jdou jen do ČR, a do země čísla jen tam, kde je zóna country_and_cz zapnutá; ostatní cíle brána odmítne. Nejvýš 2 čísla na zemi.
• 4. 11. 2026 (1.54.0): regions v GET /v1/numbers/available, parametr region v POST /v1/numbers a nástroje search_available_numbers a buy_number nově znají jihocesky, karlovarsky, kralovehradecky, liberecky, moravskoslezsky, olomoucky, pardubicky, plzensky, stredocesky, ustecky, vysocina, zlinsky. Zásoba kraje je malá, takže pool_empty je tu běžnější: použijte join_number_waitlist, nebo order_number_from_region.
• 4. 11. 2026 (1.53.0): Katalog nabídek zná všech 14 krajů. Krajská nabídka (jihocesky, karlovarsky, kralovehradecky, liberecky, moravskoslezsky, olomoucky, pardubicky, plzensky, stredocesky, ustecky, vysocina, zlinsky) se v regions z GET /v1/numbers/available a v popisech MCP objeví, až když je v prodeji; do té doby se odmítne jako neznámý region. Mění se text regionLabel: číslo z kraje má anglický název kraje, například Moravian-Silesian Region.
• 4. 11. 2026 (1.52.1): Hodnota hlavičky se třemi hvězdičkami za sebou (zbytek masky, například Bear***abc) se v PUT /v1/webhook i v set_webhook odmítne chybou invalid_webhook_headers, dřív prošla jen maska celá. Popisy get_webhook, send_test_webhook a pokyny MCP serveru zmiňují headers; testovací událost nese vlastní hlavičky i podle dokumentace. Doplněné limity hodnot (1 až 1000 znaků tisknutelného ASCII) v OpenAPI a na stránce webhooků.
• 3. 11. 2026 (1.52.0): PUT /v1/webhook a MCP set_webhook berou volitelné headers (nejvýš 5 hlaviček, hodnota do 1000 znaků, jen tisknutelné ASCII). GET/PUT /v1/webhook a get_webhook/set_webhook vrací nové pole headers s maskovanými hodnotami (Bear***, bez hlaviček {}). Vynechané headers uložené hlavičky ponechá, {} je smaže a hodnota rovná masce ponechá uloženou. Změna URL na jinou doménu uložené hlavičky zahodí a maska se tam odmítne. Nelze nastavit host, content-type, content-length, volai-signature ani hop-by-hop hlavičky. Hlavičky jdou se všemi událostmi včetně webhook.test, při přesměrování na cizí doménu se neposílají. Nová chyba invalid_webhook_headers (400).
• 3. 11. 2026 (1.51.0): REST POST /v1/voice-messages s tělem {to, text, repeat?} (text 1 až 500 znaků, repeat 1 až 3, výchozí 1; neznámé pole včetně ringingTimeoutSecs skončí chybou validation) vrací {id, status, from} a umí hlavičku Idempotency-Key jako POST /v1/calls. MCP nástroj send_voice_message volá stejnou službu. Výsledek je v GET /v1/calls/{id} jako kind: "voice_message" s blokem voiceMessage (text, repeat, repeatPlayed, completed) a ve webhooku call.completed nebo call.no_answer; e-mailový souhrn hovoru se u hlasové zprávy neposílá. Nové chyby voice_messages_disabled (503, funkce je vypnutá), voice_message_unavailable (503, hlasový motor zprávy neumí přijmout) a email_unverified (403).
• 1. 11. 2026 (1.50.0): REST GET, PUT a DELETE /v1/account/spend-cap (odpověď {spendCap: {enabled, capHal, warnShare, inboundAboveCap, month, monthSpendHal, remainingHal, reached, updatedAt}}; PUT bere capHal v celých haléřích bez DPH od 5 000 do 100 000 000, warnShare od 0,5 do 0,99 s výchozí 0,8 a inboundAboveCap, který se při změně bez pole nepřepíše) a MCP get_spend_cap, set_spend_cap a clear_spend_cap, všechny nad lib/service/spend-cap.ts stejně jako sekce Měsíční strop útraty v Kreditu. Po dosažení stropu odmítají POST /v1/calls, /v1/messages, /v1/rings, /v1/relay, zkušební hovor a vytáčení úloh novou chybou spend_cap_reached (HTTP 402, nic se neúčtuje); příchozí hovor agenta bez inboundAboveCap: true skončí po jedné větě a v hovoru je endReason: spend_cap. Útrata měsíce (Europe/Prague) se počítá u každého účtu, i bez stropu, a zahrnuje i část pokrytou měsíčním kreditem paušálu. Nepočítají se poplatky za čísla, kolo úprav Na klíč a paušál; strop nezastaví rozběhnuté hovory ani CDR zaúčtované po půlnoci, přesměrování bez agenta a odchozí hovory z čísla ve Vlastní SIP ústředně s inboundAboveCap: true. E-maily o varování a dosažení chodí nejvýš jednou za měsíc a po změně stropu se uvolní. REST POST /v1/agents/{id}/draft/knowledge-import s tělem {url} nebo {text, filename} (soubor .txt nebo .md do 1 MB; portál bere soubor do 800 kB), volitelně mode (append výchozí, nebo replace), preview (jen vrátí výsledek, nic nezapíše) a expectedRevision. MCP nástroj import_agent_knowledge (id, url nebo text + filename, stejná volitelná pole) volá stejnou službu lib/service/knowledge-import.ts. Text se zapíše do knowledge KONCEPTU a zdroj do nového pole knowledgeSources (nejvýš 20 zdrojů: url nebo filename, importedAt, chars), které se nově vrací i v tvaru agenta (GET /v1/agents/{id}, seznam i detail). Co se nevejde do 20 000 znaků, se shrne modelem (method: summarized) nebo ořízne (truncated). Chyby: invalid_import_url, private_address, invalid_knowledge, import_too_large, revision_conflict, rate_limited (10 importů za hodinu na účet). Stažená stránka je cizí text: náhled a kontrola zneužití při uložení konceptu ho hlídají, REST ho bez preview rovnou ukládá. REST POST /v1/account/cancellation-request s tělem {reason, note?} (reason je jedna z too_expensive, callers_hang_up, missing_feature, not_needed, other; note nejvýš 500 znaků) a MCP nástroj request_account_cancellation volají lib/service/account-cancellation.ts, tedy stejnou službu jako formulář v Nastavení. Odpověď {cancellationRequest: {reason, note, requestedAt, alreadyRequested}}; opakovaná žádost vrátí původní záznam s alreadyRequested: true (HTTP 200) a nepošle další e-mail. Žádost je nejvýš jedna na účet, účet se z ní nijak nemění a nic se nemaže; majitel volai dostane upozornění s důvodem, zákazník potvrzení v jazyce účtu. Chyby: validation, user_not_found. Když v e-mailu o hovoru klikneš na palec dolů, hodnocení se zapíše hned a na stránce, která se otevře, můžeš jedním formulářem vybrat důvod a připsat poznámku. Dřív šlo jen o pět samostatných tlačítek bez poznámky. Když napíšeš na podpora@volai.cz, přijde ti automatické potvrzení, že zpráva dorazila, s informací, že odpovídáme obvykle do jednoho pracovního dne, a odkazem na stránku stavu. Na adrese volai.cz/duvera (anglicky volai.cz/en/trust) najdeš na jednom místě, kde leží data hovorů, SMS a účtu, kdo se jich dotkne, jak dlouho je držíme, jak je chráníme a co zatím neumíme. Na webu přibývá tlačítko Zavolat z prohlížeče, kterým si ukázkového agenta volai vyzkoušíš hovorem přímo z prohlížeče, bez registrace. Hovor je ukázka, nahrává se a agent mluví česky. Zapínáme ho postupně, takže se může objevit až po čase. public/llms.txt, public/SKILL.md, /docs/api a /docs/mcp (cs i en) odpovídají kódu: create_calendar_event zakládá schůzku jen s confirm: true a kalendář nic nemaže; číslo pro hovory i SMS je v režimu pilotu (voiceSmsNumbersMode() je admin), ostatní účty dostanou voice_sms_numbers_unavailable (platilo do 3. 11. 2026, od té doby je režim on a číslo si objedná každý účet sám). remainingLine zkušebního hovoru uvádí, že se do limitu 3 hovorů za 24 hodin počítá i nezvednutý hovor.
• 1. 11. 2026 (1.49.1): CAMPAIGN_QUOTA_EXPIRES_AT v lib/service/call-quotas.ts je 2026-11-15T23:00:00+01:00 (22:00 UTC; dřív 2026-11-14T23:00:00+01:00), PETCENTER_REMINDER_DISPATCH_END zůstává 2026-11-21T19:55:00+01:00 (18:55 UTC). petcenterCampaignQuotaActive() a tik runPetcenterOutboundTaskTick tedy vytáčejí hlavní kampaň do 15. 11. 22:00 UTC a připomínky coupon_reminder dál do 21. 11. 18:55 UTC. Uložená kvóta agentky kampaně (call-quota:agent) má vlastní validUntil, který se posouvá zvlášť přes PUT /api/admin/call-quotas z 2026-11-14T22:00:00Z na 2026-11-15T22:00:00Z. Ostatní podmínky výjimky (příznak VOLAI_PETCENTER_CALL_QUOTA_ENABLED, účet, agent, odchozí úloha, osm relay jmen) jsou beze změny.
• 30. 10. 2026 (1.49.0): POST /v1/tools, PATCH /v1/tools/{id} a MCP create_tool a update_tool přijímají volitelné pole requireConfirmation (boolean, výchozí false; jiný typ je 400 validation). Odpovědi s nástrojem (GET /v1/tools, GET /v1/tools/{id}, POST, PATCH, MCP list_tools) ho nesou vždy jako boolean; POST /v1/tools/test pole nezná. PATCH bez pole uloženou hodnotu zachová (starší klient ani zastaralá stránka portálu bránu nevypnou), false ji vypne. Motoru se require_confirmation: true posílá jen u nástroje se zapnutou bránou a jen agentovi na motoru v jazyce cs nebo sk, false se výslovně neposílá; agent v en, de, pl i agent na ElevenLabs pole ignoruje a uložení nástroje se kvůli jazyku neodmítá, protože nástroj patří účtu a sdílí ho víc agentů. Úprava nástroje agenty na motoru nepřepisuje: příznak se k nim dostane při dalším uložení agenta (PATCH /v1/agents/{id}) nebo publikaci (POST /v1/agents/{id}/draft/publish). U běžící kampaně opětovná publikace otestovaného konceptu beze změn značku „otestováno“ zachová a úloha poběží dál, ale už s bránou, kterou test nepokryl; přímé PATCH /v1/agents/{id} značku zruší a úloha skončí s agent_version_changed. PATCH měnící jen requireConfirmation nevolá ElevenLabs a adresu nástroje znovu neověřuje (žádný DNS lookup), takže bránu jde přepnout i při výpadku domény nástroje. Brána čte jen poslední repliku volajícího a otázku agenta nezná: zachytí nejasný souhlas, ne každé „ano“ řečené na jinou otázku. Portál: editor nástroje (/agent/nastroje/novy a /agent/nastroje/[id]) ukládá volbu přepínačem Vyžadovat jasný souhlas volajícího do téhož pole; skrytý příznak formuláře odliší vypnutou volbu od formuláře, který přepínač neznal, takže zastaralá stránka bránu tiše nevypne, a po uložení změněné brány formulář řekne, že u běžícího agenta začne platit až po jeho publikování. Metoda, typ a zdroj parametru se odesílají ze stavu formuláře a popis je řízené pole, protože React 19 po každé formulářové akci formulář vrací do výchozího stavu a dřív se při druhém uložení po chybě poslala první možnost výběru a starý popis. GET /v1/subscription a MCP get_subscription: available říká, jestli jde právě teď zapnout NOVÝ paušál, a je true jen když je nabídka pro účet zapnutá a účet nemá běžící paušál (active, past_due); jinak je false. Dřív bylo true i u předplatitele, přestože POST /v1/subscription/checkout vrátil 409 subscription_exists. Po skončení paušálu (canceled) je zase true. Kdo podle available poznával, jestli účet paušál má, čte subscription. recommendation na available nezávisí a předplatitel ji dostává dál. PATCH /v1/subscription a MCP update_subscription: stupeň, na který účet už přechází (nextTier), je splněný požadavek (200, ne 400 invalid_tier), takže stejné tělo jde po výpadku uprostřed poslat znovu a dokončí zbytek. Výjimky: dnešní stupeň bez naplánované změny zůstává invalid_tier; návrat na dnešní stupeň (zruší naplánovanou změnu) se při opakování jako splněný nebere a skončí invalid_tier; u paušálu zrušeného ke konci období samotný tier dál vrací invalid_state (v těle s cancelAtPeriodEnd: true je to opakování a projde). invalid_state je nově uvedený i v chybách PATCH /v1/subscription v OpenAPI a v dokumentaci. GET /v1/balance a MCP get_balance: upozornění subscription_exhausted_topup, subscription_cap_reached a subscription_runway nesou nové volitelné pole cancelAtPeriodEnd: true (jen když je pravda: paušál se neobnoví, renewsAt je konec paušálu a nový měsíční kredit nepřijde). Formát renewsAt (epoch ms) se nemění a je zdokumentovaný jako tentýž okamžik jako subscription.periodEnd (ISO 8601). E-maily o neprošlé obnově a o konci paušálu mají u účtu bez uložené karty vlastní znění (karta chybí, nic nebylo strženo). Odchozí hovor agenta na motoru, který zůstal ringing nebo initiated bez conversationId a který watchdog (nebo reconcile úlohy) po dvou hodinách uzavřel jako failed s cenou 0, se v úloze nově chová jako relay_not_routed: pokus má items[].attempts[].countsAsAttempt: false a errorCode: "no_provider_report", nespotřebuje maxAttempts ani pořadí politiky lorela_enterprise, rezervace rozpočtu se vrátí, nic se nestrhne a kontakt dostane nextAttemptAt nejdřív za 60 sekund. Pokusy relay_not_routed a no_provider_report se v sérii sčítají: po třetím nepočítaném pokusu za sebou jde kontakt do review s reviewReason podle posledního z nich, tedy call:no_provider_report; dřív jen tehdy, když další pokus nevychází před expiresAt nebo ho politika lorela_enterprise nedovolí. Hovor, kterému pozdní post-call doplnil conversationId, motor viděl, takže se počítá jako dosud. Položky, které takový hovor poslal ke kontrole dřív (call:failed, s politikou call:unknown), se samy neobnovují. Pole errorCode a reviewReason jsou volné řetězce, přibyla jen nová hodnota; integrace, která z úkolů čte reporty, má počítat s dalším nepočítaným pokusem a dalším důvodem kontroly. Pauza (POST .../pause, u kampaně dávkové pozastavení) mezi zápisem záměru vytočení a voláním poskytovatele nechávala reviewReason: "dispatch_in_flight", aktivní claim, rezervaci a položku in_progress bez hovoru a bez pokusu; start pak vracel task_needs_attention, resolve item_not_resolvable, DELETE task_not_deletable a reconcile nic neměnil. Zpracování úlohy teď po takové pauze záměr, claim i rezervaci uvolní samo a vrátí task_paused (hovor nevznikl): kontakt je znovu pending (nebo failed s volným pokusem) a úloha paused bez reviewReason, takže první start projde. Úklid se při souběžném zápisu (revision_conflict) zopakuje až třikrát, stejně jako úklid u poslední brány před poskytovatelem, jehož výsledek se dřív zahazoval. reconcile (cron, POST /v1/tasks/{id}/reconcile, MCP reconcile_task) navíc uvolní záměr, ke kterému neexistuje záznam hovoru ani výsledek pokusu a jehož claim i pětiminutová rezerva po něm vypršely, tedy nejdřív 15 minut po zahájení vytáčení (claim žije 10 minut): vrátí rezervaci a kontakt zařadí mezi čekající, ověřený callback kontakt dokončí. Úloha, kterou mezitím zastavil vypršený claim (dispatch_claim_expired), skončí paused bez důvodu a musí se znovu spustit (start); úloha, kterou claim nezastavil, dál běží. Nejisté vytočení a hovor, který vzniknout mohl, se nemění. Úlohy uvízlé dříve se opraví jedním reconcile a skončí jako paused bez důvodu (pauza byla záměrná), samy se znovu nespustí. Tvar odpovědí se nemění. POST /v1/dnc a MCP add_to_dnc přijmou buď e164 (jedno číslo, odpověď { "added": true, "e164": ... } beze změny), nebo nové pole e164s (1 až 500 čísel, zapsaných jedním příkazem SADD). Obě pole najednou, žádné z nich, prázdné pole i víc než 500 položek je 400 validation; v OpenAPI jsou obě pole nepovinná a pravidlo „právě jedno z nich“ hlídá až validace. Položka v e164s musí být řetězec nejvýš 256 znaků, jiná položka shodí celý požadavek na 400. Odpověď na e164s nese addedCount, alreadyOnListCount, rejectedCount a rejected (položky { index, input, reason: "invalid_number" }, kde input je původní zápis zkrácený na 32 znaků). Součet addedCount + alreadyOnListCount + rejectedCount je vždy počet poslaných položek; číslo zopakované v požadavku nebo zapsané v jiném formátu se počítá jako už na seznamu. Položka, která není platné číslo (i delší text, třeba dvě čísla v jedné buňce), požadavek neshodí, platné položky se přidají vždy, a i vstup samých neplatných položek je 200, proto po každé odpovědi zkontroluj rejectedCount. Požadavek je idempotentní (opakování vrátí addedCount: 0). V OpenAPI je odpověď POST /v1/dnc anyOf obou tvarů a booleovské added zůstává jen v odpovědi na jedno číslo. Čísla se odebírají dál po jednom (DELETE /v1/dnc/{e164}). Kontrola cíle při vytáčení čte jedním SISMEMBER místo celé množiny, takže u seznamu s tisíci čísly se při každém vytočení nepřenášejí desítky kB; výpisy GET /v1/dnc a list_dnc se nemění. REST POST /v1/tasks/{id}/items/{itemId}/resolve a MCP resolve_task_item přijímají u auditovaného přeskočení (action: "skip" s operationId a evidenceRef) pole reason s hodnotou customer_purchased nebo nově unsubscribed. evidenceRef je neprůhledný odkaz na doklad nákupu nebo odhlášení, nikdy telefon ani e-mail. Podmínky se nemění: úkol draft (kontakt pending) nebo paused (kontakt pending nebo failed), žádný aktivní claim, záměr vytočení ani rezervace, a přeskočení neřeší kontakty ve review. Pokusy, ceny a seznam nevolat zůstávají beze změny. Důvod je součástí otisku (resolution.fingerprint), takže opakování stejné operace nic nezapíše a stejné operationId s jiným reason nebo evidenceRef vrací 409 revision_conflict. items[].resolution.reason v každé odpovědi s úkolem (GET /v1/tasks, GET /v1/tasks/{id}, POST .../resolve, MCP list_tasks, get_task, resolve_task_item) je nově výčet customer_purchased | unsubscribed (v OpenAPI dřív konstanta): klient, který odpovědi validuje podle staré specifikace, musí hodnotu unsubscribed povolit. Neznámý reason v požadavku vrací 400 validation. Upřesněné jsou popisy v OpenAPI, v MCP a v dokumentaci API, MCP a Úkolů.
• 26. 10. 2026 (1.48.0): REST: GET /v1/voice-sms-numbers, POST /v1/voice-sms-numbers (bez těla, podporuje Idempotency-Key, vrací 202 s číslem ve stavu awaiting_registration), GET /v1/voice-sms-numbers/{e164}, PATCH /v1/voice-sms-numbers/{e164} (routing: agent na vlastním motoru, nebo none), POST /v1/voice-sms-numbers/{e164}/cancel (zrušení do schválení registrace, zdarma) a DELETE /v1/voice-sms-numbers/{e164} (uvolnění aktivního čísla je nevratné, zaplacené období se nevrací; když zrušení u operátora selže, číslo zůstane ve stavu releasing a odpověď je 502 release_failed). MCP: list_voice_sms_numbers, order_voice_sms_number (confirmedMonthlyFeeHal musí být 39000, jinak se nic neobjedná), set_voice_sms_number_routing a cancel_voice_sms_number; uvolnění v MCP záměrně není. Stavy čísla: awaiting_registration, active, rejected, releasing. SMS z čísla se odesílají přes fromNumber v POST /v1/messages a send_sms (jen příjemci +420, bez deliveryStatus), přijaté SMS dál čte GET /v1/messages?direction=in a webhook message.received; hovory z čísla vytáčí agent (POST /v1/calls s agentId, jen na +420, jeden odchozí hovor naráz); spojení dvou čísel přes from a prozvonění z něj nejdou (unsupported_for_number_type). Nové chybové kódy: voice_sms_numbers_unavailable, voice_sms_number_limit (nejvýš 2 čísla na účet, objednat jde po prvním dobití), voice_sms_order_limit, voice_sms_number_out_of_stock, unsupported_for_number_type (forward a sip toto číslo nepodporuje) a destination_not_allowed (z čísla jde volat jen na +420). Poplatek 390 Kč za 30 dní se strhává jako number_fee; upozornění number_fee v GET /v1/balance a MCP get_balance počítá i tato čísla a dluh delší než 7 dní číslo uvolní stejně jako u ostatních čísel.
• 26. 10. 2026 (1.47.0): GET /v1/account a MCP get_account vracejí vedle account nové pole testCalls s klíči max (3), remaining (zbývající zkušební hovory v aktuálním okně) a resetAt (konec okna v epoch ms, okno běží 24 hodin od prvního pokusu; null, když za posledních 24 hodin žádný pokus nebyl). Totéž pole nese odpověď POST /v1/agents/{id}/test-call a MCP test_call hned po vytočení. Počítá se každý vytočený pokus včetně nezvednutého, který se neúčtuje; pokus, který vůbec nevytočil (chyba agenta, kreditu, kapacity), se nepočítá. Pole jen přibylo, stávající tvar odpovědí se nemění. PATCH /v1/account pole nevrací.
• 23. 10. 2026 (1.46.1): POST /v1/tasks/{id}/reconcile, MCP reconcile_task a cron úloh ustálí úkol po obnově podle práce: paused, dokud některý kontakt čeká na další pokus (pending, failed, in_progress), i když jiné kontakty jsou v review; needs_attention jen když nezbývá nic k vytočení kromě kontaktu v review (reviewReason úkolu je důvod první takové položky); completed, když nezbývá nic. reviewReason nese jen výsledek needs_attention, jinak je prázdný; po pozastavení uprostřed vytáčení a po zaniklém claimu se uvolní i activeItemId, activeClaimToken a activeClaimUntil. Týká se čtyř obnov: po pozastavení uprostřed vytáčení (dispatch_in_flight), po zaniklém claimu (dispatch_claim_expired), po dovyúčtování hovoru s dosud neznámou cenou (billing_unknown) a po vyřešeném nejistém vytočení (dial:*). Dřív obnova řadila kontrolu před práci, takže pozastavení běžící úlohy poslalo úlohu se stovkami čekajících kontaktů do needs_attention, ze kterého ji start ani PATCH (task_not_editable) nepustily. Nejisté vytočení, ke kterému se hovor nedohledal, drží úkol v needs_attention dál (kontakt drží nevyřešený záměr vytočení a start by ho odmítl), dokud o kontaktu nerozhodne POST .../items/{itemId}/resolve; totéž platí po dovyúčtování hovoru s neznámou cenou (billing_unknown), když jiný kontakt drží nevyřešený záměr vytočení. Běžící úkol a důvody na úrovni úkolu (například variables_limit) reconcile nemění. S politikou retryPolicy: "lorela_enterprise" se mění i stav kontaktu po posledním dovoleném pokusu (maxAttempts): výsledek no_answer, missed, busy, dokončená hlasová schránka bez člověka nebo zvednutý hovor, ve kterém volaný nic neřekl, ho uzavře jako skipped s reviewReason: "retry_policy_exhausted", stejně jako retry_age_expired po vypršení horizontu (dřív review); odkaz na poslední hovor (providerCallId) zůstává. Nejasný výsledek posledního pokusu zůstává review se stejným důvodem a ruční resolve s retry ho politika dál odmítá. Ověřený lidský callback po tomto uzavření kontakt přepne na completed (po retry_age_expired a task_expired zůstává skipped s callbackContactCallId). Úkoly bez politiky se nemění. POST .../items/{itemId}/resolve se nemění: poslední vyřízená položka ke kontrole překlopí úkol s prací do paused. Úkoly, které před nasazením uvízly v needs_attention, se samy neopraví (jejich důvod je odvozený z položky): jednorázově je uvolní resolve se skip nad položkami ke kontrole.
• 23. 10. 2026 (1.46.0): POST /v1/tasks, PATCH /v1/tasks/{id}, MCP create_task a update_task přijímají nepovinné retryMaxAgeDays: celé číslo 1 až 30, horizont opakování politiky retryPolicy: "lorela_enterprise" ve dnech od prvního započítaného pokusu příjemce. Veřejný tvar úlohy (GET /v1/tasks, GET /v1/tasks/{id}, odpovědi create a PATCH, MCP get_task a list_tasks) ho vrací jen u zadané hodnoty; nepřítomné pole znamená výchozích 5 dní jako dosud, takže úlohy bez pole se chovají beze změny. Pole vyžaduje politiku (při založení ve stejném těle, při PATCH v těle nebo už uloženou u úkolu), jinak se vrací validation s polem retryMaxAgeDays; stejně hodnota mimo 1 až 30 nebo neceločíselná. Vynechání při PATCH hodnotu zachová. Na rozdíl od retryPolicy jde hodnotu změnit i po začátku pokusů, ve stavech, které PATCH přijímal už dřív (running a completed dál ne: task_not_editable). Zvýšení hodnoty u pozastaveného úkolu vrátí do pending s novým nextAttemptAt položky skipped s reviewReason: "retry_age_expired", které mají započítaný pokus, volný pokus pod maxAttempts, nemají ověřený callback a jejichž první započítaný pokus + nový horizont (i expiresAt, je-li zadané) je v budoucnu; snížení nic neotevře a kontakty mimo nový horizont zůstanou přeskočené. Žebříček pokusů (8 minut po prvním, okna 08:00-09:00 a 17:00-19:00, čtyři pokusy) se nemění, mění se jen horizont. Portál: detail úkolu s politikou ukáže řádek o plánu opakování a horizontu, pravidla volání mají pole Horizont opakování (dny) a u úkolu s politikou nabízejí i čtyři pokusy. OpenAPI, popisy MCP nástrojů, SKILL.md a průvodce Úkoly jsou doplněné.
• 23. 10. 2026 (1.45.1): CAMPAIGN_QUOTA_EXPIRES_AT v lib/service/call-quotas.ts je 2026-11-14T23:00:00+01:00 (22:00 UTC; dřív 2026-10-31T23:00:00Z), PETCENTER_REMINDER_DISPATCH_END je 2026-11-21T19:55:00+01:00 (18:55 UTC; dřív 5. 11.). petcenterCampaignQuotaActive() a tik runPetcenterOutboundTaskTick tedy vytáčejí hlavní kampaň do 14. 11. 22:00 UTC a připomínky coupon_reminder do 21. 11. 18:55 UTC. Uložená kvóta agentky kampaně (call-quota:agent) má vlastní validUntil a posouvá se zvlášť přes PUT /api/admin/call-quotas. Ostatní podmínky výjimky (příznak VOLAI_PETCENTER_CALL_QUOTA_ENABLED, účet, agent, odchozí úloha, osm relay jmen) jsou beze změny.
• 23. 10. 2026 (1.45.0): Relay jména čísla se zakládají na pozadí hned po koupi (POST /v1/numbers, buy_number, portál) i po vyřízení objednávky (POST /v1/numbers/orders, order_number_from_region), bez ohledu na směrování čísla. Lease (POST /v1/relay, create_relay_lease), agentní hovor i přepojení z čísla, které jména ještě nemá, jejich založení spustí znovu. Popis create_relay_lease doplňuje už platné pravidlo: lease spojí právě jeden hovor, opakované vytočení stejného sipName skončí odmítnutím SIP 603, takže před každým pokusem vytvoř nový lease a automatické opakování v platformě vypni. Tvar odpovědí se nemění.
• 22. 10. 2026 (1.43.0): Nové pole agenta recordingNotice (boolean) v POST/PATCH /v1/agents, MCP create_agent/update_agent a v konceptu agenta (PUT /v1/agents/{id}/draft, save_agent_draft). Odpověď ho nese vždy (false, když není nastavené). Věta se připojí jen při recordingNotice: true a zapnutém recordCalls; v konceptu chybějící klíč znamená beze změny. Odhad délky pozdravu (first_message_too_long) větu započítá jen tehdy, když je zapnutá. Tím se mění, co znamená recordCalls: samo nahrávání větu už nepřidává. Stávajícím agentům, kterým ji volai přidalo samo, byla 22. 10. 2026 odebrána; věta napsaná přímo ve firstMessage zůstává.
• 22. 10. 2026 (1.42.3): Rezervace pokusu (reservedBudgetHal, estimatedCostHal položky) je součet nohy hovoru a nohy agenta, každá zaokrouhlená nahoru na haléř stejně jako při účtování (dřív jedno zaokrouhlení součtové sazby, které u části stropů vyšlo o haléř níž). Hovor se stropem délky (odchozí úkol) se účtuje za min(durationSecs, maxDurationSecs); uložené durationSecs zůstává změřené. Přepojená noha takového hovoru dostane nejvýš zbytek do nejvyšší ceny pokusu. Agent s recordCalls: false na motoru volai (provider: "engine") nahrávku nemá: hasRecording je false a GET /v1/calls/{id}/recording vrátí no_recording. Uložení takového agenta vyžaduje motor, který příznak zná, jinak skončí chybou zápisu do motoru místo tichého nahrávání.
• 21. 10. 2026 (1.42.2): checkCallRateLimit (POST /v1/calls, MCP make_call, odchozí úkoly) počítá pokusy za 24 hodin u hovoru, na který se uplatní uložená kvóta agenta (call-quota:agent:{agentId}) nebo výjimka kampaně PetCenter s denním limitem nad 1 000, do vlastního čítače ratelimit:callsday-agent:{userId}:{agentId} a porovnává je s denním limitem kvóty. Hovory s výchozím limitem, hovory bez agenta (zkušební hovor z webu, most, relay) a hovory s kvótou, která denní limit nezvedá (1 000 a méně), dál sdílejí čítač účtu ratelimit:callsday:{userId}; hovor téhož agenta mimo rozsah kvóty (outboundTaskOnly, taskPurposes, po validUntil) se řídí výjimkou kampaně, pokud se na něj uplatní, jinak jde s výchozím limitem 1 000 do čítače účtu. Souběžné sloty agentcallslot:{userId} (relay_lease_limit) a minutový čítač ratelimit:calls:{userId} zůstávají společné pro účet. Kód rate_limited, HTTP status 429, texty hlášek a výchozí limity 2 souběžné, 10 za minutu a 1 000 za 24 hodin se nemění; kvótu dál ukládá jen admin. resolveAgentCallLimitsWithSource v lib/service/call-quotas.ts vrací vedle limitů i jejich zdroj (stored, campaign, default) z jediného čtení kvóty a usesAgentDailyCounter z nich volí čítač.
• 18. 10. 2026 (1.42.1): Příchozí hovor, který hlasový motor odmítl pro vyčerpaný strop souběžných hovorů, má teď v REST (GET /v1/calls, GET /v1/calls/{id}) a MCP (list_calls, get_call) status: "missed", endReason: "capacity", durationSecs: 0 a priceHal: 0; z kreditu se nic nestrhne. Webhook call.missed odejde jednou za hovor, SMS volajícímu jen u agenta se zapnutým missedCallSms (stejně jako u každého zmeškaného příchozího hovoru); e-mail se shrnutím po hovoru se za něj neposílá. Když o nezvednutém hovoru dřív informoval operátor, odejde call.missed už tehdy (případně bez endReason) a stávající záznam se doplní o endReason: "capacity"; druhý záznam ani druhý webhook nevznikne. Dosud takový hovor zůstával navždy ve stavu in_progress, protože motor žádný post-call neposílá. Záznam teď vzniká při rekonciliaci hovorů motoru, tedy do několika minut po odmítnutí. Dosavadní visící záznamy z posledních sedmi dní, starší dvou hodin, uzavře hodinová kontrola zpětně, jen s důkazem z evidence motoru a bez webhooku; má-li k nim operátor vlastní záznam, sloučí je s ním. Hodnoty missed i capacity už ve výčtech existovaly, tvar odpovědí se nemění. Ve filtru outcome (GET /v1/calls, list_calls) takový hovor patří do no_answer; u odchozího hovoru se capacity (plný relay pool) nic nemění.
• 18. 10. 2026 (1.42.0): GET /v1/subscription a MCP get_subscription: v recommendation nové pole steady, jestli útratu nedělá jen jednorázová špička: provoz posledních 14 pražských dní přepočtený na 30 dní a k němu měsíční poplatky za čísla z 30denního okna (jednou) dosáhnou aspoň ceny doporučeného stupně. Portál nabídne paušál osobně a věta MCP ho doporučí jen při worthIt i steady; worthIt a ostatní pole se nemění. Doporučení se počítá jednou funkcí pro portál, REST i MCP; pro REST a MCP má cache vedle výdrže kreditu (10 minut, smaže ji každý pohyb kreditu). Nic jiného v API se nemění.
• 18. 10. 2026 (1.41.0): GET /v1/subscription a MCP get_subscription: nové pole previousPeriod, shrnutí zaplaceného období před tím současným (subscription.periodStart) se stejnými čísly jako e-mail o obnově: tier, periodStart a periodEnd (ISO 8601), creditHal, usedHal, usedPercent (dolů zaokrouhlené), overHal (útrata nad měsíční kredit; u dokupování bez dluhu, který uhradil nový kredit, u stropu včetně dluhu; null, když ji historie kreditu nedoloží), expiredHal, exhaustionMode a exhaustedAt (ISO 8601, null, když kredit nedošel nebo to historie nedoloží). Ukládá se při každé obnově kartou (i když ji dokončí webhook payment_intent.succeeded) i ruční platbou a drží 45 dní; vrací se jen u aktivního paušálu, bez ohledu na available, a je null bez paušálu, ve stavu past_due a canceled, v prvním období a když útratu nejde doložit. MCP get_subscription k tomu přidá větu o minulém období s pražskými daty. GET /v1/balance a MCP get_balance: notice {kind:"subscription_runway",renewsAt,runsOutAt} u aktivního paušálu nově počítá runsOutAt z opatrného tempa paušálu, stejného jako výhled na kartě v portálu: nejvyšší z průměru za 28 dní (při úplné historii kreditu), průměru provozu za posledních 7 pražských dní bez poplatků za čísla a průměru od začátku běžícího období (po jeho prvním týdnu), místo průměru za 28 dní. Tvar ani podmínky upozornění se nemění (při zapnutém automatickém dobíjení se nevrací) a runway.dailyAverageHal a runway.runwayDays zůstávají průměrem za 28 dní. E-mail o obnově, kterou dokončí webhook, nově taky vynechá radu při naplánované změně stupně. Nic jiného v API se nemění.
• 18. 10. 2026 (1.40.1): POST /v1/outbound/dispatch-scopes/petcenter/registrations dekódoval výsledek Lua skriptu přes JSON.parse i v případě, že ho výchozí klient Upstash (redis() s automatickou deserializací; jen redisRaw() ji nemá) vrací už jako objekt. Každý požadavek tak skončil výjimkou SyntaxError: "[object Object]" is not valid JSON a odpovědí 500. Výjimka vznikla až po běhu skriptu a před mapováním výsledku, takže nově zapsanou registraci (nebo opakování téže operace) viděl klient jen jako 500 a odmítnutí z Lua se k němu nikdy nedostalo jako 409 revision_conflict (operation_conflict, manifest_cas_conflict, task_changed_during_registration s error.details), 404 not_found nebo 400 validation. registerPetcenterDispatchScope nově dekóduje výsledek pomůckou decodeLuaJsonObject: JSON.parse jen nad skutečným řetězcem a objekt projde beze změny. Odpověď skriptu, která není objekt (platný JSON jiného tvaru i text, který není JSON), vyhodí výjimku a route vrátí 500, protože skript mohl změnu už zapsat a výsledek je nejistý; klient se pak zeptá na výsledek operace přes GET /v1/outbound/dispatch-scopes/petcenter/registrations?operationId=.... Prázdný výsledek dál končí registration_failed. Stejnou pomůckou dekóduje výsledky i hromadná pauza, její chování ani chybová hláška se nemění. Kontrakt se nemění: tvar těla a odpovědi, idempotence podle operationId (replayed: true při opakování), expectedManifestSha, stavové kódy ani příznak providerActionStarted. Jediný rozdíl viditelný klientem je, že dřívější odpovědi 500 jsou nově 200, 409, 404 nebo 400 podle výsledku skriptu; 500 zůstává jen pro nečekaný tvar jeho odpovědi.
• 18. 10. 2026 (1.40.0): GET /v1/subscription a MCP get_subscription: nové pole recommendation, nebo null (paušál účtu nenabízený nebo historie kreditu kratší než 30 pražských dní). Obsah: spendHal (útrata za posledních 30 pražských dní za hovory, agenta, čísla a SMS, minus vrácení za SMS), days (30), cheapestPath (per_second nebo plan), tier a tierTotalHal (nejlevnější stupeň s dokupováním a jeho cena při té útratě), savingsHal, worthIt (úspora aspoň 50 Kč a 5 %, stejný práh jako v portálu) a options (všechny cesty pro stejnou útratu: {path, tier, totalHal} pro platbu po vteřinách a každý stupeň). MCP get_subscription k tomu předplatiteli přidá větu s radou podle stejného pravidla jako portál a e-mail. Nic jiného v API se nemění.
• 18. 10. 2026 (1.39.1): PUT /api/admin/call-quotas načte agenta (getAgent) a odmítne zápis, když agent neexistuje nebo je smazaný (404 agent_not_found), nebo když userId v těle není vlastník agenta (400 validation, zpráva neuvádí skutečného vlastníka). Odmítnutý zápis nezapíše nic do call-quota:agent:{agentId}, do indexu call-quota:index ani do user:{userId}:admin-log. userId v těle zůstává povinné, ať jde uložený tvar z GET poslat zpět. Hláška relay_lease_limit při vytáčení hovoru agenta (POST /v1/calls, MCP make_call, odchozí úkoly) je nově 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. (číslo i slovo se ohýbají: 1 běžící hovor, 2 až 4 běžící hovory, jinak běžících hovorů), anglicky 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.. Číslo je práh volajícího agenta z resolveAgentCallLimits (uložená kvóta, jinak výchozí 2, po ořezu poolem), počet běžících hovorů je společný čítač účtu agentcallslot:{userId}, takže slot mohl zabrat i jiný agent téhož účtu. Dřív hláška tvrdila, že jde o maximum na účet, ačkoli práh určuje agent, a české slovo bylo pro každý počet ve tvaru běžící hovory. Kód relay_lease_limit, HTTP status 400, čítač, práh ani čekání odchozích úkolů na tento kód se nemění. Nadpis tabulky historie v detailu zákazníka v adminu je nově Historie admin akcí (Admin action history), řádky se nemění.
• 18. 10. 2026 (1.39.0): Nový admin endpoint GET/PUT/DELETE /api/admin/call-quotas (session admina, ne API klíč; zápisy kontrolují Origin) ukládá kvótu agenta do call-quota:agent:{agentId}: concurrent 1 až 30, perMinute 1 až 60, daily 1 až 20 000, povinná note, outboundTaskOnly a volitelné taskPurposes (standard, coupon_reminder) a validUntil (milisekundy od epochy). Každá změna se zapíše do user:{userId}:admin-log jako call_quota_set nebo call_quota_deleted. resolveAgentCallLimits v lib/service/call-quotas.ts ji uplatní před výjimkou PetCenter a před výchozími { concurrent: 2, daily: 1000, perMinute: 10 }, jen pro stejný účet, odchozí úlohu (je-li outboundTaskOnly), povolený účel a čas před validUntil. Souběh se ořízne na min(uložený, max(2, počet různých jmen v ODORIK_RELAY_NAMES - 2)), minutový a denní limit ne. Bez uložené kvóty se chování nemění. Umístění hovoru na relay jméno čeká na svůj tah (jeden sdílený ukazatel v Redisu, rozestup RELAY_PLACEMENT_GAP_MS 3 s, nejdéle RELAY_PLACEMENT_MAX_WAIT_MS 10 s; při výpadku Redisu se hovor vytočí hned a zaloguje se relay placement spacing unavailable): hovory agenta (POST /v1/calls, MCP, úlohy) a zkušební hovory u motoru i ElevenLabs, claim přepojení mostem nejvýš 4 s; BYO relay lease (POST /v1/relay) a callback hovory bez relay jména ne. POST /v1/calls a zkušební hovor tak mohou při dávce hovorů trvat až o 10 s déle; maxDuration je 100 s u POST /v1/calls a 70 s u POST /v1/agents/{id}/test-call. Tik odchozích úloh po TICK_DISPATCH_BUDGET_MS (90 s) nezačne další úlohu, zbytek počká na další běh. Odmítnutí motorem pro strop souběžných hovorů nese Retry-After: 30, který volai předává už dnes (retryAfterSecs, hlavička Retry-After, items[].nextAttemptAt): po nasazení motoru s tímto stropem čekají kontakty 30 s místo 5 minut, motor bez hlavičky dál 300 s.
• 18. 10. 2026 (1.38.3): Bez změny chování API. Nabídka paušálu je zapnutá pro všechny účty (PAUSAL_MODE=on), takže GET /v1/subscription vrací available: true; pausal_unavailable (404) zůstává pro případ, že se nabídka vypne. Dokumentace (/docs/kredit, SKILL.md, llms.txt) už neříká, že je paušál jen pro některé účty, a obnovy popisuje jako hodinové.
• 18. 10. 2026 (1.38.2): agentCallLimits v lib/service/call-quotas.ts vrací { concurrent: 6, daily: 6000, perMinute: 15 } i po CAMPAIGN_QUOTA_EXPIRES_AT (2026-10-31T23:00:00Z), pokud kontext kvóty nese nové volitelné pole taskPurpose: "coupon_reminder" a platí petcenterReminderQuotaActive(), tedy je zapnutý příznak VOLAI_PETCENTER_CALL_QUOTA_ENABLED a čas je před PETCENTER_REMINDER_DISPATCH_END (2026-11-05T19:55:00+01:00, 18:55 UTC; konstanta se přesunula do call-quotas.ts a čte ji i tik vytáčení). makeAgentCall předá účel kvótě až po ověření vazby na schválenou připomínku. Hovor bez účelu má po 31. 10. výchozí { concurrent: 2, daily: 1000, perMinute: 10 }. Ostatní podmínky (přesná shoda účtu, agenta a interního kontextu odchozí úlohy, alespoň osm různých jmen v ODORIK_RELAY_NAMES) platí i pro připomínky; hlavní kampaň po 31. 10. dál nevytáčí, petcenterCampaignQuotaActive ani logika tiku se nemění. Chování API pro ostatní účty se nemění.
• 18. 10. 2026 (1.38.1): GET /v1/balance a MCP get_balance: osmý tvar notice {kind:"subscription_runway",renewsAt,runsOutAt} (při dnešním tempu dojde zůstatek před obnovou; předplatiteli se vrací místo {kind:"runway"}, při zapnutém automatickém dobíjení nic). POST /v1/subscription/checkout a MCP create_subscription_link: consumerConsent se u účtu s IČO, DIČ nebo názvem firmy ignoruje (do metadat Stripe jde 0), spotřebitel bez IČO dál dostává confirmUrl. Nic jiného v API se nemění.
• 17. 10. 2026 (1.38.0): Nové endpointy REST: GET /v1/subscription (odpověď {subscription, tiers, topupBalanceHal, available}; subscription je null bez paušálu, tiers nese {id, priceHal, creditHal} v haléřích bez DPH, available říká, jestli si na účtu lze paušál zapnout), POST /v1/subscription/checkout (tělo {tier, exhaustionMode, consumerConsent?}, kde tier je "490", "990" nebo "1990" a exhaustionMode je topup nebo cap bez výchozí hodnoty; vrací {checkoutUrl}, nic se nestrhne, dokud člověk nezaplatí v Checkoutu; účet bez IČO musí poslat consumerConsent), PATCH /v1/subscription (tělo {tier?, cancelAtPeriodEnd?, exhaustionMode?}), POST /v1/subscription/pay (odkaz do Checkoutu na ruční zaplacení neprošlé obnovy, jen ve stavu past_due, jinak invalid_state) a POST /v1/subscription/card (odkaz do Checkoutu v režimu uložení karty na výměnu uložené karty, nic se nestrhne); POST endpointy berou Idempotency-Key. PATCH hned provede snížení stupně (od dalšího období), cancelAtPeriodEnd: true a exhaustionMode: "cap" a vrátí {subscription}; zvýšení stupně, cancelAtPeriodEnd: false (obnovení paušálu nastaveného ke konci) a exhaustionMode: "topup" nic nezmění a vrátí 409 subscription_confirmation_required s confirmUrl (jednorázový, platí 24 hodin), který musí člověk otevřít a potvrdit v portálu. Objekt subscription nese tier, status (active, past_due nebo canceled), periodStart a periodEnd jako řetězce ISO 8601 (na rozdíl od ts v ledgeru, kde jsou epoch milisekundy), monthlyCreditHal, monthlyRemainingHal, exhaustionMode, cancelAtPeriodEnd, nextTier a card (brand, last4). GET /v1/balance a nástroj MCP get_balance nově nesou i subscription (null bez paušálu) a topupBalanceHal (jen dobitý kredit, záporný při dluhu); balanceHal je dál součet obou. Ledger (GET /v1/credit/ledger, MCP list_ledger) má dvě nové hodnoty type: subscription_grant a subscription_expire; položka ledgeru u útraty kryté měsíčním kreditem nese navíc fromSubscriptionHal (část, kterou zaplatil měsíční kredit), ostatní položky pole nemají. Pět nových nástrojů MCP: get_subscription, create_subscription_link, update_subscription, cancel_subscription a create_subscription_payment_link; výměna karty zůstává jen v REST a v portálu. Nové chybové kódy: 402 subscription_cap_reached (vrací se místo insufficient_credit u volání, zkušebních hovorů, prozvonění, SMS a nákupu čísel, SMS čísel a relay linek, když paušál běží s exhaustionMode: "cap", měsíční kredit je vyčerpaný a zbylý kredit akci nepokryje), 409 subscription_exists, 404 subscription_missing, 409 subscription_canceled, 409 subscription_confirmation_required, 400 consumer_consent_required, 404 pausal_unavailable (nabídka není pro účet zapnutá), 400 invalid_tier a 409 subscription_cap_active (auto-dobíjení nejde zapnout, dokud paušál běží se stropem); stránka potvrzení v portálu (ne REST) může skončit stavem confirm_invalid, confirm_expired nebo confirm_used. Jakmile je nabídka pro účet zapnutá, portál ukáže na stránce Kredit kartu paušálu a stránky pro zapnutí, změnu a potvrzení odkazu confirmUrl. Účty bez paušálu se v dosavadních polích, stavech ani kódech nemění.
• 16. 10. 2026 (1.37.5): Motor posílá v analysis.evaluation_criteria_results u každé položky rationale a reason jako null, když nemají hodnotu. Schéma post-call webhooku null odmítlo a zahodilo hodnocení všech kritérií, takže goal v GET /v1/calls, GET /v1/calls/{id} a v MCP list_calls a get_call bylo u hovorů na motoru null, filtr goal je řadil mezi not_evaluated a e-mail po hovoru neměl řádek s cílem. Schéma teď bere null jako chybějící pole u všech volitelných polí, kde null nic neznamená, a vadná položka hodnocení zahodí jen sebe. Kde null nese význam (například recording_url: null = hovor bez nahrávky), zůstává. Žádná změna polí ani endpointů. Hovory z období od 16. 9. do 16. 10. 2026 zatím hodnocení nemají.
• 15. 10. 2026 (1.37.4): Tři nová pole agenta turnDigitTailFloorMs, turnLongSpeechFloorMs (celé číslo, 0 = vypnuto, jinak 400 až 2300 ms; mezera 1 až 399 vrací validation) a turnLongSpeechSecs (1 až 30, desetinné povolené) v POST /v1/agents, PATCH /v1/agents/{id} (číslo nastaví, null uloženou hodnotu smaže, chybějící klíč = beze změny), GET /v1/agents a GET /v1/agents/{id} (vždy přítomné, číslo nebo null = nenastaveno, motor používá své výchozí 0 / 0 / 5), ve snímku konceptu (PUT/GET /v1/agents/{id}/draft; chybějící klíč = beze změny, null smaže) a v MCP create_agent/update_agent/save_agent_draft. Motoru se posílají v bloku turn jako digit_tail_floor_ms, long_speech_floor_ms a long_speech_secs při KAŽDÉM uložení agenta (motor pole z předchozí verze nepřenáší; chybějící hodnota jde jako výchozí motoru) a read-back je porovnává (kontrakt motoru kap. 3.5af a 3.5ag). Ukládají se u obou poskytovatelů, čtou se jen na motoru v režimu smart_turn; ElevenLabs je ignoruje. Doporučení motoru: krok 1 = 800 u českých agentů s diktovanými čísly, krok 2 = 1200, praktický strop 1500; podlahu dostanou i data, PSČ a roky. Čítače uplatněných podlah zůstávají jen v motoru (dump a jeho GET /v1/calls), do webhooků volai nejdou. V portálu karta "Konec repliky" v záložce Pokročilé.
• 15. 10. 2026 (1.37.3): Nové pole agenta sttLanguageHintsStrict: boolean v POST /v1/agents, PATCH /v1/agents/{id} (true zapne, false nebo null vypne, chybějící klíč = beze změny), GET /v1/agents a GET /v1/agents/{id} (vždy boolean, false když není nastavené), ve snímku konceptu (PUT/GET /v1/agents/{id}/draft; chybějící klíč = beze změny, null vypne) a v MCP create_agent/update_agent/save_agent_draft. Motoru se posílá jako stt.language_hints_strict při KAŽDÉM uložení agenta (motor pole z předchozí verze nepřenáší) a read-back ho porovnává. Ukládá se u obou poskytovatelů, čte ho jen motor (Soniox); best-effort, jen agenti na motoru s jazykem cs a odchozími hovory, u sk nezapínat. Detail hovoru GET /v1/calls/{id}, MCP get_call a webhooky call.completed (i call.failed s endReason: "engine_error") nesou nový blok engine: { protectedUtterances: [{ timeInCallSecs?, atSecs, message, words, reason }], protectedUtterancesCount } - repliky volaného zahozené v okně pozdravu (metadata.engine.protected_utterances z post-callu motoru, kontrakt kap. 3.5ae): nejsou v přepisu a agent na ně nereagoval; reason je first_message_protect, greeting_courtesy nebo greeting_identification (otevřený výčet), nejvýš 10 položek, message do 200 znaků, počet počítá všechny. Blok je jen u hovorů motoru od sestavení z 15. 10. 2026 ([] a 0, když nic nezahodil); starší hovory, výpis GET /v1/calls a agenti na ElevenLabs ho nemají. V portálu přepínač v záložce Pokročilé a karta "Repliky volaného během pozdravu" v detailu hovoru.
• 15. 10. 2026 (1.37.2): cdr-sync: druhá noha zvednutého prozvonění (stejné from/to, jiné active_call_id, začátek krátce po první noze, první noha answered) se páruje k témuž záznamu kind: "ring" bez poplatku za pokus; vteřiny se účtují jen při length > 0. Popis ring.rangSecs v OpenAPI a dokumentaci: hodnota operátora bývá o 1 až 3 s větší než ringSecs. Žádná změna polí ani endpointů.
• 15. 10. 2026 (1.37.1): Nové nepovinné pole agenta inboundVariables: Record<string, string> v POST /v1/agents, PATCH /v1/agents/{id}, GET /v1/agents a GET /v1/agents/{id}, ve snímku konceptu (PUT /v1/agents/{id}/draft, GET .../draft) a v MCP create_agent/update_agent/save_agent_draft: výchozí hodnoty {{promenna}} pro PŘÍCHOZÍ hovor. Initiation webhook je sloučí do dynamic_variables jen pro klíče, které hovor nedodává sám (caller_number, called_number, attempt_id, volai_*, trial_* a system__* mají přednost a validace taková jména odmítne); odchozí hovory (POST /v1/calls, relay, úlohy) je nepoužijí. Nejvýš 10 klíčů [A-Za-z0-9_]{1,40}, hodnota oříznutý řetězec do 200 znaků. PATCH objektem nahradí uložené hodnoty celé, null nebo {} je smaže, chybějící klíč nechá beze změny; v odpovědi klíč chybí, když agent žádné nemá. V konceptu chybějící klíč znamená beze změny. Varování prompt_variables_unavailable_inbound a first_message_empty proměnnou s výchozí hodnotou nehlásí. Platí u obou poskytovatelů - motor i ElevenLabs čtou tentýž webhook.
• 15. 10. 2026 (1.37.0): Nový POST /v1/rings s tělem {to, from?, ringSecs?} (from = tvoje aktivní volai číslo, výchozí první číslo účtu; ringSecs 3 až 30, výchozí 10) odpoví hned po objednání u operátora {id, status: "initiated", kind: "ring", from, to, requestedSecs, priceHal}. Výsledek přijde webhookem (call.no_answer pro rang a ended_early, call.completed pro answered) a je v GET /v1/calls/{id} (i s ?waitSecs=) v novém bloku ring: {requestedSecs, outcome, rangSecs}; outcome je rang, ended_early, answered nebo unknown. kind má novou hodnotu ring; tělo všech hovorových webhooků nese nově kind a u prozvonění blok ring. MCP nástroj ring_number se stejnými poli. Limity 30 prozvonění za minutu a 500 za den na účet, 120 za hodinu na jeden cíl; ruční seznam nevolat platí, automatická 30denní blokace se nepoužije ani nenaplňuje. Idempotency-Key podporován. Nové chybové kódy: ring_needs_number (účet bez aktivního čísla).
• 13. 10. 2026 (1.36.2): PATCH /v1/numbers/{e164} a MCP set_number_routing vrátí validation, když je routing.mode sip, sipUri míří na <credentialId>.sip.vapi.ai nebo <credentialId>.sip.eu.vapi.ai a sipUsername se sipPassword jsou poslané nebo uložené z dřívějška. Vapi BYO trunk naše hovory pozná podle IP v gateways (IP 81.31.45.0, netmask 24) a s autentizovaným směrováním hovor nespojí. Nativních SIP čísel Vapi (sip:<jméno>@sip.vapi.ai) se změna netýká. Číslo, které takové směrování už má uložené, se opraví poslaním obou polí jako prázdného řetězce. Popis set_number_routing a stránky /integrace/vapi, /docs/vlastni-agent a /docs/sip to uvádějí; portál u nespojeného hovoru na BYO trunk Vapi radí zkontrolovat přihlašovací údaje, gateways a region.
• 13. 10. 2026 (1.36.1): Odchozí hovor agenta přes relay, kterému operátor nedostal cíl (webhook směrování neodpověděl do pěti sekund), má dál status: "no_answer", ale nově endReason: "rejected" místo "no_answer" a do automatické blokace cíle (3 neúspěchy za 24 hodin) se nepočítá. V úlohách má takový pokus countsAsAttempt: false a errorCode: "relay_not_routed", nespotřebuje maxAttempts ani pořadí politiky lorela_enterprise a kontakt dostane nextAttemptAt nejdřív za 60 sekund. Po třetím takovém pokusu za sebou jde kontakt do review s reviewReason: "call:relay_not_routed".
• 12. 10. 2026 (1.36.0): Nový interní POST /v1/outbound/dispatch-scopes/petcenter/registrations přijímá trvalé operationId, SHA-256 manifestu a uspořádaná ID úloh. První registrace je připnutá na schválený manifest 19 úloh; pozdější registrace mohou jen přidávat. GET vrací stav a výsledek operace. Nový cron /api/cron/outbound-tasks/petcenter prochází oddělenou férově rotovanou frontu; obecný cron i atomický claim vynucují oddělení. Limity 6 souběžných hovorů, 15 pokusů za minutu a 6 000 za den zůstávají stejné. GET /v1/tasks?ids=id1,id2 čte jeden až pět vybraných úloh patřících přihlášenému účtu, hlásí úplnost výběru a odmítne odpověď nad 4 MiB. POST /v1/outbound/dispatch-scopes/petcenter/pauses bezpečně pozastaví až pět registrovaných úloh s ověřením revizí; GET vrací trvalé výsledky a hash vstupu pro bezpečné dorovnání.
• 11. 10. 2026 (1.35.0): POST/PATCH /v1/agents a MCP create_agent/update_agent/save_agent_draft berou dvě nová pole: firstMessageProtectSecs: number | null (0 až 20 vteřin, i desetinné, jen odchozí hovory; dokud první věta hraje, krátká reakce volaného ji nepřeruší; replika volaného bez přerušovače (stop, ne, moment, dost, počkejte) se v chráněném okně zahodí: větu nepřeruší, v přepisu není a agent na ni nereaguje, zatímco s přerušovačem se věta přeruší vždy; null nebo 0 ochranu vypne) a silencePromptText: string | null (vlastní věta připomínky v tichu, nejvýš 80 znaků, řekne se doslova místo "Jste tam?"; prázdný řetězec nebo null vrátí výchozí text). Na rozdíl od silencePromptSecs BEZ vnucené výchozí hodnoty: chybějící pole při POST se neuloží, GET /v1/agents ho u staršího agenta vrací jako null a PATCH bez klíče uloženou hodnotu nechá být, takže se stávajícím agentům nic nemění. Obě pole se přijímají a ukládají u OBOU poskytovatelů, zazní ale jen u agenta na vlastním motoru volai. Hodnota mimo meze padá na obecnou validační chybu (validation, 400), žádný nový kód. Položka přepisu hovoru (transcript[] v GET /v1/calls/{id}, MCP get_call a webhooku call.completed) nese u repliky agenta, kterou volající přerušil, nepovinné interrupted: true, přičemž message je pořád celý plánovaný text; chybí u hovorů přes ElevenLabs i u hovorů bez přerušení.
• 10. 10. 2026 (1.34.5): GET a POST /v1/sms-numbers i MCP list_sms_numbers a buy_sms_number vracejí u každého SMS čísla dailySendLimit (20 SMS za 24hodinové okno v prvních 30 dnech čísla, potom 50), dailySendRemaining (u uvolňovaného čísla 0) a dailySendResetsAt (Unix ms konce okna, null, když žádné neběží). Okno začíná první SMS ze kteréhokoli SMS čísla účtu, je pro všechna společné a počítá i pokusy nad limit a SMS, které operátor odmítl. Tělo webhooku message.sent má nové pole smsNumber: E.164 SMS čísla u odeslání ze SMS čísla, null u sdíleného odesílatele SMSinfo. Hlášky internal_error a send_failed_operator u SMS říkají „Chyba je na naší straně a víme o ní“, sms_number_out_of_stock už neslibuje doplnění zásoby a hláška rate_limited při vyčerpaném limitu SMS čísla řekne, za jak dlouho okno skončí; kódy chyb se nemění. V portálu ukazuje formulář na /zpravy limit u zvoleného SMS čísla a karta SMS zprávy na Přehledu počítá i přijaté SMS.
• 10. 10. 2026 (1.34.4): agentCallLimits v lib/service/call-quotas.ts vrací pro rozsah kampaně { concurrent: 6, daily: 6000, perMinute: 15 }; podmínka alespoň osmi různých jmen v ODORIK_RELAY_NAMES zůstává a zaručuje dvě volná jména pro ostatní volající. Výchozí kvóta účtu (2, 1000, 10), podmínky zapnutí i společné čítače účtu se nemění; chování API pro ostatní účty se nemění.
• 10. 10. 2026 (1.34.3): Akce chyby send_unknown už netvrdí, že stav unknown je vždy konečný: u SMS odeslané ze SMS čísla se může později sám změnit na sent s deliveryStatus, nebo na failed s vráceným kreditem; u SMS od sdíleného odesílatele SMSinfo zůstává konečný. Akce chyby rate_limited už neslibuje vždy hlavičku Retry-After: denní strop odeslání ze SMS čísla (20 SMS za den na účet v prvních 30 dnech od koupě čísla, potom 50) se obnoví další den a souběžně běžící koupě čísla skončí za pár vteřin. POST /v1/messages má v tabulce chyb blocked_destination (400, prémiová čísla). Zprávy přijaté na SMS čísle mají source: "inbound", výpis přijatých drží nejvýš 1 000 nejnovějších zpráv na účet a webhook message.received se nad 300 přijatých zpráv za hodinu na jedno číslo neposílá (zprávy se dál ukládají). V message.received je from číslo v E.164, nebo textové jméno odesílatele (nejvýš 32 znaků); zprávu, kterou příjem hned nezachytil, doplní pravidelná kontrola do zhruba 15 minut a událost pak přijde se zpožděním. Doručenka (deliveryStatus) ani pozdní failed žádnou událost nevyvolají, čtou se z GET /v1/messages/{id}. Uvolnění SMS čísla v MCP není, jen v portálu a přes DELETE /v1/sms-numbers/{e164}.
• 9. 10. 2026 (1.34.2): agentCallLimits v lib/service/call-quotas.ts vrací pro rozsah kampaně { concurrent: 8, daily: 6000, perMinute: 15 }; výchozí kvóta účtu (2, 1000, 10), podmínky zapnutí i společné čítače účtu se nemění. Chybová zpráva rate_limited u denního limitu uvádí 6000.
• 9. 10. 2026 (1.34.1): CAMPAIGN_QUOTA_EXPIRES_AT v lib/service/call-quotas.ts je 2026-10-31T23:00:00Z; dál platí vypínač VOLAI_PETCENTER_CALL_QUOTA_ENABLED, přesná shoda účtu, agenta a interního kontextu odchozí úlohy a alespoň osm různých jmen v ODORIK_RELAY_NAMES. Chování API pro ostatní účty se nemění.
• 9. 10. 2026 (1.34.0): Nové endpointy GET /v1/sms-numbers, POST /v1/sms-numbers (bez těla, podporuje Idempotency-Key, vrací 201) a DELETE /v1/sms-numbers/{e164} (nevratné, zaplacené období se nevrací) a MCP nástroje list_sms_numbers a buy_sms_number (confirmedMonthlyFeeHal musí odpovídat aktuálnímu poplatku v haléřích, jinak se nic nekoupí). GET /v1/messages a MCP list_messages berou direction (out ve výchozím stavu, in, all) a vrací i zprávy přijaté na SMS čísle; zprávy nově nesou direction, smsNumber a deliveryStatus (delivered nebo undelivered, jen u SMS odeslaných z čísla), status má novou hodnotu received a failReason hodnotu opted_out. POST /v1/messages a MCP send_sms berou fromNumber (aktivní SMS číslo účtu, jen příjemci +420, 1,90 Kč za segment). Nová událost webhooku message.received s daty {id, from, to, body, segments, receivedAt} (receivedAt je Unix ms); text přijaté SMS je cizí obsah a MCP u něj posílá securityNotice. Přijaté SMS se uchovávají 90 dní. Nové chybové kódy: sms_numbers_unavailable, sms_number_limit, sms_number_out_of_stock, invalid_from_number, from_number_unsupported_destination a recipient_opted_out; stávající kódy recipient_rejected, sms_gateway_failed, recipient_is_virtual_number (SMS od sdíleného odesílatele na SMS číslo volai) a release_failed platí i pro SMS čísla. Pole from je u zprávy odeslané bez fromNumber dál interní štítek volai, u zprávy odeslané ze SMS čísla samo číslo a u přijaté zprávy odesílatel.
• 8. 10. 2026 (1.33.0): Politika callback-routing má volitelné missedFirstMessage (do 500 znaků): použije se místo firstMessage, když předchozí ověřený odchozí hovor neměl rozhovor se zákazníkem (nezvednuto, záznamník, hlasové menu, nikdo nepromluvil, nebo hovor ještě neuzavřený). Initiation posílá motoru volai_callback_kind (missed/contacted) vedle volai_call_mode=campaign_callback. Post-call motoru umí caller_optout_requested (jen odchozí hovory): hovor pak nese optOutRequested: true ve výpisu i detailu, číslo volaného se zapíše do seznamu nevolat účtu (GET /v1/dnc) a politika lorela_enterprise další pokus téže položky nenaplánuje. Hovor motoru s answered_by: unknown zůstává unknown - portál už místo něj nehádá záznamník z krátké odpovědi („Ano.“ po úvodu), takže hasConversation takového hovoru odpovídá přepisu; schránka rozpoznaná motorem (voicemailReason vyplněný) dostane v politice lorela_enterprise další pokus i přes hlášku operátora v přepisu. Nový důvod voicemailReason: digits (hláška operátora čtoucí volané číslo po číslicích). Vše aditivní; stávající politiky, hovory a úlohy se nemění.
• 8. 10. 2026 (1.32.1): Pole from u zprávy zůstává interní štítek volai a OpenAPI ho nově popisuje; popis pole source říká, že hodnota inbound u zpráv nevzniká. Instrukce MCP serveru, SKILL.md a llms soubory říkají totéž. Chování API se nemění.
• 8. 10. 2026 (1.32.0): Uloží výslovný seznam vlastních aktivních agentů motoru pro zákazníky s jednoznačným skutečným odchozím hovorem z tohoto čísla během lookbackSecs (60-604800 sekund). Neznámý, nejednoznačný nebo neověřený volající zůstane u výchozího agenta. Prázdné agentIds politiku vypne. Volitelná firstMessage platí jen pro ověřený callback. engineSyncRequired: true znamená, že je nutné samostatně aktivovat webhooks.inbound_route_url v konfiguraci motoru výchozího agenta a ověřit ji čtením; tento požadavek živou konfiguraci motoru nepřepisuje. Detail ověřeného příchozího hovoru obsahuje callbackOf.callId a případně serverové taskId a taskItemId. Nové REST GET/PUT /v1/numbers/{e164}/callback-routing a MCP get_callback_routing / set_callback_routing. Podepsaný kontext nástroje příchozího hovoru nese direction=in a prázdný dispatch/task/item. Serverový volai_call_mode=campaign_callback se nastaví jen při ověřené vazbě. Ověřený příchozí lidský kontakt ukončí další plánované pokusy stejné položky úlohy, bez přidání odchozího pokusu nebo ceny. Již běžící hovor a jeho účtování doběhnou. Serverová vazba dispatch/task/item se uchovává osm dní pro celé callback okno.
• 8. 10. 2026 (1.31.0): POST /v1/tasks, PATCH /v1/tasks/{id}, create_task a update_task přijímají nepovinné retryPolicy: "lorela_enterprise" a expiresAt (kladné bezpečné celé číslo, Unix ms); obě pole se vracejí ve veřejném úkolu. Bez politiky zůstává maxAttempts 1-3, při založení výchozí 1; s politikou 1-4, při založení výchozí 4. PATCH bez limitu jej nemění. Politiku lze zapnout jen před prvním pokusem o dispatch. Druhý pokus je nejdřív osm minut od začátku prvního skutečného pokusu, v 08:00-22:00 Europe/Prague; třetí v dalším jiném okně 08:00-09:00 nebo 17:00-19:00; čtvrtý v opačném okně následující kalendářní den. Užší callingWindow včetně dnů platí dál. Opakovat lze jen no_answer, missed, busy nebo dokončenou hlasovou schránku bez kontaktu s člověkem; nejistý výsledek a chyba motoru vyžadují kontrolu. Politika nepovoluje ruční resolve s action: "retry" a po pěti dnech od prvního skutečného pokusu už nevolá. expiresAt platí i bez politiky a brání novému vytočení od termínu včetně prvního pokusu; probíhající hovor doběhne. DNC ani automatická blokace po třech neúspěších za 24 hodin se neobcházejí, takže čtvrtý pokus nemusí proběhnout.
• 5. 10. 2026 (1.30.2): Hovor, u kterého motor caller_loop do post-callu nepošle (volající nejdřív mluvil s agentem a teprve potom na lince zůstala jen opakovaná hláška), má endReason: "completed" a běžnou cenu jako každý jiný dokončený hovor. Záložní synchronizace ztraceného post-callu (GET /v1/calls motoru) nově čte metrics.caller_loop_reported: hodnota 1 znamená, že motor caller_loop do post-callu poslal, a caller_loop se převezme jako dosud; hodnota 0 znamená běžný hovor, který se uzavře a naúčtuje s endReason: "completed" bez ohledu na metrics.caller_loop_released. U staršího motoru bez tohoto pole platí dosavadní pravidlo s metrics.caller_loop_released (kladná hodnota znamená běžný hovor). Tvary odpovědí REST a MCP, hodnoty endReason ani filtr outcome se nemění.
• 4. 10. 2026 (1.30.1): endReason: "caller_loop" a priceHal: 0 se nově přidělují jen příchozímu hovoru s kladným durationSecs; odchozí hovor nebo hovor s nulovou délkou, ke kterému motor pošle termination_reason: "caller_loop", jde běžnou cestou (endReason: "completed" a běžné účtování, hovor s nulovou délkou zůstává neuzavřený jako dosud). Záložní synchronizace ztraceného post-callu (GET /v1/calls motoru) převezme caller_loop jen tehdy, když metrics.caller_loop_released chybí nebo je 0; při kladné hodnotě (během čekání se ozval člověk) se hovor uzavře a naúčtuje jako každý jiný dokončený hovor s endReason: "completed" a call.completed nese cenu, stejně jako když post-call dorazí sám. Hovor s endReason: "caller_loop" se v portálu nikdy nezařadí mezi hovory k pozornosti (Přehled a filtr v Hovorech) a týdenní e-mailový souhrn ho nepočítá mezi vyřízené hovory ani volající a neuvádí ho mezi hovory, které potřebují reakci. Tvary odpovědí REST a MCP, hodnoty endReason a filtr outcome se nemění.
• 4. 10. 2026 (1.30.0): Nová hodnota endReason: "caller_loop" (REST GET /v1/calls a GET /v1/calls/{id}, MCP list_calls a get_call, webhook call.completed): příchozí hovor, kde volající byl automat opakující pořád tutéž hlášku (fronta, vytáčecí systém) a který motor ukončil pojistkou. Zdrojem je metadata.engine.termination_reason: "caller_loop" v post-callu motoru (u ztraceného post-callu totéž pole z GET /v1/calls motoru). Hovor má status: "completed", kladné durationSecs a priceHal: 0, z kreditu se nic nestrhne; cena 0 platí do pěti minut délky hovoru, delší hovor se účtuje podle běžného ceníku a endReason zůstává caller_loop. Webhook call.completed nese endReason: "caller_loop". Hovor, ve kterém se během čekání ozval člověk a motor s ním pokračoval, caller_loop nedostane. Ve filtru outcome (GET /v1/calls, list_calls) takový hovor patří do agent.
• 4. 10. 2026 (1.29.6): PATCH /v1/agents/{id}, update_agent i publikace konceptu: změna language z jazyka, ve kterém noví agenti vznikají na ElevenLabs (dnes en, de, pl), na jazyk, ve kterém vznikají na motoru (cs, sk), spustí u agenta s provider: "elevenlabs" po uložení stejný pokus o převod na motor jako zapnutí transferTo. Při úspěchu má agent provider: "engine" a výchozí hlas motoru pro nový jazyk (milena, katarina), při selhání zůstává na ElevenLabs. Změna mezi cs a sk nic nepřesouvá. voicemail_requires_engine má nové znění: při založení radí useForOutboundTasks: true, u existujícího agenta podporu.
• 4. 10. 2026 (1.29.5): POST /v1/agents a create_agent vracejí v warnings nový kód elevenlabs_by_explicit_choice ({code, message: {cs, en}}), když požadavek poslal useForOutboundTasks: false, výchozí nastavení nasazení by pro jazyk agenta zvolilo motor a agent na ElevenLabs opravdu zůstal (přepojení transferTo ho mohlo na motor přepnout). Agent se založí jako dřív, kód nic neblokuje. PATCH /v1/agents/{id}, publikace ani rollback konceptu ho nevracejí.
• 3. 10. 2026 (1.29.4): Jen dokumentace, chování API se nemění. maxAttempts (1-3) je nejvyšší počet automatických vytočení jednoho kontaktu včetně prvního; 1 znamená bez opakování. Kontakt, kterému po vyčerpání pokusů dáš resolve s action: "retry", dostane ještě jedno vytočení navíc. Počítá se každý pokus, při kterém hovor mohl proběhnout (nezvednutý, odmítnutý volaným i s nejistým výsledkem). Nepočítá se pokus odmítnutý před vytočením, který má items[].attempts[].countsAsAttempt: false.
• 3. 10. 2026 (1.29.3): Pro pokusy zaznamenané od této verze je items[].attempts[].countsAsAttempt rovno false pro všechny kódy, kdy hovor prokazatelně nevznikl, takže se nezapočítají do 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 a destination_busy. Dřív se trvalé překážky v čísle (invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number) počítaly, takže po zrušení blokace a dalším odmítnutí ukazoval kontakt více pokusů, než kolik jich bylo povoleno, přestože se nevolalo. Pokusy zapsané před touto verzí se zpětně nepřepisují (výjimkou je pokus, jehož záměr vytočení uzavře oprava účtování). Nejisté chyby vytáčení (například engine_unavailable) se počítají dál, protože hovor mohl vzniknout. Trvalá překážka dál posílá kontakt do review (rozhoduješ ty), opravitelný kód (chybějící kredit, agent bez čísla a podobně) úkol pozastaví; rate_limited a relay_lease_limit úkol nechají běžet a jen počkají. Nic se kvůli tomu nevytáčí dokola. Kontakt, který po vyčerpání pokusů vrátíš přes resolve s retry, nově po opravitelné chybě vytočení bez hovoru (například insufficient_credit) zůstane pending a po nápravě se znovu vytočí; dřív zůstal failed a úkol nešel spustit (task_not_startable).
• 3. 10. 2026 (1.29.2): destination_busy při vytáčení z úkolu (hovor prokazatelně nevznikl): kontakt čeká dál (failed, když už měl započítaný pokus a má volný další, jinak pending) s items[].lastError: "destination_busy" a items[].nextAttemptAt podle zbývající doby zámku čísla (nejméně 30 s, nejvýš 16 min, bez zámku 90 s), pokus má countsAsAttempt: false, rezervace v reservedBudgetHal se uvolní a ostatní kontakty běží dál; lastError úkolu se nenastavuje, jen se smaže zastaralý čekací rate_limited nebo relay_lease_limit, protože obsazení dokazuje, že limit prošel. Po 6. obsazení za sebou (tedy po 5 čekáních) jde kontakt do review s reviewReason: "dial:destination_busy". Sedm trvalých kódů (on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, invalid_number, unsupported_country, blocked_destination) pošle kontakt do review s reviewReason: "dial:<kód>", ale úkol zůstává running a do needs_attention přejde, až nezbude jiná práce (dřív hned). V API a MCP se blokace ruší dvěma voláními: POST /v1/dnc/{e164}/unblock (unblock_destination), pak resolve s action: "retry" (resolve_task_item); u vlastního čísla, čísla jiného účtu volai, neplatného čísla, čísla mimo Česko a Slovensko a prémiové linky pomůže jen skip. Kontakt v review se může objevit i u běžícího úkolu; resolve pak vrací 409 task_not_editable, takže počkej na needs_attention, nebo úkol pozastav. POST /v1/calls se nemění.
• 2. 10. 2026 (1.29.1): items[].providerCallId ukazuje jen na hovor posledního pokusu: kontakt ve stavu failed, který čeká na další pokus, ho nenese; hovor každého pokusu zůstává v items[].attempts[].providerCallId. Dřív na položce zůstal hovor prvního pokusu, další vytočený hovor se do úkolu nezapsal a kontakt se vytáčel znovu bez započtení pokusu a bez promítnutí ceny do spentHal. Chyby on_dnc, destination_auto_blocked, cannot_call_own_number a cannot_call_volai_number při vytáčení z úkolu jsou prokazatelně nevytočené: pokus má outcome: "failed", rezervace v reservedBudgetHal se uvolní hned a kontakt jde do review s reviewReason: "dial:<kód>" (dřív outcome: "unknown" a držená rezervace). POST /v1/tasks/{id}/start už nevrací 409 task_needs_attention kvůli rezervaci, kterou nedrží žádný kontakt; POST /v1/tasks/{id}/reconcile takovou rezervaci srovná a uzavře i starší otevřený záměr po nevytočeném pokusu.
• 2. 10. 2026 (1.29.0): Nový endpoint POST /v1/numbers/orders/{id}/cancel (bez těla) a MCP nástroj cancel_number_order: objednávka pending přejde do nového stavu cancelled (nová hodnota status objednávky v GET /v1/numbers/orders a list_number_orders); provisioning vrací 409 in_progress, done a failed 409 invalid_transition, cizí nebo neznámé id 404 not_found; opakované zrušení vrací objednávku beze změny. Zrušená objednávka se nepočítá do brány prvního dobití (jedno číslo na účet bez dobití). callingWindow.end u úkolů je včetně celé minuty (current <= end): okno 00:00-23:59 pokrývá celý den a window_closed v minutě end už nepřijde.
• 30. 9. 2026 (1.28.1): PATCH /v1/numbers/{e164} (MCP set_number_routing) s mode: "forward" vrací 402 insufficient_credit, pokud účet ještě nikdy nedobil kredit a číslo zatím není přesměrované. Číslo, které už ve forward je, jde přesměrovat na jiný cíl i bez dobití. POST /v1/numbers (MCP buy_number) a POST /v1/numbers/orders (MCP order_number_from_region) vrací 402 insufficient_credit při pokusu o další číslo, když účet bez dobití už drží aktivní číslo nebo má otevřenou objednávku (pending, provisioning). Stejný kód a příčina (account) jako u SMS, jiný text hlášky - říká, co udělat (první dobití kreditu); nic se neúčtuje. Po prvním dobití kreditu (karta, automatické dobití) omezení mizí.
• 25. 9. 2026 (1.28.0): Nové pole suspended: boolean u agenta (REST i MCP, GET/POST/PATCH /v1/agents). Nové chybové kódy agent_suspended a account_suspended (403, cause: "account") - account_suspended na každém REST volání s API klíčem a v každém MCP nástroji (po rate limitu) kromě čtení daňových dokladů (GET /v1/billing/documents, /{id} a /{id}/pdf, MCP list_billing_documents a get_billing_document), které zůstávají dostupné; agent_suspended na POST /v1/calls, POST /v1/agents/{id}/test-call a POST /v1/tasks/{id}/start. Příchozí hovor zablokovaný pozastavením agenta nebo účtu nese endReason: "suspended" (nová hodnota vedle credit_blocked, cena 0). Odpověď account_suspended/agent_suspended se nikdy neukládá pod Idempotency-Key, ať stejný klíč po obnovení projde. Klíče vlastních proměnných (variables u POST /v1/calls a make_call) nově nesmí začínat předponou volai_ - je vyhrazená pro proměnné, které doplňuje volai (například volai_block_reason), a takový požadavek vrátí 400 validation; u úkolů se takový klíč odmítne až při vytáčení kontaktu. Pozastavení a obnovení dělá výhradně provozovatel v adminu - REST ani MCP pro to vlastní nástroj nemá. Věta, kterou volající slyší na zablokované lince (dluh i pozastavení), teď zní v jazyce agenta (cs, sk, en, de, pl).
• 25. 9. 2026 (1.27.3): Beze změny rozhraní: stejný kód warnings agent_misuse_suspected ve stejných odpovědích REST i MCP, jen širší rozpoznávání.
• 24. 9. 2026 (1.27.2): Odchozí úkoly: relay_lease_limit z vytáčení (kvóta 2 souběžných hovorů agenta na účet) se chová jako rate_limited - úkol zůstává running, nastaví lastError: "relay_lease_limit", pokus se nezapočítá (countsAsAttempt: false) a čekající kontakty dostanou items[].nextAttemptAt za minutu. Dřív šla položka do review s reviewReason: "dial:relay_lease_limit" a úkol do needs_attention. Synchronizace s motorem (GET /v1/calls) čte nové pole attempt_id odchozího hovoru a páruje jím záznam initiated po nejistém vytočení (bez call_sid, i u agenta bez vlastního čísla); po spárování přijde call.completed s cenou a uvolní se relay linka i kvóta. Vyžaduje motor s attempt_id ve výpisu hovorů; starší výpis se chová jako dřív.
• 24. 9. 2026 (1.27.1): POST /v1/calls s agentId na agentovi vlastního motoru, zkušební hovor se systemPrompt, MCP make_call a odchozí úkoly: když vytočení u motoru skončí timeoutem, přerušeným spojením, odpovědí 500/504 nebo nečitelnou 2xx, vrací se dál 502 engine_unavailable, ale hovor zůstává initiated (bez priceHal), relay linka se neuvolní a stejné to je 15 minut zamčené (destination_busy); kvóta souběžných hovorů se uvolní hned. Když hovor proběhl, výsledek a cenu doplní post-call nebo synchronizace s motorem (post-call ho nově najde i bez call_sid podle identifikátoru pokusu, i u agenta bez vlastního čísla) a přijde call.completed; když ne, uzavře ho po 2 h watchdog jako failed s priceHal: 0. Webhook call.failed se u nejistého vytočení neposílá. Jisté selhání (spojení s motorem vůbec nevzniklo nebo vypršelo jeho navazování, 4xx, 502/503) se chová jako dřív: failed, priceHal: 0, call.failed.
• 24. 9. 2026 (1.27.0): Nový kód warnings agent_misuse_suspected ({code, message: {cs, en}}). Objevuje se v POST/PATCH /v1/agents, PUT /v1/agents/{id}/draft, POST /v1/agents/{id}/simulate, POST .../draft/publish, POST .../draft/rollback, POST /v1/calls (prompt zkušebního hovoru nebo variables), POST/PATCH /v1/tasks, POST/PATCH /v1/tools a odpovídajících MCP nástrojích (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). Pole warnings je nepovinné, chybí, když není co hlásit, a /openapi.json ho popisuje u všech těchto odpovědí.
• 24. 9. 2026 (1.26.3): POST /v1/calls s from (bridge) a MCP make_call: když objednávka spojení u telefonního operátora skončí síťovou chybou, timeoutem nebo odpovědí 429/5xx, vrací se úspěch se status: "initiated" místo 502 callback_failed a hovor zůstává initiated, dokud ho cdr-sync nespáruje s CDR (a nezaúčtuje), nebo po 24 h uzavře watchdog jako failed s priceHal: 0. callback_failed teď znamená jen prokazatelné odmítnutí operátorem (chybová odpověď nebo 4xx). Webhook call.failed se u nejisté objednávky neposílá; stejné číslo to zůstává asi 10 minut zamčené (destination_busy).
• 24. 9. 2026 (1.26.2): Strop hovorů na účet za 24 hodin (sdílený POST /v1/calls s agentem i mostem, relay a zkušebními hovory, MCP make_call i odchozími úkoly) je nově 1000 místo 200. Po jeho vyčerpání dál 429 rate_limited s hláškou o denním limitu; 10/min, souběžnost a rozpočet motoru se nemění.
• 24. 9. 2026 (1.26.1): Odchozí úkoly: záznam hovoru ve stavu failed bez conversationId a bez priceHal (vytočení motor odmítl nebo nepotvrdil) se v reconcile usadí na 0 - dřív položka zůstala reviewReason: "billing_unknown" a úkol needs_attention navždy. resolve se skip u položky billing_unknown přepne úkol se zbývající prací do paused (rezervace původního hovoru se dál počítá do reservedBudgetHal a start ji toleruje); retry dál čeká na cenu. Rozhodnutí hned po chybě vytočení (reviewReason: "dial:...") už neztratí vazbu na hovor ani rezervaci. rate_limited při vytáčení (limit motoru, 10 hovorů za minutu, 200 za den) nechá úkol running s lastError: "rate_limited" a čekajícím položkám nastaví nextAttemptAt na konec limitu (podle Retry-After, jinak za 5 minut, nejvýš 24 hodin) místo paused; pokus se nezapočítá. invalid_workflow a engine_not_configured při vytáčení jsou prokazatelně bez hovoru (úkol paused, pokus se nezapočítá). Každý hovor agenta na vlastním motoru, který motor nevytočil (odchozí úkoly i POST /v1/calls, MCP make_call a portál), má v GET /v1/calls priceHal: 0 a durationSecs: 0 místo chybějících hodnot; webhook call.failed se nemění.
• 24. 9. 2026 (1.26.0): POST /v1/calls s agentId na agentovi vlastního motoru (a MCP make_call): odmítnutí limitem odchozích minut motoru (hodinový a denní koš na účet) nebo plnou souběžností motoru je nově 429 rate_limited místo 502 engine_unavailable; u limitu minut s hlavičkou Retry-After (vteřiny do konce hodinového okna, u denního do půlnoci UTC). Nic se nevytočilo ani neúčtovalo; hovor v historii zůstává jako failed a webhook call.failed nese reason: "rate_limited". Odchozí úkoly berou rate_limited (i z limitu 10 hovorů za minutu a 200 za den) jako prokazatelně bez hovoru: položka failed bez započtení pokusu, úkol paused místo needs_attention. Chybová tabulka POST /v1/calls nově uvádí i 502 engine_unavailable - u agenta na vlastním motoru znamená jen skutečný výpadek motoru, ne limit.
• 23. 9. 2026 (1.25.0): Nové volitelné pole event_id v obálce webhooku ({event, data, ts, event_id}) u call.completed/call.failed/call.no_answer/call.missed - message.sent a testovací webhook.test beze změny. Neúspěšné doručení těchto čtyř událostí po 3 pokusech (3 s odstup) nekončí: zůstává ve frontě a doručí se v následujících minutách, nejvýš do 5 kol; opakované doručení nese bajtově stejné tělo. GET /v1/webhook/deliveries (i MCP list_webhook_deliveries) teď ukazuje i mezistavy před posledním kolem, attempts je součet pokusů napříč všemi koly, a nově nese volitelné pole eventId.
• 23. 9. 2026 (1.24.1): Dva nové kódy warnings: prompt_variables_unavailable_inbound (agent s numberE164, jehož systemPrompt/firstMessage obsahuje {{promennou}} mimo sadu, kterou příchozí hovor doopravdy dodává) a first_message_empty (firstMessage, ve které po odstranění všech {{...}} bloků nezůstane žádné písmeno ani číslice mimo proměnné). REST (POST/PATCH /v1/agents, publikace a návrat konceptu) i MCP (create_agent, update_agent, publish_agent_draft, rollback_agent_draft) čtou stejný zdroj jako editor agenta v portálu (agentWarnings).
• 20. 9. 2026 (1.24.0): Nové nepovinné pole busyCalendarIds u agenta (POST/PATCH /v1/agents, MCP create_agent/update_agent, koncepty) i u hledání volna a zakládání události bez agenta (POST /v1/integrations/{id}/availability, POST /v1/integrations/{id}/events, MCP find_free_slots, create_calendar_event). Kalendáře se čtou paralelně; selhání kteréhokoli z nich je chyba celého hledání, aby se nenabídl termín přes neviditelnou schůzku. Nejvýš čtyři, bez duplicit a bez calendarId; jinak 400 calendar_invalid_rules, neznámý kalendář 400 calendar_invalid_calendar.
• 20. 9. 2026 (1.23.4): Chybové tabulky POST /v1/agents, PATCH /v1/agents/{id} a publikace i návratu konceptu doplňují šestici, kterou vrací validateCalendar: 404 calendar_integration_not_found a 400 calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules. Propisuje se do openapi.json, reference /docs/api, SKILL.md i llms-full.txt.
• 20. 9. 2026 (1.23.3): maybeQueueMissedCallSms spouští SMS i pro odchozí hovor s answeredBy: "voicemail" (dosud jen status: "no_answer" a příchozí missed). Hlasové menu (ivr) ani unknown SMS nespouští. Ostatní podmínky (jen CZ/SK číslo, DNC, blokace, jedna SMS na číslo za 24 h, noční klid, poslední pokus úkolu) platí beze změny; CallRecord.missedSms se zapisuje stejně.
• 19. 9. 2026 (1.23.2): Čas s milisekundami se formátoval s posunem zóny o minutu menším (+01:59 místo +02:00) - týkalo se to pole now v nástrojích agenta i začátku zakládané události, když klient poslal start se zlomky sekund. Náhradní termíny u 409 calendar_slot_taken (POST /v1/integrations/{id}/events, MCP create_calendar_event) se počítají od požadovaného termínu, stejně jako find_free_slots se zadaným časem.
• 19. 9. 2026 (1.23.1): Pole calendar u agenta (POST/PATCH /v1/agents, MCP create_agent/update_agent a koncepty) odmítne kalendář s accessRole reader nebo freeBusyReader chybou 400 calendar_invalid_calendar - agent do téhož kalendáře schůzky zapisuje. Roli vrací list_calendars jako accessRole, pokud ji poskytovatel uvádí; kalendář bez uvedené role projde jako dřív. Ostatní chybové kódy se nemění.
• 19. 9. 2026 (1.23.0): Nové pole CallRecord.rating (value: "good" | "bad", reason?, note?, at, source: "portal" | "email" | "api" | "mcp") a CallRecord.missedSms; PATCH /v1/calls/{id} a MCP annotate_call přijímají rating/ratingReason/ratingNote (patchCallAnnotation volá rateCall se source: "api"/"mcp"). Nové pole AgentRecord.missedCallSms { enabled, text? } (proměnné {firma}, {cislo}, {agent}) v POST/PATCH /v1/agents, GET /v1/agents/{id} a MCP create_agent/update_agent/get_agent/save_agent_draft. GET/PATCH /v1/account a MCP get_account/update_account mají companyName (max 80 znaků, prázdný řetězec maže) a GET nově vrací notifications.weeklySummary. Zkušební hovor v editoru agenta ukazuje výsledek podle cíle hovoru (call.evaluation.goal) a zapsaná data.
• 18. 9. 2026 (1.22.0): Nové endpointy POST /v1/integrations/{id}/availability (volné sloty bez uloženého agenta - windows chybí = 24 hodin každý den) a POST /v1/integrations/{id}/events (založení schůzky, vyžaduje confirm: true, nepovinný idempotencyKey pro bezpečné opakování; 409 calendar_slot_taken při kolizi), MCP nástroje find_free_slots a create_calendar_event se stejným tvarem. DELETE /v1/integrations/{id} nově vrací affectedAgents - agenty, kterým odpojení integrace vypnulo pole calendar. Nové pole calendar u POST/PATCH /v1/agents, GET /v1/agents/{id} a MCP create_agent/update_agent/get_agent: integrationId, calendarId, timezone, slotMinutes, minNoticeMinutes, horizonDays, bufferMinutes, windows (pole oken {from,to} pro každý den v týdnu). Funguje jen na vlastním motoru volai (provider: "engine") - u agenta na ElevenLabs se pole uloží a čeká na varování calendar_pending_engine_switch, dokud agent nepřepne. Jedenáct nových chybových kódů s 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. 9. 2026 (1.21.0): Nový typ pohybu ledgeru setup_revision (GET /v1/credit/ledger, MCP) pro kolo úprav objednávky Na klíč nad rámec balíčku, částka SETUP_EXTRA_REVISION_HAL (490 Kč bez DPH). Daňové doklady (GET /v1/billing/documents, .../{id}, list_billing_documents, get_billing_document) mají nově vždy vyplněné pole kind ("invoice" - výchozí, nebo "credit_note") a k němu volitelná pole correctsNumber a correctionReason; dobropis k vratce zřízení Na klíč se čísluje vlastní řadou OD a nese kladné částky (znaménko dává PDF). credit() (lib/service/balance.ts) dostal interní parametr notifyTelegram - platba Na klíč posílá jen jednu Telegram hlášku ("Na klíč: zaplaceno"), ne dvě. Nová veřejná stránka /recepcni-na-klic (anglicky /en/receptionist-done-for-you).
• 18. 9. 2026 (1.20.0): Nové pole laughter (auto/on/off) v POST/PATCH /v1/agents a MCP create_agent/update_agent: auto nechává rozhodnutí na detekci citlivého tématu motoru (dluhy, zdravotnictví, úřady, pohřebnictví), on tuhle detekci přebije, off ho vždy potlačí; vynechaný klíč se uloží i vrací jako auto, nikdy jako chybějící pole. GET /v1/agents/{id} a nový MCP nástroj get_agent (dřív chybějící parita pro detail jednoho agenta) přidávají laughterEffective ({active, reason, sensitiveCategory} | null) uvnitř vráceného objektu agenta, spočtené čerstvě pro publikovanou konfiguraci; null znamená, že se to teď nestihlo zjistit (motor neodpověděl do 3 vteřin, výpadek, nebo tichá 404 u starší verze) - nikdy odhad. MCP update_agent vrací týž objekt jako pole vedle agent, protože PATCH /v1/agents/{id} ho nevrací vůbec. Pole se přijímá a ukládá i u agenta na ElevenLabs, ale bez slyšitelného efektu - přehraje ho jen český hlas Cartesia na vlastním motoru volai.
• 18. 9. 2026 (1.19.0): Nová oblast REST API v1 a MCP - zdroj setup-orders, capability oblast setup (za credit). Sedm endpointů (POST /v1/setup-orders, GET /v1/setup-orders, GET/POST /v1/setup-orders/{id}, .../messages, .../checkout, .../launch, .../cancel) a sedm odpovídajících MCP nástrojů (create_setup_order, list_setup_orders, get_setup_order, message_setup_order, checkout_setup_order, launch_setup_order, cancel_setup_order) nad stejnou servisní vrstvou lib/service/setup-orders.ts. Nabídku počítá vždy katalog v kódu (lib/setup-catalog.ts), model z rozhovoru jen vybírá položky. Nové chybové kódy: setup_order_not_found, order_closed, invalid_transition, quote_pending_confirmation, checkout_open, turn_in_progress, advisor_no_quote, advisor_unavailable, setup_orders_disabled. Dokumentace na /docs/na-klic (anglicky /docs/done-for-you).
• 17. 9. 2026 (1.18.0): Koncept agenta (PUT/GET /v1/agents/{id}/draft, POST /v1/agents/{id}/draft/publish) i MCP save_agent_draft mají teď tříhodnotové numberE164: chybějící klíč nechá číslo agenta beze změny, null ho odpojí, řetězec připojí uvedené číslo - dorovnání parity s PATCH /v1/agents/{id}, který tuhle sémantiku měl už dřív. Čtení konceptu navíc srovnává published.numberE164 vždy se skutečným číslem živého agenta a draft.numberE164 jen tehdy, když koncept o čísle nerozhoduje, takže kontrolní tabulka v editoru i odchozí úkoly vidí pravdivý stav i po připojení nebo přesunu čísla mimo editor; "nerozhoduje" platí i pro řetězec, který se shoduje se ŽIVÝM číslem agenta - taková hodnota se chová jako chybějící klíč, a to znovu při každém čtení konceptu proti tehdy aktuálně živému číslu; přesune-li se číslo později na jiného agenta mimo koncept, stejná uložená hodnota se stane výslovnou volbou a další publikace nebo rollback konceptu ho tomuhle agentovi vezme zpátky - ne potichu: warnings u publikace i rollbacku (REST i obou MCP nástrojů) v tom případě nese nový kód number_changed_by_publish s from/to (E.164, nebo null bez čísla), a ani ten operaci neblokuje. Pozor na zpětnou kompatibilitu čtení: draft.numberE164 teď může v odpovědi přijít jako null (výslovná volba "bez čísla"), kde dřív klíč jen chyběl - klient ho má číst stejně jako chybějící klíč, tedy "agent nemá číslo". Značka "otestováno" a otisk agenta připnutý běžícímu odchozímu úkolu se navíc počítají BEZ telefonního čísla (behaviorFingerprint, ne draftFingerprint), takže připojení ani přesun čísla mimo editor už nevyžaduje nový test a nezastaví běžící kampaň; koncepty s číslem uložené PŘED touhle změnou mají starou značku spočítanou ještě SE číslem, takže si o ni řeknou jednorázově znovu - jeden test nebo publikace po aktualizaci ji obnoví a dál platí nové pravidlo.
• 15. 9. 2026 (1.17.0): Nový stav hodnocení cíle GoalDisplayState (success/failure/unclear/no_conversation/not_evaluated) nahrazuje trojici AgentGoalResult v zobrazení portálu, ve filtrech /hovory a v přehledu. REST a MCP dostaly answeredBy: "ivr", goal.reason ("no_caller_speech"/"evaluation_error") a hasConversation (boolean | null). Parametr goal (GET /v1/calls, MCP list_calls) přijímá pět nových hodnot navíc ke stávající unknown, která zůstává zpětně kompatibilní - dál zahrnuje záznamy bez jasného výsledku (goal.result chybí nebo je unknown): vždy unclear a not_evaluated, u no_conversation jen když má taky výsledek unknown.
• 13. 9. 2026 (1.16.0): Nová hodnota endReason: "engine_error" (status failed) nastává, když motor pošle metadata.engine.termination_reason s hodnotou engine_stall nebo engine_error u hovoru, který se obsluhoval - dřív se pole u takového hovoru zahazovalo. priceHal je 0, jen když hovor ještě žádnou cenu nemá (jinak zůstává, ALERT log). Zákaznický webhook call.failed dostal čtyři nová volitelná pole: durationSecs, priceHal, transcript, summary - vyplněná jen u téhle technické větve, jinde chybí jako dřív. GET /v1/calls/{id} a MCP get_call vrací stejnou hodnotu endReason. Odchozí úkoly (POST /v1/outbound-tasks, MCP) berou engine_error jako opakovatelný pokus (stejná cesta jako no_answer), ne jako důvod k zastavení kampaně, a nezapisují ho do automatické 30denní blokace destinace.
• 13. 9. 2026 (1.15.0): POST/PATCH /v1/agents a MCP create_agent/update_agent/save_agent_draft berou nové pole silencePromptSecs: number | null (celé číslo 3 až 25, null vypíná), meze shodné s motorem (engine/types.py, U1). Chybějící pole při POST/create_agent uloží výchozích 10 - na rozdíl od voicemail se pole přijímá a vrací u OBOU poskytovatelů (GET /v1/agents vrací uloženou hodnotu i u provider: "elevenlabs"). Hodnota mimo meze padá na obecnou validační chybu (validation, 400), žádný nový kód. Existující agenty na motoru dostanou výchozích 10 jednorázovým re-synchronizačním skriptem (scripts/resync-silence-prompt.mts), který mění výhradně tohle jedno pole.
• 13. 9. 2026 (1.14.7): OpenAPI doplňuje popisy všech operací a polí požadavků včetně vnořených variant. Publikuje produktové limity agentů, nástrojů, SMS a hovorů ze společných konstant servisní vrstvy, místo volných technických stropů parseru. Automatická kontrola ověřuje všechny ukázky požadavků a odpovědí proti schématům. Chování API, chybové kódy a nastavení poskytovatelů se nemění.
• 13. 9. 2026 (1.14.6): POST /v1/messages a MCP send_sms vrací insufficient_credit (HTTP 402, cause account), dokud účet nemá kladný pohyb topup (karta i automatické dobíjení) nebo admin (ruční korekce majitele). Končí dřívější strop 3 SMS pro účty bez vlastního aktivního čísla a aktivní číslo už výjimku nedává. První dobití se drží jako trvalý příznak účtu, takže dlouhá historie pohybů zákazníka nikdy nezablokuje.
• 13. 9. 2026 (1.14.5): Nový kód workflow_node_tool_missing ve warnings u POST/PATCH /v1/agents, u publikace i vrácení konceptu a u MCP create_agent, update_agent, publish_agent_draft a rollback_agent_draft. Platí pro oba poskytovatele, protože smazaný nástroj se do fáze nepřenese ani na vlastním motoru. workflow_node_tool_not_synced zůstává jen pro nástroj, který na účtu je, ale agent ho nemá mezi svými. Šablona Recepce nově doporučuje dvě věty do základního promptu: neodhadovat provozní údaje a ptát se jen na jednu věc najednou.
• 12. 9. 2026 (1.14.4): Průvodce rozlišuje identifikátory OAuth souhlasů od API klíčů i při obnově starší uložené volby. Nedostupné ověření není považováno za odvolaný přístup.
• 12. 9. 2026 (1.14.3): Doplněny katalogové soubory katty-studio.mp3 a katty-telefon.mp3 stejným generátorem a obsahem jako ostatní hlasy. Hlas agenta, poskytovatel ani nastavení telefonního provozu se nemění.
• 12. 9. 2026 (1.14.2): Popisky kopírování a dalšího kroku odpovídají zvolenému způsobu připojení. Codex desktop při použití API klíče vede ke konfiguraci config.toml. Zavření mobilního menu zachovává návrat fokusu.
• 12. 9. 2026 (1.14.1): Přihlášení zachovává cíl průvodce. Volba prostředí se ukládá k účtu odděleně od skutečného MCP ověření. Ruční návody zahrnují Claude Code, Codex CLI i desktop a API klíč jako alternativu. Nápověda a názvy Hlasoví agenti, Telefonní čísla a Data a integrace jsou sjednocené.
• 12. 9. 2026 (1.14.0): Při vynechaném useForOutboundTasks záleží na VOLAI_ENGINE_DEFAULT_FOR_NEW, dostupnosti motoru a seznamu VOLAI_ENGINE_DEFAULT_FOR_NEW_LANGUAGES (bez nastavení cs,sk). Samotný jazyk motor nezaručuje. Explicitní true žádá motor, false začne na ElevenLabs. Platí pro portál, POST /v1/agents i MCP create_agent. Po založení ověř provider a voiceId; přepojení může vyvolat další pokus o změnu poskytovatele.
• 12. 9. 2026 (1.13.0): Pole workflow je v POST a PATCH /v1/agents, v konceptu agenta i v MCP nástrojích create_agent, update_agent a save_agent_draft. Hovor, který fázemi prošel, nese workflowPath v GET /v1/calls a GET /v1/calls/{id}. Nová varování workflow_*, workflow_not_synced_to_provider a workflow_node_tool_not_synced upozorní na problémy s nastavením fází.
• 12. 9. 2026 (1.12.5): voiceId pro agenta na ElevenLabs: katty (výchozí, hlas šablony) nebo syrové ElevenLabs id; jana už v katalogu ani u ElevenLabs není (dva agenti z 12. 9. odpoledne přepnuti na Katty, hlas odstraněn z workspace). GET /v1/voices?provider=elevenlabs a MCP list_voices s provider: elevenlabs vrací katty. Záskok motoru na ElevenLabs pro Milenu, Terezu a Katarinu je také Katty.
• 12. 9. 2026 (1.12.4): Pomalé čtení stavu už nepřerušuje pravidelný polling. Evidence úspěšného MCP čtení se dohledá podle aktivního přístupu i při chybě zápisu pomocného indexu. Ověření nadále vyžaduje get_balance nebo list_agents přes MCP.
• 12. 9. 2026 (1.12.3): Opraven anglický odkaz na ochranu kalendářových dat a zobrazení aktivního filtru cíle i v účtu bez dosavadního vyhodnocení. Obě jazykové varianty mají regresní testy odkazů a nedostupných integrací.
• 12. 9. 2026 (1.12.2): MCP průvodce používá existující evidenci úspěšných čtení aktivním API klíčem nebo OAuth souhlasem, bez simulovaného ověření. Filtr goal=unknown v GET /v1/calls a MCP list_calls zahrnuje i záznamy bez hodnocení cíle. Technické dokončení neznamená splněný cíl. REST a MCP nadále vracejí jednotlivé záznamy; portál je seskupuje do konverzací.
• 12. 9. 2026 (1.12.1): voiceId pro agenta na ElevenLabs: jana (výchozí, hlas šablony) nebo syrové ElevenLabs id; anet projde jen agentovi, který ji už má, jinak 400 validation s vysvětlením (dřív 502 eleven_labs_error od ElevenLabs voice_live_moderated_not_allowed). GET /v1/voices?provider=elevenlabs a MCP list_voices s provider: elevenlabs vrací jana. Agent na ElevenLabs bez voiceId dostane Janu výslovně (záznam nese její id). Registrace SIP: operátor vracel 403 INVALID_USER u linek koupených přes API, dokud se u linky jednou nepřepne SIP protokol vypnout/zapnout; opraveno u všech linek a při nákupu nové linky se dělá automaticky.
• 12. 9. 2026 (1.12.0): OAuth authorization code + PKCE S256, DCR, resource-bound opaque tokens, refresh rotation/replay detection, OIDC discovery/JWKS/userinfo a revokace. Access token 10 minut, refresh nejvýše 30 dní, souhlas nejvýše 90 dní. Změna hesla zneplatní OAuth přístup. MCP annotations výslovně rozlišují přepisy, placené akce, zprávy a externí vedlejší efekty.
• 12. 9. 2026 (1.11.0): GET /v1/numbers/{e164}/sip a MCP get_sip_credentials: outboundTrunkAddress = sip.volai.cz (vlastní SIP proxy volai s digest ověřením, realm sip.volai.cz; naměřeno: platforma odmítne INVITE větší než UDP MTU, přes TCP tentýž hovor projde), transport = tcp (schéma nově enum [tcp, udp], UDP funguje také), port 5060 beze změny. Watchdog hlídá healthz proxy (SIP_PROXY_HEALTHZ_URL): ops e-mail při nedostupnosti, zastavené synchronizaci ověřovacích dat nebo certifikátu pod 14 dní. Post-call webhook ElevenLabs má v produkci HMAC tajemství, zapíná se per agent (ELEVENLABS_POST_CALL_WEBHOOK_ID).
• 12. 9. 2026 (1.10.0): GET /v1/numbers/{e164}/sip a MCP get_sip_credentials: outboundTrunkAddress se řídí samostatnou konfigurací (může být shodná se server), popisy polí bez zmínek o realmu; inboundSignallingCidrs beze změny. Post-call webhook ElevenLabs páruje příchozí hovory přes metadata.phone_call.call_sid (dřív četl SIP Call-ID call_id, který se nikdy neshodoval s klíčem call:sid z initiation webhooku) sdílenou findExistingCallByKeys s cronem conversations-sync (pořadí call:conv -> call:attempt -> call:sid). Per-agent nastavení post-call webhooku (platform_settings.workspace_overrides.webhooks) migruje cron, jakmile je nastavené ELEVENLABS_POST_CALL_WEBHOOK_ID; do té doby hovory dál uzavírá cron. Post-call z vlastního motoru přijímá phone_call.external_number: null a caller_presentation; prefix uri_ u volajícího se odstraňuje jako v initiation webhooku. Cíl přepojení hovoru (transfer_to_number) se skládá ze samostatné VOLAI_SIP_TRANSFER_HOST, ne z veřejné SIP domény. Nový interní zdroj ověřovacích dat pro SIP proxy (GET /api/internal/sip-subscribers, mimo v1, bearer + IP allowlist + rate limit).
• 12. 9. 2026 (1.9.0): POST/PATCH /v1/agents a MCP create_agent/update_agent teď mohou vrátit druhý kód ve warnings: first_message_too_long, nezávisle na first_message_no_ai_disclosure - a stejné warnings od teď vrací i publikace konceptu agenta (POST /v1/agents/{id}/draft/publish, MCP publish_agent_draft) a jeho vrácení na dřívější revizi (POST /v1/agents/{id}/draft/rollback, MCP rollback_agent_draft), kde dřív chyběly úplně - obojí totiž propisuje první větu na živého agenta. Odhad počítá slova, číslice po znacích a velké zkratky do čtyř znaků; delší velké slovo se čte jako jedno slovo, ať firma psaná kapitálkami odhad uměle nenafoukne. Jediný práh (odhadovaná doba nad 7 sekund) se měří nad tím, co volající doopravdy slyší - pozdrav plus věta o nahrávání, když je zapnuté. Nezměněná výchozí šablona pozdravu varování nikdy nedostane, jen text, který zákazník upravil.
• 12. 9. 2026 (1.8.2): V dokumentaci, integračních návodech i chybových hláškách najdeš přístupy pod názvem AI asistent. MCP jasně říká, že hlasový motor je potřeba až pro spuštění odchozího úkolu; založit lze i úkol s agentem na ElevenLabs.
• 12. 9. 2026 (1.8.1): OpenAPI doplňuje Idempotency-Key pro 14 podporovaných operací, response hlavičky a nepovinné JSON tělo s revision při smazání úkolu. Oprava popisů bez změny chování placených akcí: useForOutboundTasks rozlišuje true/false/vynechání, úkoly mají limit 1000 příjemců a billing_unknown zachovává původní hovor i rezervaci do zjištění ceny. Daňové doklady kreditu jsou dostupné v REST a MCP, API klíč může přes REST odvolat jen sám sebe, odpojení integrace je REST/portál. Oprava údaje z 1.6.1: preview_task_csv není MCP nástroj; CSV náhled je POST /v1/tasks/csv-preview nebo portál. Instalační příkazy sdílejí generátor s průvodcem, přepínače příkladů mají unikátní kotvy a Python zachovává JSON hodnoty.
• 11. 9. 2026 (1.8.0): Nové REST POST /v1/dnc/{e164}/unblock a odpovídající MCP nástroj unblock_destination ruší automatickou blokaci destinace; fungují i pro blokace založené před tímhle nasazením. Starší blokace mohou ve výpisu GET /v1/dnc a list_dnc chybět, protože vznikly před jeho indexem, ale přímé odblokování podle čísla funguje. Indexované blokace se vracejí vedle beze změny zachovaného numbers v poli blocked: [{e164, blockedAt, expiresAt}], kde jsou časy unix milisekundy. Po odblokování se čítač neúspěšných pokusů počítá od nuly - tři nové neúspěšné pokusy na stejné číslo blokaci vrátí a odblokovat lze opakovaně. groupCallsByConversation (sdílený primitiv pro /hovory, export CSV, navigaci Předchozí/Další i statistiky) řadí podle representative.startedAt sestupně, dřív podle key, tedy podle abecedy identifikátoru konverzace. TestCallOutcome má novou hodnotu no_answer oddělenou od failed, ať panel netvrdí příčinu, kterou nezná. Vokativ jména psaného celými verzálkami je nově taky verzálkami (RADEK -> RADKU) v e-mailu i v hlavičce Přehledu.
• 11. 9. 2026 (1.7.1): agent_busy (HTTP 409, cause: "busy") přibyl do sdílené chybové mapy PUBLIC_ERROR_HTTP/PUBLIC_ERROR_CAUSE (lib/types.ts). Vrací ji switchAgentProvider (lib/service/engine-provider.ts) - jediná admin akce portálu, která poskytovatele agenta přepíná, REST v1 ani MCP takový vstup nemají (agents.switch_provider v katalogu schopností, lib/capabilities.ts). Kontrolu dělá nový klient GET /v1/calls/active (lib/engine.ts listActiveCalls): hovor agenta se páruje PRIMÁRNĚ podle pole agent_id, které motor u běžícího hovoru nese od nasazení verze s tímhle polem, číslo zůstává záloha pro starší motor bez něj.
• 11. 9. 2026 (1.7.0): POST/PATCH /v1/agents a MCP create_agent/update_agent/save_agent_draft berou nové pole voicemail: {enabled, action: "mark"|"hangup"|"message", message?} - jen u agenta s provider: "engine", jinak voicemail_requires_engine; message je povinná při action: "message", do 400 znaků (invalid_voicemail_message). GET /v1/agents vrací nastavenou hodnotu. Post-call z motoru nese answered_by/voicemail_reason/voicemail_message_left/voicemail_detected_at_secs; answered_by má přednost před dosavadním odhadem z přepisu hovoru (lib/answered-by.ts) jen hodnotami human a voicemail - unknown se bere jako "motor nerozhodl" a použije se odhad z přepisu. GET/list_calls/get_call u odchozích hovorů motoru navíc vrací voicemailReason (čtvrtá hodnota human_reply - krátká odpověď člověka), voicemailMessageLeft a voicemailDetectedAtSecs.
• 11. 9. 2026 (1.6.5): Motor u odchozího hovoru ukončeného před zvednutím smaže místnost a pošle post-call: prázdný přepis, call_duration_secs: 0 a nové aditivní pole metadata.engine.termination_reason (no_answer nebo disconnected_before_answer). Hovor dostane status: no_answer, endReason: no_answer a cenu 0 jako dřív, jen hned. Rekonciliace GET /v1/calls páruje odchozí hovory motoru přes call_sid a u nespojených posílá nulovou délku. GET /openapi.json: answeredBy má description o omezení na odchozí hovory.
• 11. 9. 2026 (1.6.4): POST /v1/tasks a PATCH /v1/tasks/{id} (i create_task/update_task v MCP) přijímají recipients do 1000 položek, POST /v1/tasks/csv-preview do 1000 řádků. Nová kontrola velikosti záznamu úkolu (2 MB serializovaného JSONu) vrací validation s polem recipients.
• 11. 9. 2026 (1.6.3): Initiation webhook ElevenLabs: agent_id z payloadu se teď porovnává s elevenAgentId NEBO id agenta dohledaného přes routing čísla - cizí agent_id dostane jen minimální odpověď bez conversation_config_override; stejná kontrola chrání uzavírání konverzace v post-call webhooku i cronu synchronizace konverzací. Cron synchronizace CDR: nerozpoznaný odchozí CDR záznam z vlastní linky (mimo demo číslo), starší než 600 s a bez nejasně spárovatelného existujícího záznamu, se naúčtuje jako kind: "sip" odchozí sazbou bez agentní přirážky (v GET /v1/calls se objeví s kind: "sip"; čítač chargedSip je jen v odpovědi cronu, ne ve veřejném API); mladší nebo nejasně spárovatelný záznam se dál jen podrží pro ruční kontrolu. CallKind rozšířen o "sip". Tvar CDR záznamu skutečného SIP klienta zatím nemá produkční ověření (žádný registrovaný softphone) - proto obě pojistky.
• 11. 9. 2026 (1.6.2): Nový endpoint POST /v1/tasks/{id}/items/{itemId}/resolve s tělem { action: "retry" | "skip", revision } a MCP nástroj resolve_task_item; nový chybový kód item_not_resolvable (409, account), task_not_editable u běžícího nebo hotového úkolu. Synchronizace hovorů motoru páruje vlastní odchozí nohu podle relay linky a času začátku, nezvednutý odchozí hovor zavírá jako no_answer, po uzavření uvolňuje tenant kvótu souběžných hovorů. relay_lease_limit při vytáčení úkolu je dočasný stav bez započítání pokusu.
• 11. 9. 2026 (1.6.1): POST /v1/tasks/csv-preview a portál rozpoznávají sloupec telefonu bez ohledu na velikost písmen, mezery a koncovou dvojtečku a přijímají aliasy (telefon, tel, mobil, phone number); v odpovědi je sloupec vždy phone. Jednosloupcový vstup bez hlavičky, jehož první hodnota je telefon, se bere jako data. Bez sloupce telefonu vrací náhled jedinou chybu phone u hlavičky, ne Phone is required na každém řádku. Kontrakt agent_not_ready se nemění. Oprava popisu 12. 9. 2026: původní zmínka nástroje MCP byla nesprávná; náhled CSV je pouze REST/portál.
• 11. 9. 2026 (1.6.0): GET /v1/numbers/{e164}/sip a MCP get_sip_credentials vrací navíc outboundTrunkAddress, port, transport a inboundSignallingCidrs vedle server/username/password; MCP create_relay_lease a popis nástroje get_sip_credentials teď výslovně rozlišují server (registrace) od outboundTrunkAddress (odchozí trunk platformy). Dokumentace na /docs/vlastni-agent, integrace ElevenLabs i blog už do outbound_trunk_config.address nedosazují server, jen outboundTrunkAddress.
• 11. 9. 2026 (1.5.1): GET /v1/calls, GET /v1/calls/{id}, webhook call.completed a MCP list_calls/get_call: answeredBy je přítomné jen při direction: "out" (i u starších záznamů). POST /v1/messages a send_sms: účet bez aktivního čísla a bez kladného pohybu topup/refund/admin v ledgeru dostane po třech odeslaných SMS insufficient_credit (HTTP 402, cause account).
• 8. 9. 2026 (1.5.0): Nové REST endpointy: GET/PATCH /v1/account, PUT /v1/account/billing, GET /v1/api-keys, DELETE /v1/api-keys/{id} (self-revoke); PATCH /v1/calls/{id} a rozšířené query GET /v1/calls o from, to, agentId, flagged, goal, outcome; POST /v1/tools/test, POST /v1/tools/{id}/test, DELETE /v1/webhook a GET /v1/tools/{id} navíc vrací 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 (bez klíče, x-volai-version na všech v1 odpovědích včetně chyb, 429 a /openapi.json). Odpovídajících 16 nových MCP nástrojů: 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 - odvolání cizího API klíče, tvorba API klíče a odpojení integrace/karty zůstávají REST-only nebo jen v portálu (spec §3). Nový katalog schopností nese capability pole u každého endpointu a nástroje; strážné testy ověřují, že chybová tabulka a ukázka odpovědi na /docs/api sedí na skutečných chybových kódech u všech endpointů. Aditivní, žádný existující status ani kód se nemění. Nový soubor content/changelog.json je jediný zdroj pravdy: /novinky, sekce Historie změn na /docs/api, sekce Versioning v SKILL.md, RSS (/en/feed/<oblast>), GET /v1/changelog a MCP get_changelog jsou nad ním jen generované pohledy. Aditivní, žádný existující obsah nezmizel. Nové REST endpointy: 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. Odpovídajících 7 nových MCP nástrojů: list_tasks, get_task, create_task, update_task, pause_task, reconcile_task, start_task (ten vyžaduje zopakovat skutečný počet příjemců a rozpočet, jinak vrátí chybu s vypsanými skutečnými čísly) - smazání úkolu a náhled CSV zůstávají jen REST a portál (spec §3). Portál: tlačítko Smazat úkol v detailu úkolu s opsáním názvu. Aditivní, žádný existující status ani kód se nemění. Nové REST endpointy: 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 navíc vrací runway a notice. Odpovídajících 6 nových MCP nástrojů: list_ledger, create_topup_link, get_auto_topup, disable_auto_topup, list_billing_documents, get_billing_document (get_balance rozšířen o stejné runway/notice) - get_billing_document nevrací PDF, to zůstává jen přes REST GET /v1/billing/documents/{id}/pdf (binární výstup); zapnutí automatického dobíjení, změna částky a karty zůstávají jen přes odkaz na Stripe Checkout, MCP nemá ani jedno z toho (spec §2, §3). Aditivní, žádný existující status ani kód se nemění. GET /v1/account vrací nové pole notifications.productUpdates (výchozí zapnuto); přepínač je i v Nastavení portálu. Denní e-mailový souhrn (cron 0 6 * * * UTC) posílá jen účtům s ověřeným e-mailem a productUpdates !== false, nejvýš jeden e-mail na účet a den. Hlavička List-Unsubscribe a jednoklikové odhlášení bez cookies platí od teď i pro reaktivační e-mail, pokud je na serveru nastavené UNSUBSCRIBE_SECRET - bez něj e-mail odejde i tak, jen bez odkazu na odhlášení. Aditivní, žádný existující status ani kód se nemění.
• 8. 9. 2026 (1.4.3): Každá vlastnost vstupního schématu všech 44 MCP nástrojů nese vlastní description (vidí ji klient v tools/list; u těla PATCH .../events/{eventId} a PUT /v1/agents/{id}/draft i openapi.json). Fakturační endpointy GET /v1/integrations/{id}/invoices[/{invoiceId}] mají v dokumentaci a v OpenAPI seznam chyb podle skutečné dosažitelnosti - integration_storage_error z nich zmizel, z API nikdy nepřicházel - a validace jejich query vrací lidskou hlášku jako zbytek v1 (stejně GET .../events). Aditivní, žádný status ani kód se nemění.
• 8. 9. 2026 (1.4.2): Oprava čtení a potvrzených úprav Apple událostí: iCloud odmítá hledání podle UID, proto výpis vrací neprůhledné identifikátory zdrojových souborů CalDAV. externalId předávej beze změny jako eventId; Apple identifikátory uložené ze starší verze načti znovu. Neplatný Apple identifikátor vrací 400 calendar_invalid_query. Google identifikátory se nemění.
• 8. 9. 2026 (1.4.1): POST /v1/agents a create_agent berou useForOutboundTasks (volba vlastního hlasového motoru volai při zakládání, stejná jako zaškrtávátko „Používat v odchozích úkolech“ v portálu; bez pole platí výchozí nastavení, dnes ElevenLabs). Aditivní, žádný status ani kód se nemění.
• 8. 9. 2026 (1.4.0): Apple Calendar používá stejný kalendářový tok v REST i MCP jako Google. Fakturoid a ABRA Flexi přinesly endpointy GET /v1/integrations/{id}/invoices[/{invoiceId}] a nástroje list_invoices a get_invoice (rozhraní faktury jen čte). GET /v1/integrations a list_integrations vrací navíc providers s připraveností konfigurace a odkazem pro připojení. Přihlašovací údaje poskytovatele je pořád nutné připojit v portálu. Aditivní, žádný status ani kód se nemění.
• 7. 9. 2026 (1.3.0): Přibyly kalendářové endpointy GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET/PATCH /v1/integrations/{id}/events/{eventId} a šest MCP nástrojů (list_integrations, list_calendars, list_calendar_events, get_calendar_event, propose_calendar_update, confirm_calendar_update) - Google Kalendář tak vstoupil do veřejného rozhraní (čtení a potvrzená úprava události), REST je na 50 endpointech a MCP na 42 nástrojích. Každá chybová odpověď nese navíc cause (request / account / busy / service - kdo chybu opraví) a action (jedna věta, co udělat). Hlášky kódu validation říkají pole, skutečnou hodnotu a přijatý strop místo surového textu validátoru; stropy vstupu u jména, instrukcí, cíle a podkladů agenta jsou desetinásobkem produktových limitů, takže limit hlásí vždy produktová chyba s přesným číslem. MCP chyby mají stejná pole ve structuredContent.error (včetně requestId) a text s prefixem podle příčiny. Vše je aditivní, statusy ani kódy se nemění.
• 6. 9. 2026 (1.2.0): Endpointy /v1/agents/{id}/draft* a /simulate ztratily obal ok a chybový prostý řetězec - chyby mají od teď stejný tvar {error:{code,message,requestId,docsUrl}} jako zbytek v1; revision v tělech požadavků se přejmenovala na expectedRevision; přibylo hasMore/nextBefore u stránkování, hlavičky X-Request-Id a RateLimit-*, POST /v1/webhook/test, GET /v1/webhook/deliveries a GET /openapi.json. Endpointy konceptu byly veřejné už od 5. 9. 2026, ale bez stabilního obalu - jsou proto ze záruky (pravidlo 1 sekce Verzování) do verze 1.2.0 vyjmuté.

Úplný a průběžně aktualizovaný seznam je na stránce Novinky (i jako RSS kanál).

Konvence

Zvyklosti, které platí napříč endpointy - ne jen u jednoho z nich.

Identifikátory

Každé ID nese prefix podle typu záznamu a je jinak neprůhledné (dál ho neparsuj):

vk_ API klíč, ag_ agent, ad_ koncept agenta, ado_ operace nad konceptem, c_ hovor, msg_ SMS zpráva, tl_ nástroj, whd_ doručení webhooku, rl_ relay lease, int_ připojení (integrace), inv_ daňový doklad (GET /v1/billing/documents), l_ položka historie kreditu, task_ úkol, item_ příjemce v úkolu, attempt_ pokus o vytočení položky úkolu, req_ ID požadavku (viz Formát chyby výš).

Časy

Časová razítka jsou skoro všude unixové milisekundy (createdAt, startedAt, boughtAt, issuedAt, taxableAt) - VÝJIMKA jsou pole napojeného kalendáře A dokladů: start, end, fetchedAt (kalendář) a parametry timeMin/timeMax jsou řetězce RFC 3339 (2026-09-08T10:00:00.000Z), nikdy číslo; GET /v1/integrations/{id}/invoices a .../invoices/{externalId} jsou taky řetězce - fetchedAt stejně RFC 3339, dueDate je čisté datum (2026-09-08) přímo od Fakturoidu/ABRA Flexi, nebo null, když ho poskytovatel nedal. Druhou výjimkou je měsíční paušál: periodStart a periodEnd (/v1/subscription, /v1/balance) jsou řetězce ISO 8601 v UTC, ne milisekundy.

Stránkování - tři schémata a výpisy bez

GET /v1/messages, GET /v1/calls a GET /v1/billing/documents berou limit + before (ms razítko, exkluzivní) a vrací hasMore/nextBefore - podrobně viz Stránkování výš. Události napojeného kalendáře (GET /v1/integrations/{id}/events) místo toho používají neprůhledný pageToken/nextPageToken - timeMin/timeMax/search musí mezi stránkami zůstat stejné, pageToken sám o sobě to nezajistí. GET /v1/credit/ledger bere jen limit (1-200, výchozí 50), žádný kurzor - vždy začíná od nejnovější položky. GET /v1/tasks bez ids vrací nejvýš 100 nejnovějších úkolů; s ids načte nejvýš pět zadaných úkolů na požadavek a nepředstírá úplný inventář účtu. GET /v1/webhook/deliveries taky nemá kurzor a vrací nejvýš posledních 50 doručení (úspěšná, neúspěšná i testovací). Hledání v napojených dokladech se taky tiše ořízne - prvních 40 řádků u Fakturoidu nebo 50 u ABRA Flexi, bez kurzoru na další; místo stránkování dotaz zúži. Všechno ostatní, co vrací seznam (agenti, čísla, SMS čísla, nástroje, API klíče, seznam nevolat, hlasy), vrací celou množinu najednou - není co stránkovat.

Neznámé a české parametry

Neznámý query parametr se skoro všude tiše ignoruje (ať starší klient nespadne na jeden navíc poslaný parametr) - výjimkou jsou endpointy napojeného kalendáře a napojených dokladů (/v1/integrations/{id}/...), které neznámý parametr odmítnou chybou 400 validation, protože ho posílají dál poskytovateli a tiše zahozený filtr by tam vypadal jako chybějící data, ne jako chyba; a z jiného důvodu i GET /v1/credit/ledger a GET /v1/billing/documents, jejichž query schéma je schválně striktní, ať překlep v limit/before spadne hlasitě místo tichého ignorování.

Pár polí schválně nese české jméno: tok adresy k číslu (GET /v1/numbers/address-options, pak POST /v1/numbers/orders - prosté POST /v1/numbers bere jen e164/region a adresu ignoruje) posílá psc, obec, cobce, ulice (jen tam, kde adresa ulici má) a cp - přesně jak je pojmenuje číselník RÚIAN (vlastní adresní registr operátora), odkud se číslo objednává, ať se hodnota mezi nimi nikdy tiše nepřeloží špatně. GET /v1/calls/{id}/recording?stahnout=1 je jediný český parametr mimo tenhle tok (stáhnout jako přílohu místo zobrazení v prohlížeči). Všechno ostatní - identifikátory, pole i parametry - je anglicky.

Kvóty na jednom místě

Každá kvóta je zmíněná i u svého endpointu výš - tady je jen souhrn:

• 60 požadavků/min na API klíč (REST a MCP si limit dělí, viz Rate limits výš)
• SMS: 1 za 2 s a 100/den na účet, až po prvním dobití kreditu
• SMS odesílané ze SMS čísla (fromNumber): navíc 20 zpráv za den na účet v prvních 30 dnech od koupě čísla, potom 50; nejvýš dvě SMS čísla na účet
• Odchozí hovory (agent, most, zkušební): 10/min a 1000/den na účet, nejvýš 2 souběžné hovory přes vestavěného agenta
• Prozvonění (POST /v1/rings): 30/min a 500/den na účet a 120/hod na jedno číslo, nezávisle na limitech hovorů
• Hlasové zprávy (POST /v1/voice-messages): nejvýš 200 za 24 hodin na účet, k tomu běžné limity hovorů
• Zkušební hovor bez vlastního čísla (POST /v1/calls se systemPrompt místo agentId/from): navíc 3/24 h na účet A sdílený strop 30/hod napříč VŠEMI účty dohromady - do sdíleného stropu narazíš i bez vlastního zavinění.
• POST /v1/agents/{id}/test-call: 3/den na účet
• POST /v1/tools/test a .../{id}/test: 10/min na účet
• POST /v1/agents/{id}/simulate: 20/hod na účet
• POST /v1/webhook/test: 10/hod na účet
• GET /v1/changelog: 30/min na IP adresu (bez API klíče)
• Úkoly: běžící úkol vytočí nejvýš JEDNOHO příjemce za jeden běh cronu. Obecná fronta běží */2 * * * * a obslouží nejvýš 20 úkolů napříč účty; registrované úlohy PetCenter mají oddělený minutový cron * * * * * i frontu, se stejnými limity souběhu a rychlosti volání. Obě fronty při více než 20 čekajících úkolech pořadí spravedlivě otáčejí.

Opakování webhooku

Neúspěšné doručení dostane až 3 pokusy po 3 sekundách v rámci téhož odeslání. U hovorových událostí (call.completed, call.failed, call.no_answer, call.missed) a u message.received tím doručování nekončí: událost zůstává ve frontě a doručení se v následujících minutách ještě zopakuje, nejvýš do 5 kol - dedupuj podle event_id v těle, kdyby ti výjimečně dorazila víckrát. message.sent a testovací webhook.test frontu nemají: po neúspěchu se jen zaloguje a znovu se neposílá. Průběh (včetně mezistavů před posledním kolem, attempts je součet pokusů napříč VŠEMI koly) uvidíš v GET /v1/webhook/deliveries (nebo list_webhook_deliveries).

Zastarávání

v1 zatím jen přibývá (viz Verzování výš) - jedinou výjimkou byla verze 1.5.1, která u PŘÍCHOZÍCH hovorů přestala vracet answeredBy (pole u nich nikdy nemělo smysluplnou hodnotu, u odchozích hovorů se nemění). Skutečné zrušení pole v v1 volai zatím neudělalo. Až k tomu dojde, pole dostane deprecated: true v GET /openapi.json a odpověď ponese hlavičky Deprecation/Sunset aspoň 90 dní předem, MCP odpověď, která se pole dotkne, navíc dostane položku ve warnings (stejné pole, jaké dnes nese upozornění na chybějící informaci o AI podle Aktu o umělé inteligenci) - samo odebrání přijde vždy jen jako nová hlavní verze (v2), nikdy tiše uvnitř v1.

Hovory vs. konverzace - viz stejnojmenný odstavec v sekci Hovory níž, než budeš sčítat počty.

Přihlašovací údaje (heslo, token, aplikační heslo) pošli jen tehdy, když ho uživatel už má někde, odkud ho umíš přečíst (proměnná prostředí nebo soubor, který sám pojmenoval) - nikdy si o něj neříkej v konverzaci a nikdy ho neopakuj zpátky; platí dnes pro Apple Kalendář a ABRA Flexi (viz sekce o kalendáři a dokladech níž).

Co přes API nejde

Telefonii ovládáš přes API a MCP celou - čísla, hovory, SMS, agenty, webhooky, relay i seznam nevolat. Profil účtu, fakturační adresa a firemní údaje jdou přes API taky (sekce Účet výš). Pár věcí ale zůstává jen v portálu, záměrně:

Opačným směrem toho v MCP schválně chybí víc: uvolnění zakoupeného čísla (DELETE /v1/numbers/{e164}), SMS čísla (DELETE /v1/sms-numbers/{e164}) a čísla pro hovory i SMS (DELETE /v1/voice-sms-numbers/{e164}) je v REST API i v portálu, ale ne mezi MCP nástroji - nevratná akce, na kterou je jedna špatně pochopená věta málo. Stejně schválně chybí i výdej nahrávky (binární tělo, GET /v1/calls/{id}/recording), detail jedné zprávy nebo jednoho nástroje (výpisy list_messages/list_tools nesou stejná pole, jen ne pro jediné ID) a samostatný nástroj pro zkušební hovor - make_call s agentId vytočí stejný hovor jako POST /v1/agents/{id}/test-call, jen bez jeho přísnějšího denního limitu 3 hovorů.

Účet

Profil, tísňová adresa, fakturační údaje a přehled API klíčů. Tvorba nových API klíčů (POST /v1/api-keys) se nevystavuje - klíč, který razí klíče, by mohl ze ztráty jednoho udělat trvalý přístup. Nový klíč vytvoříš v portálu (sekce Přístupy a API). E-mailová upozornění (callSummary, lowCredit, reactivation, productUpdates) jdou přes tohle rozhraní jen ČÍST - zápis je výhradně v portálu, protože lowCredit je jediná brzda mezi docházejícím kreditem a tichým vyčerpáním.

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

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "revoked": true
}

Kredit

balanceHal i všechny sazby v tomhle API jsou bez DPH - volai je plátce DPH, ale DPH se řeší až při dobíjení kreditu kartou v portálu (přehled na stránce /cenik), API samotné s ní nepočítá. Podrobný průvodce s příklady toku je na /docs/kredit.

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

{
  "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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "removed": true
}

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

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -o invoice.pdf

Měsíční paušál

Měsíční paušál jednou za měsíc strhne uloženou kartu a připíše měsíční kredit, který se utrácí dřív než dobitý kredit a na konci období propadá. Každý stupeň má cenu a větší měsíční kredit, obojí bez DPH (viz tiers v GET /v1/subscription). Peníze se hýbou jen s člověkem u karty: tohle API samo nikdy nezačne ani nezvýší opakované strhávání. Zapnutí paušálu, ruční zaplacení neprošlé obnovy a výměna karty vrací odkaz na Stripe Checkout; zvýšení stupně, obnovení zrušeného paušálu a přepnutí na dokupování z karty vrací confirmUrl, který musí v portálu potvrdit člověk. Podrobný průvodce je na /docs/kredit.

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

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -H "Idempotency-Key: plan-card-2026-11-18-01"

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

Úkoly

Úkol vytočí seznam příjemců jedním agentem podle předem nastavených pravidel (rozpočet, volací okno, počet pokusů) - nic se nevytáčí, dokud ho sám nespustíš (POST .../start). Kompletní průvodce s CSV importem, stavy a globální propustností je na /docs/ukoly. Agent s číslem pro hovory i SMS volá v kampani jen na česká čísla (+420) a z čísla běží naráz jeden hovor: kontakt s jiným číslem jde ke kontrole a úkol volá další, zabrané číslo úkol krátce počká.

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

{
  "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_TVUJ_KLIC"

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

curl https://volai.cz/v1/outbound/dispatch-scopes/petcenter/registrations \
  -H "Authorization: Bearer vk_TVUJ_KLIC" -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "deleted": true
}

curl -X POST https://volai.cz/v1/tasks/csv-preview \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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 }]
}

Čísla

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

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

curl -X PUT "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"offerId": "brno"}'

{
  "joined": true
}

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

{
  "left": true
}

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

{
  "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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  --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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

{
  "released": true
}

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC"

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

Zprávy

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

{
  "messages": [
    {
      "id": "msg_5b7e0d93",
      "to": "+420777123456",
      "from": "+420770112233",
      "body": "Potvrzeno, vidíme se v pátek v 10:00. - Moje Appka",
      "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": "Díky, přijdu v pátek v 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": "Ahoj z volai! - Moje Appka",
      "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_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_MESSAGES_ID" \
  -d '{"to":"+420777123456","body":"Ahoj z volai! - Moje Appka"}'

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

status zprávy: pending (uložená, ještě se odesílá), sent (operátor přijal zprávu k odeslání, případně do fronty; nejde o potvrzení doručení příjemci), failed (operátor odmítl, u zprávy ze SMS čísla případně až dodatečně - neúčtuje se, už stržený kredit se vrátí, priceHal 0), received (zpráva přijatá na tvém SMS čísle nebo čísle pro hovory i SMS, vždy s direction: "in" a priceHal 0) a unknown (potvrzení o odeslání nedorazilo, typicky timeout na straně operátora) - přesto se účtuje plnou cenou, protože zpráva mohla dojít. U zprávy odeslané ze SMS čísla se unknown může později sám změnit: na sent s deliveryStatus, když operátor zprávu potvrdí, nebo na failed s vrácením kreditu, když ji odmítne. Dostaneš-li unknown, zprávu prosím neposílej znovu naslepo - ozvi se podpoře, případný duplicitní kredit vrátíme.

U status: "failed" navíc dostaneš failReason: unsupported_characters (emoji nebo znak, který síť nedoručí), unsupported_recipient (síť číslo nepřijímá), forbidden_sender a low_balance (chyba na naší straně), gateway_failed (brána operátora), network_rejected (jiné odmítnutí), opted_out (příjemce poslal na tvoje SMS číslo STOP). U ostatních stavů je null.

deliveryStatus (delivered nebo undelivered) je doručenka operátora a vzniká jen u zpráv odeslaných z tvého SMS čísla. U zpráv přes sdílené jméno SMSinfo, které doručenky nemá, u zpráv odeslaných z čísla pro hovory i SMS, které je také nemá, a u přijatých zpráv je null. Stav sent zůstává potvrzením přijetí operátorem a doručení nedokládá. Zpráva s undelivered se účtuje, protože ji operátor přijal. Když operátor dodatečně ohlásí selhání, změní se status zprávy na failed, priceHal klesne na 0 a kredit za ni se vrátí. Doručenka přijde, jakmile ji operátor ohlásí; když oznámení o stavu nedorazí, doplní ji pravidelná kontrola každých 15 minut. Když ji operátor neohlásí vůbec, zůstane null.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "fromNumber": "+420770112233", "body": "Potvrzeno, vidíme se v pátek v 10:00. - Moje Appka"}'

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

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

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

SMS čísla

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

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

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

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

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

{
  "released": true
}

Čísla pro hovory i SMS

Číslo pro hovory i SMS je třetí druh čísla vedle hlasových čísel a SMS čísel: pražské pevné číslo (+420 2xx), na které přijímáš hovory i SMS a ze kterého agent volá i odesílá SMS. Hlasové číslo SMS nepřijímá a SMS číslo nemá hovory. Číslo je registrované u operátora na provozovatele a ty ho užíváš; po objednávce je aktivní obvykle do 1 pracovního dne, nejdéle za 48 hodin, a poplatek se strhne až po aktivaci. Příchozí hovory zvedá agent, který běží na vlastním hlasovém motoru volai, a číslo zvládne nejvýš dva souběžné hovory. Příjem SMS jsme ověřili na síti O2, ověřovací kódy od služeb nezaručujeme. S country v těle objednávky dostaneš místo pražského čísla číslo v jiné zemi: pevné číslo v jiné zemi, na které přijímáš hovory (zvedá je agent), ale bez SMS (nepřijímá je ani neposílá), a které volá ven jen do země čísla a do ČR. Cena a pravidla jsou stejné jako u pražského čísla; číslo se registruje u operátora na provozovatele s adresou v dané zemi a je aktivní obvykle do 1 pracovního dne, nejdéle za 3 pracovní dny (u zemí bez registrace do hodiny). Země, ve kterých jde číslo objednat, se mění, proto je čti z GET /v1/voice-sms-numbers/countries (MCP list_voice_sms_countries) a žádnou nevyjmenovávej z paměti. Objednáš ho sám v portálu, přes REST (POST /v1/voice-sms-numbers) i MCP (order_voice_sms_number), a to po prvním dobití kreditu. Když objednávky dočasně stojí, vrátí objednávka voice_sms_numbers_unavailable a nic se neúčtuje; zkus to později, nebo napiš na podpora@volai.cz.

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

{
  "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_TVUJ_KLIC"

{
  "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": 4900
    }
  ]
}

curl -X POST "https://volai.cz/v1/voice-sms-numbers" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "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_TVUJ_KLIC" \
  -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_TVUJ_KLIC"

{
  "cancelled": true
}

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

{
  "released": true
}

Hovory

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

{
  "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": {
        "jmeno": "Jana Nováková",
        "pocet_kav": 2,
        "spechalo": "bezna"
      }
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/calls" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -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_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+420777123456",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí a mluvíš stručně a přátelsky.",
    "firstMessage": "Dobrý den, tady zkušební agent volai, jak vám mohu pomoct?"
  }'

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

curl -X POST "https://volai.cz/v1/voice-messages" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_VOICE_MESSAGES_ID" \
  -d '{"to":"+420777123456","text":"Upozornění: server api-1 neodpovídá už pět minut. Prosím ověřte jeho stav.","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_TVUJ_KLIC" \
  -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"
  }
}

curl 'https://volai.cz/v1/calls/active?agentId=ag_example' -H 'Authorization: Bearer vk_TVUJ_KLIC'

{
  "data": {
    "agentId": "ag_example",
    "complete": true,
    "checkedAt": "2026-10-09T17:59:00.000Z",
    "enginesChecked": 2,
    "outboundCount": 0,
    "inboundCount": 0,
    "unresolvedOutboundCount": 0,
    "outbound": []
  }
}