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

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/relay, POST /v1/numbers, POST /v1/numbers/orders, POST /v1/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 a POST /v1/credit/auto-topup/setup 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.

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.34.2 (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

• 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.

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 taky nemá kurzor a vrací nejvýš 100 nejnovějších úkolů. 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, 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
• 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 (*/2 * * * *) a jeden běh se dotkne nejvýš 20 úkolů napříč VŠEMI účty - i s kreditem a otevřeným oknem volání jsou tak volání z jednoho úkolu od sebe zhruba dvě minuty, a při vytížení (přes 20 běžících úkolů) se úkoly střídají spravedlivě, ne jeden po druhém do konce.

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}) 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 }
  }
}

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

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/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

Ú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.

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",
      "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 -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",
    "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",
    "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",
    "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",
    "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",
    "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",
    "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 -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",
    "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",
    "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",
    "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_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
    },
    {
      "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
    }
  ],
  "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é SMS číslo, 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. 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á, 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í.

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
    }
  ]
}

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

{
  "smsNumber": {
    "number": "+420770112233",
    "status": "active",
    "createdAt": 1756111640000,
    "monthlyFeeHal": 39000,
    "nextChargeAt": 1758703640000
  }
}

curl -X DELETE "https://volai.cz/v1/sms-numbers/+420770112233" \
  -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 '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": []
  }
}

curl -X POST https://volai.cz/v1/calls/c_example/hangup -H 'Authorization: Bearer vk_TVUJ_KLIC' -H 'Content-Type: application/json' -d '{"expectedAgentId":"ag_example","expectedTaskId":"task_example","expectedItemId":"item_example","expectedPhoneSha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'

{
  "data": {
    "callId": "c_example",
    "outcome": "hung_up",
    "endConfirmed": true
  }
}

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

{
  "call": {
    "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"
    },
    "transcript": [
      { "role": "agent", "message": "Dobrý den, tady recepce kavárny Nula, jak vám mohu pomoct?", "timeInCallSecs": 0 },
      { "role": "caller", "message": "Chtěl bych si objednat dva latte s sebou.", "timeInCallSecs": 4 },
      { "role": "agent", "message": "Jasně, dva latte na vyzvednutí, bude to za patnáct minut.", "timeInCallSecs": 9 }
    ],
    "summary": "Zákazník si objednal dva latte s sebou, vyzvednutí za 15 minut."
  }
}

curl -X GET "https://volai.cz/v1/calls/c_9d4e2b7f?waitSecs=30" \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "call": {
    "id": "c_9d4e2b7f",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "completed",
    "startedAt": 1756111400000,
    "durationSecs": 47,
    "priceHal": 269,
    "agentId": "ag_kx91fa2b",
    "note": null,
    "flag": null,
    "handledAt": null,
    "rating": null,
    "goal": null,
    "hasConversation": true,
    "source": "api",
    "kind": "agent",
    "endReason": "completed",
    "hasRecording": true,
    "answeredBy": "human"
  }
}

{
  "call": {
    "id": "c_9d4e2b7f",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "ringing",
    "startedAt": 1756111400000,
    "agentId": "ag_kx91fa2b",
    "note": null,
    "flag": null,
    "handledAt": null,
    "rating": null,
    "goal": null,
    "hasConversation": null,
    "source": "api"
  },
  "stillRunning": true
}

curl https://volai.cz/v1/calls/c_8f2ac1d4/recording \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -OJ

curl -X PATCH https://volai.cz/v1/calls/c_8f2ac1d4 \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"note": "Volal kvůli reklamaci, přeposlat na podporu.", "flag": {"reason": "Agent nerozuměl dotazu na fakturu."}}'

{
  "call": {
    "id": "c_8f2ac1d4",
    "direction": "in",
    "from": "+420777123456",
    "to": "+420601234567",
    "status": "completed",
    "startedAt": 1756111400000,
    "durationSecs": 47,
    "priceHal": 236,
    "agentId": "ag_kx91fa2b",
    "source": "inbound",
    "kind": "inbound",
    "endReason": "completed",
    "hasRecording": true,
    "data": { "jmeno": "Jana Nováková" },
    "note": "Volal kvůli reklamaci, přeposlat na podporu.",
    "flag": { "reason": "Agent nerozuměl dotazu na fakturu.", "flaggedAt": 1756111460000 },
    "handledAt": null,
    "rating": null,
    "goal": { "result": "failure", "rationale": "Zákazník si objednal dva latte s sebou, vyzvednutí za 15 minut.", "reason": null },
    "hasConversation": true
  }
}

Stav hovoru: pole status

status je jediné pole, které se u hovoru mění v čase. Prvních pět minut po zahájení se ještě může posunout, pak už je konečné - čtyři z těch stavů jsou koncové.

Druh hovoru: pole kind

kind říká, kudy hovor vznikl - a tím i jak se účtuje. Je to jediné pole, podle kterého ve faktuře odlišíš hovor vlastního (BYO) agenta od hovoru zabudovaného, protože u relaye se neplatí agentní přirážka.

Proč hovor skončil: pole endReason

endReason doplňujeme u všech uzavřených hovorů. Pozor: hovor zablokovaný kvůli dluhu nebo ručnímu pozastavení provozovatelem má status completed, ale endReason je credit_blocked, resp. suspended, a cena 0 - podle samotného status ho od proběhlého hovoru nepoznáš. Totéž platí pro hovor, na jehož druhém konci byl automat opakující pořád tutéž hlášku (caller_loop): má status completed, ale pokud trval nejvýš pět minut, je jeho cena 0. Tři varianty „nevyzvednuto“ jsou schválně rozlišené, ne jeden společný stav.

Agenti

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

{
  "agents": [
    {
      "id": "ag_pw7q2vnd",
      "name": "Recepční",
      "language": "cs",
      "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
      "firstMessage": "Dobrý den, tady recepce kavárny Nula, jak vám mohu pomoct?",
      "voiceId": "7JbZPqJGWUfXXBim0T8U",
      "provider": "elevenlabs",
      "createdAt": 1756111000000,
      "status": "active",
      "toolIds": ["tl_5c2a91f4"],
      "dataFields": [
        {
          "key": "jmeno",
          "type": "string",
          "description": "Jméno volajícího, které sám řekl."
        }
      ],
      "recordCalls": true,
      "goal": null,
      "knowledge": null,
      "notifyEmail": true,
      "silencePromptSecs": 10,
      "laughter": "auto",
      "missedCallSms": { "enabled": false },
      "suspended": false
    },
    {
      "id": "ag_kx91fa2b",
      "name": "Recepční",
      "language": "cs",
      "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
      "firstMessage": "Dobrý den, tady recepce kavárny Nula, jak vám mohu pomoct?",
      "voiceId": "milena",
      "provider": "engine",
      "numberE164": "+420601234567",
      "createdAt": 1756111000000,
      "status": "active",
      "toolIds": ["tl_5c2a91f4"],
      "transferTo": "+420777123456",
      "transferCondition": "Volající výslovně žádá spojení s člověkem.",
      "dataFields": [
        {
          "key": "jmeno",
          "type": "string",
          "description": "Jméno volajícího, které sám řekl."
        },
        {
          "key": "spechalo",
          "type": "string",
          "description": "Jak moc věc spěchala.",
          "enumValues": ["nizka","bezna","vysoka"]
        }
      ],
      "recordCalls": true,
      "goal": null,
      "knowledge": null,
      "notifyEmail": true,
      "silencePromptSecs": 10,
      "laughter": "auto",
      "missedCallSms": { "enabled": false },
      "suspended": false
    }
  ]
}

curl -X POST "https://volai.cz/v1/agents" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_AGENTS_ID" \
  -d '{"name":"Recepční","systemPrompt":"Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí a odpovídáš na otázky o otevírací době. Nikdy nevymýšlej ceny, které neznáš. Hovor ukonči shrnutím objednávky.","firstMessage":"Dobrý den, tady recepce kavárny Nula, jak vám mohu pomoct?","language":"cs","numberE164":"+420601234567","toolIds":["tl_5c2a91f4"],"transferTo":"+420777123456","transferCondition":"Volající chce mluvit s obsluhou, nebo řeší reklamaci.","dataFields":[{"key":"jmeno","type":"string","description":"Jméno volajícího, které sám řekl."},{"key":"pocet_kav","type":"number","description":"Kolik káv si volající objednal."}],"recordCalls":true}'

{
  "id": "ag_kx91fa2b"
}

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

{
  "agent": {
    "id": "ag_kx91fa2b",
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, tady recepce kavárny Nula, jak vám mohu pomoct?",
    "voiceId": "milena",
    "provider": "engine",
    "numberE164": "+420601234567",
    "createdAt": 1756111000000,
    "status": "active",
    "toolIds": ["tl_5c2a91f4"],
    "transferTo": "+420777123456",
    "transferCondition": "Volající výslovně žádá spojení s člověkem.",
    "dataFields": [
      {
        "key": "jmeno",
        "type": "string",
        "description": "Jméno volajícího, které sám řekl."
      },
      {
        "key": "spechalo",
        "type": "string",
        "description": "Jak moc věc spěchala.",
        "enumValues": ["nizka","bezna","vysoka"]
      }
    ],
    "recordCalls": true,
    "goal": null,
    "knowledge": null,
    "notifyEmail": true,
    "silencePromptSecs": 10,
    "laughter": "auto",
    "missedCallSms": { "enabled": false },
    "suspended": false,
    "laughterEffective": {
      "active": true,
      "reason": "ok",
      "sensitiveCategory": null
    }
  }
}

curl https://volai.cz/v1/agents/ag_example/call-hold -H 'Authorization: Bearer vk_TVUJ_KLIC'

{
  "agentId": "ag_example",
  "held": false,
  "hold": null
}

curl https://volai.cz/v1/agents/ag_example/call-hold -X POST -H 'Authorization: Bearer vk_TVUJ_KLIC' -H 'Content-Type: application/json' -d '{"reason":"budget_limit","operationId":"budget-stop-001"}'

{
  "agentId": "ag_example",
  "held": true,
  "hold": {
    "agentId": "ag_example",
    "reason": "budget_limit",
    "operationId": "budget-stop-001",
    "fingerprint": "14e5bfb3f57897b30d172ef4ba861b2a27e7beb1de278a94b47bc0f14c614f4c",
    "createdAt": "2026-10-08T12:00:00.000Z"
  }
}

curl -X PATCH https://volai.cz/v1/agents/ag_kx91fa2b \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"firstMessage": "Dobrý den, kavárna Nula, co si dáte?"}'

{
  "agent": {
    "id": "ag_kx91fa2b",
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, kavárna Nula, co si dáte?",
    "voiceId": "milena",
    "provider": "engine",
    "numberE164": "+420601234567",
    "createdAt": 1756111000000,
    "status": "active",
    "toolIds": ["tl_5c2a91f4"],
    "transferTo": "+420777123456",
    "transferCondition": "Volající výslovně žádá spojení s člověkem.",
    "recordCalls": true,
    "goal": null,
    "knowledge": null,
    "notifyEmail": true,
    "silencePromptSecs": 10,
    "laughter": "auto",
    "missedCallSms": { "enabled": false },
    "suspended": false
  }
}

curl -X DELETE https://volai.cz/v1/agents/ag_kx91fa2b \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "deleted": true
}

Odpovědi POST /v1/agents, PATCH /v1/agents/{id}, POST /v1/agents/{id}/draft/publish a POST /v1/agents/{id}/draft/rollback mohou nést nepovinné pole warnings. Několik kódů se týká první věty: first_message_no_ai_disclosure, když uložená první věta agenta nesděluje, že mluví digitální asistent (evropský AI Act, čl. 50), a first_message_too_long, když je odhadovaná mluvená doba TOHO, CO VOLAJÍCÍ SKUTEČNĚ SLYŠÍ (první věta plus věta o nahrávání, když je recordCalls zapnuté), nad 7 sekundami (asi 2,53 slova za sekundu; číslice vždy a velké zkratky do čtyř znaků se počítají po znacích). Nezměněná výchozí šablona první věty tenhle kód nikdy nespustí, jen text, který zákazník upravil. Kdo agentku přeruší, udělá to nejčastěji do jedné sekundy slyšitelné řeči. Agent s fázemi (pole workflow, viz sekce Fáze hovoru (workflow) níž) přidává do stejného pole dalších deset kódů - dead_end, empty_node, entry_phrase_never_spoken, missing_enter_phrase, short_condition, condition_about_agent, base_prompt_long, workflow_not_synced_to_provider, workflow_node_tool_not_synced a workflow_node_tool_missing (uzel odkazuje nástroj, který na účtu už není - smazaný; fázi je potřeba uložit bez něj) - a typicky je nese i tehdy, když první věta v pořádku je (šablona Recepce jich vrací tři). Varování, které patří konkrétní fázi nebo přechodu, nese navíc nodeId, nebo edgeId. Žádný z kódů uložení nezastaví - jen na ně upozorní. Pole v odpovědi chybí, jen když není co hlásit. Vrácení konceptu na dřívější revizi (draft/rollback) vrací warnings stejně jako publikace, protože taky propisuje první větu na živého agenta. Jen publikace a rollback (ne POST/PATCH /v1/agents) navíc můžou ve stejném poli vrátit number_changed_by_publish s hodnotami from/to (E.164, nebo null bez čísla), když republikace doopravdy změní telefonní číslo živého agenta - ani ten publikaci neblokuje. Samostatný kód calendar_pending_engine_switch se objeví, když má agent nastavený calendar (termíny podle kalendáře), ale běží na ElevenLabs - nastavení se uloží a začne fungovat, jakmile agent přejde na vlastní motor volai; zapnutí kalendáře ten přechod samo spouští. Agent s připojeným číslem (numberE164), jehož zadání (systemPrompt nebo firstMessage) používá {{promennou}} mimo sadu, kterou příchozí hovor doopravdy dodává (caller_number, called_number, attempt_id, volai_blocked, volai_block_reason, trial_prompt, trial_first_message a sedm system__* proměnných), dostane prompt_variables_unavailable_inbound - na příchozím hovoru se taková proměnná dosadí jako prázdný text. Když po odstranění všech {{...}} bloků z neprázdné první věty v ní nezůstane žádné písmeno ani číslice mimo proměnné, dostane first_message_empty. Samostatný kód agent_misuse_suspected se objeví, když konfigurace agenta (u odpovědí výš) obsahuje formulace, které mohou působit jako vydávání se za úřad či jinou instituci, nebo jako žádost o citlivé údaje - viz Podmínky volai § 10. Týž kód ve stejném tvaru vracejí v nepovinném poli warnings i PUT /v1/agents/{id}/draft a POST /v1/agents/{id}/simulate (koncept), POST /v1/calls (prompt zkušebního hovoru nebo variables), POST /v1/tasks a PATCH /v1/tasks/{id} (název úkolu a proměnné příjemců) a POST /v1/tools a PATCH /v1/tools/{id} (popis nástroje a jeho parametrů). Uložení ani odeslání neblokuje, jde jen o upozornění. Jen POST /v1/agents navíc vrací elevenlabs_by_explicit_choice, když požadavek poslal useForOutboundTasks: false u jazyka, kterému by nasazení jinak dalo vlastní motor volai (dnes cs a sk), a agent proto zůstal na ElevenLabs - bez hlasů motoru a bez funkcí, které běží jen na motoru. Agent se založí, varování jen upozorní; kdo chtěl agenta jen na příchozí hovory, má pole vynechat.

{
  "id": "ag_kx91fa2b",
  "warnings": [
    {
      "code": "first_message_no_ai_disclosure",
      "message": {
        "cs": "Podle evropského AI Act (čl. 50) musí první věta prozradit, že mluví digitální asistentka. Stačí: „Dobrý den, tady digitální asistentka firmy Novák.“ Bez toho za sdělení odpovídáš ty.",
        "en": "Under the EU AI Act (Article 50), the first line must reveal that a digital assistant is speaking. For example: \"Hello, this is the digital assistant for Novak Inc.\" Without it, you are responsible for the disclosure."
      }
    }
  ]
}

Nová pole agenta

POST /v1/agents i PATCH /v1/agents/{id} berou kromě jména, promptu, hlasu a čísla i tahle pole. Všechna jsou nepovinná při vytváření. toolIds, transferTo, transferCondition, dataFields a recordCalls u staršího agenta v odpovědi chybí, dokud je nikdo nenastaví. goal a knowledge se naopak vrací VŽDY - nenastavené jako null, ne jako chybějící klíč - a notifyEmail je vždycky boolean (chybí-li, znamená to zapnuto). Odpověď navíc vždy nese provider (engine nebo elevenlabs) - říká, na kterém poskytovateli agent doopravdy běží, obě hodnoty se v provozu vyskytují. Stejně tak vždy nese suspended (boolean) - true, když agenta ručně pozastavil provozovatel volai; takový agent nepřijímá ani neuskutečňuje hovory (agent_suspended) a pole přes API ani MCP nastavit nejde. useForOutboundTasks je výjimka - bere ho JEN POST /v1/agents, v PATCH není (existujícího agenta mezi poskytovateli přepíná volai, ne zákazník; sám to udělá po zapnutí transferTo nebo calendar a po změně language na jazyk, ve kterém noví agenti vznikají na motoru - viz detail agenta výš). voicemail je dostupné jen u agenta s provider: "engine" - u ostatních POST/PATCH s tímhle polem odmítne. silencePromptSecs (připomínka v tichu) se naopak přijímá a vrací u OBOU poskytovatelů - u agenta na ElevenLabs se hodnota jen uloží, zazní až po přepnutí na vlastní motor volai. workflow (fáze hovoru) je dostupné u obou poskytovatelů, ale ne stejně úplně - viz sekci Fáze hovoru (workflow) níž. laughter (smích agentky) je taky vždy přítomné, stejně jako goal/knowledge/notifyEmail výš - u staršího agenta bez nastavené hodnoty je to auto, nikdy chybějící klíč; přijímá se a ukládá u OBOU poskytovatelů, slyšet je ale jen u agenta na motoru s českým hlasem Cartesia.

Fáze hovoru (workflow)

Volitelné pole workflow rozdělí hovor do fází (nodes). Uzel je ROZSAH, ne scénář: jen doplní prompt, znalosti a nástroje platné, dokud je hovor v něm, a volitelně větu, kterou agent řekne hned při vstupu. Přechod mezi uzly rozhoduje model sám tím, že zavolá nástroj - nikdy to nepředepisuješ jako pevný skript. Základní systemPrompt agenta by měl nést jen to, co platí VE VŠECH fázích (identitu, tón, jak se předává vzkaz); instrukce jedné fáze patří do jejího uzlu, jinak nemá účinek. Do základního promptu patří i dvě věty, bez kterých agent nejčastěji odpoví, co neví: „Provozní údaje, které nemáš v zadání (otevírací doba, lhůty, ceny, dostupnost lidí), neříkej a neodhaduj - řekni, že to upřesní kolega.“ a „Ptej se vždy jen na jednu věc najednou.“

entry je id uzlu, ve kterém hovor začíná. edges jsou přechody: condition (5 až 200 znaků) popisuje, KDY přejít, a musí mluvit o tom, co řekl VOLAJÍCÍ (nikdy o tom, co udělal agent nebo nástroj) - jde doslova do popisu nástroje, kterým model přechod provede. Limity: 2 až 8 uzlů, 1 až 24 hran, nejvýš 5 hran z jednoho uzlu, mezi dvěma uzly smí vést jen jedna hrana (v libovolném směru, duplicate_pair); uzlův prompt má nejvýš 2 000 znaků, knowledge nejvýš 4 000, prompt a knowledge dohromady nejvýš 4 000 na uzel, a toolIds nejvýš 10 nástrojů na uzel.

enterPhrase je věta vyslovená jednou při vstupu do uzlu (nejvýš 160 znaků). enterBehavior: "wait" řekne modelu, ať po ní v tomtéž tahu nic dalšího neříká a počká na volajícího - typicky u citlivé fáze jako oznámení úmrtí; vyžaduje vyplněné enterPhrase, jinak wait_without_phrase. Uzel bez vlastního enterPhrase dostane při vstupu výchozí krátkou větu (např. česky „Rozumím.“) jen na vlastním motoru volai (provider: "engine"); u agenta na ElevenLabs se při vstupu neozve nic - vlastní věta zní přirozeněji a je jediná, která zazní u obou, a proto ji editor dál doporučuje varováním missing_enter_phrase.

Uzel typu konec neexistuje - fáze samy o sobě hovor nikdy neukončí. Hovor pořád končí jen vestavěným ukončením, stejně jako dosud.

enterBehavior: "wait" se přenáší i k agentům na ElevenLabs, ne jen na vlastní hlasový motor volai (provider: "engine"); věta při vstupu na motoru zazní doslovně, u ElevenLabs jde do promptu fáze jako instrukce, ať ji řekne - model ji zpravidla řekne podobně, ale ne nutně stejnými slovy. Uzel BEZ vlastního enterPhrase u ElevenLabs neřekne při vstupu nic: výchozí krátkou větu (např. česky „Rozumím.“) doplňuje jedině vlastní motor volai. Dva rozdíly jsou větší. Nástroj přiřazený JEN uzlu (node.toolIds) se k agentovi na ElevenLabs zatím nepřenáší - fáze tam poběží bez něj, a odpověď na to upozorní kódem workflow_node_tool_not_synced; když ho tam chceš mít, přidej ho i mezi nástroje agenta (pole toolIds, v portálu záložka Pokročilé). Na vlastním motoru volai se uzlový nástroj přenáší beze změny. A workflowPath u hovoru zapisuje výhradně post-call vlastního motoru, takže hovor agenta na ElevenLabs ho nikdy nenese, i když fázemi prošel.

Neplatný graf (nedosažitelný uzel, chybějící vstupní uzel, rezervované jméno nástroje...) vrátí invalid_workflow a nic se neuloží; konkrétní důvod je vždy v message.

Příklad - recepce pohřební služby

{
  "workflow": {
    "version": 1,
    "entry": "triaz",
    "nodes": [
      {
        "id": "triaz",
        "label": "Triáž",
        "prompt": "Zjisti, proč volající volá, jednou otázkou. Pomáháš volajícím s ohlášením úmrtí, s výkopem hrobu nebo uložením urny a s poptávkou práce na pomníku."
      },
      {
        "id": "umrti",
        "label": "Úmrtí",
        "prompt": "Zjisti jméno zesnulého, kde se úmrtí stalo, jestli je tělo v nemocnici nebo doma, kontakt a čas, kdy se ozvat. Slib, že pracovník pohřební služby zavolá do 15 minut. Otázky na pomník nebo jeho cenu tady neřeš - řekni jen, že to s pozůstalými probere kolega, nic nevysvětluj a vrať se k úmrtí. Pomník sám nezmiňuj.",
        "enterPhrase": "Upřímnou soustrast.",
        "enterBehavior": "wait"
      },
      {
        "id": "vykop",
        "label": "Výkop a uložení",
        "prompt": "Volající řeší výkop hrobu, uložení urny nebo otevření hrobky. Zjisti termín, hřbitov a číslo hrobu, kontakt a jestli je potřeba domluvit s duchovním."
      },
      {
        "id": "poptavka",
        "label": "Poptávka práce",
        "prompt": "Volající poptává novou práci na pomníku - nápis, opravu nebo rekonstrukci hrobu. Zjisti hřbitov, číslo hrobu, rozsah práce a kontakt na zpětné volání s cenou."
      }
    ],
    "edges": [
      {
        "id": "triaz_umrti",
        "from": "triaz",
        "to": "umrti",
        "condition": "Volající oznamuje úmrtí blízké osoby nebo potřebuje pohřební službu."
      },
      {
        "id": "triaz_vykop",
        "from": "triaz",
        "to": "vykop",
        "condition": "Volající potřebuje výkop hrobu, uložení urny nebo otevření hrobky."
      },
      {
        "id": "triaz_poptavka",
        "from": "triaz",
        "to": "poptavka",
        "condition": "Volající poptává novou práci: pomník, nápis, opravu nebo rekonstrukci hrobu."
      },
      {
        "id": "vykop_umrti",
        "from": "vykop",
        "to": "umrti",
        "condition": "Volající během hovoru oznámí úmrtí blízké osoby."
      },
      {
        "id": "poptavka_umrti",
        "from": "poptavka",
        "to": "umrti",
        "condition": "Volající během hovoru oznámí úmrtí blízké osoby."
      }
    ]
  }
}

Hovor, který fázemi prošel NA VLASTNÍM MOTORU VOLAI (provider: "engine"), nese v GET /v1/calls/{id} (i ve výpisu GET /v1/calls) navíc pole workflowPath: pole kroků {node, label, viaEdge, turnIndex, at, enterPhraseSpoken}, at jako unix ms. Vstupní krok má viaEdge: null. Hovor agenta na ElevenLabs pole nikdy nemá, i když fázemi prošel - zapisuje ho jen post-call motoru. Hovor bez fází klíč vůbec nemá.

Koncept agenta (draft)

Koncept (draft) je oddělený rozpracovaný snímek agenta - uložíš si do něj úpravu, prohlédneš si ji, klidně ji vyzkoušíš (simulace níž) a teprve pak ji jedním voláním nasadíš na živého agenta. PUT /v1/agents/{id}/draft NIKDY nesahá na poskytovatele hlasu (ElevenLabs ani vlastní motor volai) ani na telefonii - jen uloží koncept. POST /v1/agents/{id}/draft/publish ano - je to jediný krok konceptu, který živého agenta doopravdy mění.

Naproti tomu PATCH /v1/agents/{id} (sekce Agenti výš) sahá na poskytovatele SÁM A HNED, bez konceptu a bez mezikroku.

Publikace může vrátit kteroukoli chybu PATCH /v1/agents/{id} - je to týž zápis k poskytovateli.

Editor agenta v portálu (/agent/{id}) jede VÝHRADNĚ přes koncept - i tam, kde majitel jen upraví jedno pole, portál interně volá save_agent_draft + publish_agent_draft.

Pole snímku konceptu

draft a published mají v každé odpovědi STEJNÝ tvar - AgentDraftSnapshot, kompletní snímek konfigurace agenta. Tělo PUT/publish je .strict() - na rozdíl od PATCH /v1/agents, který neznámý klíč tiše zahodí, tady neznámý klíč vrátí 400 validation. U pole workflow se při ukládání konceptu ověřuje JEN tvar JSONu - pravidla grafu (dosažitelnost fází, existující nástroje, limity na fázi) kontroluje až publikace a PATCH /v1/agents/{id}, takže koncept se uloží i s grafem, který publikace odmítne chybou invalid_workflow. Dvě výjimky z "kompletní snímek pokaždé" existují: chybějící silencePromptSecs ve snímku znamená BEZE ZMĚNY, ne vypnuto a ne výchozích 10 - u agenta na ElevenLabs nese uloženou hodnotu, která zazní až po přepnutí na vlastní motor volai. Stejně tak chybějící numberE164 znamená BEZE ZMĚNY - publikace nechá číslo živého agenta být; teprve null ho odpojí a řetězec připojí uvedené číslo, stejná trojice významů jako u PATCH /v1/agents/{id}. Za "beze změny" se počítá i řetězec, který se shoduje se ŽIVÝM číslem agenta v tu chvíli (ne s uloženou published verzí) - taková hodnota se chová jako chybějící klíč. Tohle se vyhodnocuje znovu při KAŽDÉM čtení konceptu proti tehdy aktuálně živému číslu, takže to není trvalé rozhodnutí: přesune-li se číslo později na jiného agenta mimo tenhle koncept, stejná uložená hodnota se stane výslovnou volbou a další publikace nebo rollback konceptu ho tomuhle agentovi vrátí zpátky - ne potichu, ale s varováním number_changed_by_publish ve warnings.

Zbylá pole (firstMessage, voiceId, transferTo, transferCondition, recordCalls, goal, knowledge, notifyEmail) mají stejný význam a meze jako u POST/PATCH /v1/agents - viz tabulku Nová pole agenta výš.

operation: co agenta právě blokuje

operation (u GET .../draft i GET .../draft/operation) je null, když agenta nic neblokuje, jinak objekt { id, kind, status, expectedRevision, createdAt, updatedAt }. Hodnoty kind a status jsou zúžené na to, co potřebuješ k rozhodnutí - interní detaily (kdo přesně operaci spustil, jaký byl přesný text chyby poskytovatele) ven nejdou.

tested (GET .../draft i odpověď POST .../simulate) je { revision, testedAt } | null - kdy byla naposled otestovaná PRÁVĚ TATO revize konceptu simulací. Jakákoli další úprava konceptu (PUT) marker smaže; simulace NENÍ podmínkou publikace, je to jen dobrovolná kontrola formulace před nasazením.

history je seznam { revision, publishedAt } posledních publikací (bez uložených snímků konfigurace) - kompletní historii včetně obsahu má jen portál.

curl https://volai.cz/v1/agents/ag_kx91fa2b/draft \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "draft": {
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, kavárna Nula, co si dáte?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  },
  "published": {
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, tady recepce kavárny Nula, jak vám mohu pomoct?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  },
  "revision": 4,
  "tested": {
    "revision": 4,
    "testedAt": 1756118920000
  },
  "history": [
    {
      "revision": 3,
      "publishedAt": 1756118840000
    },
    {
      "revision": 2,
      "publishedAt": 1756112640000
    }
  ],
  "operation": null
}

curl -X PUT "https://volai.cz/v1/agents/ag_kx91fa2b/draft" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":3,"draft":{"name":"Recepční","language":"cs","systemPrompt":"Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...","firstMessage":"Dobrý den, kavárna Nula, co si dáte?","voiceId":"milena","numberE164":"+420601234567","provider":"engine"}}'

{
  "draft": {
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, kavárna Nula, co si dáte?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  },
  "revision": 4
}

curl -X POST "https://volai.cz/v1/agents/ag_kx91fa2b/draft/publish" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_AGENTS_AG_KX91FA2B_DRAFT_PUBLISH_ID" \
  -d '{"expectedRevision":4}'

{
  "revision": 5,
  "published": {
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, kavárna Nula, co si dáte?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  }
}

curl -X POST "https://volai.cz/v1/agents/ag_kx91fa2b/draft/rollback" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":4,"targetRevision":2}'

{
  "revision": 5,
  "published": {
    "name": "Recepční",
    "language": "cs",
    "systemPrompt": "Jsi recepční kavárny Nula. Přijímáš objednávky na vyzvednutí...",
    "firstMessage": "Dobrý den, kavárna Nula, co si dáte?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  }
}

curl https://volai.cz/v1/agents/ag_kx91fa2b/draft/operation \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "operation": {
    "id": "ado_4f2a91cd",
    "kind": "publish",
    "status": "uncertain",
    "expectedRevision": 4,
    "createdAt": 1756118900000,
    "updatedAt": 1756118905000
  }
}

curl -X POST https://volai.cz/v1/agents/ag_kx91fa2b/draft/operation \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"ado_4f2a91cd","decision":"acknowledge_live_state"}'

{
  "reconciled": true,
  "revision": 5
}

curl -X POST https://volai.cz/v1/agents/ag_kx91fa2b/simulate \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":4,"message":"Dobry den"}'

{
  "revision": 4,
  "text": "Dobrý den, kavárna Nula, co si dáte?",
  "usage": {
    "inputTokens": 412,
    "outputTokens": 58
  },
  "tested": {
    "revision": 4,
    "testedAt": 1756118920000
  }
}

Hlasy

Katalog hlasů pro voiceId u POST/PATCH /v1/agents. Platformu říká provider; prvotní volbu určuje useForOutboundTasks. U existujícího agenta na motoru přijme PATCH každý katalogový hlas KROMĚ hlasů ElevenLabs (katty, starší anet); katty a syrové ElevenLabs ID jsou platné jen na ElevenLabs (anet tam zůstává jen agentům, kteří ho už mají). POST má jednu výjimku: explicitní true nahradí známý hlas nepodporovaný motorem, včetně katty, jeho výchozím hlasem. Pokud motor zvolí výchozí nastavení při vynechaném poli, stejná hodnota vrátí 400; syrové ElevenLabs ID motor odmítne vždy. Filtr ?provider=engine vrátí hlasy motoru, ?provider=elevenlabs hlasy ElevenLabs. Neznámá hodnota vrátí 400 validation a vyjmenuje platné hodnoty. Stejný katalog v tabulce s popisem každého hlasu je na stránce Hlasový agent.

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

{
  "voices": [
    {
      "id": "milena",
      "name": "Milena",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, warm",
      "description": "The default volai voice - calm and natural, a good fit for most agents.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/milena-studio.mp3",
        "phone": "https://volai.cz/hlasy/milena-telefon.mp3"
      },
      "default": true
    },
    {
      "id": "jan",
      "name": "Jan",
      "gender": "male",
      "provider": "cartesia",
      "tone": "calm, matter-of-fact",
      "description": "The male counterpart to Milena - matter-of-fact, easy-to-follow delivery.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/jan-studio.mp3",
        "phone": "https://volai.cz/hlasy/jan-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "tereza",
      "name": "Tereza",
      "gender": "female",
      "provider": "cartesia",
      "tone": "professional, structured",
      "description": "The second female voice - professional, well-structured delivery.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/tereza-studio.mp3",
        "phone": "https://volai.cz/hlasy/tereza-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "marek",
      "name": "Marek",
      "gender": "male",
      "provider": "cartesia",
      "tone": "calm, resonant",
      "description": "The second male voice - calm, resonant delivery for longer calls.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/marek-studio.mp3",
        "phone": "https://volai.cz/hlasy/marek-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "katarina",
      "name": "Katarina",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, natural",
      "description": "Slovak female voice - calm, natural delivery.",
      "languages": [
        "sk"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/katarina-studio.mp3",
        "phone": "https://volai.cz/hlasy/katarina-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "peter",
      "name": "Peter",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, clear",
      "description": "Slovak male voice - matter-of-fact, easy-to-follow delivery.",
      "languages": [
        "sk"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/peter-studio.mp3",
        "phone": "https://volai.cz/hlasy/peter-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "skylar",
      "name": "Skylar",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, friendly",
      "description": "English female voice - calm, friendly delivery.",
      "languages": [
        "en"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/skylar-studio.mp3",
        "phone": "https://volai.cz/hlasy/skylar-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "daniel",
      "name": "Daniel",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, confident",
      "description": "English male voice - matter-of-fact, confident delivery.",
      "languages": [
        "en"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/daniel-studio.mp3",
        "phone": "https://volai.cz/hlasy/daniel-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "alina",
      "name": "Alina",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, warm",
      "description": "German female voice - calm, warm delivery.",
      "languages": [
        "de"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/alina-studio.mp3",
        "phone": "https://volai.cz/hlasy/alina-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "lukas",
      "name": "Lukas",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, clear",
      "description": "German male voice - matter-of-fact, easy-to-follow delivery.",
      "languages": [
        "de"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/lukas-studio.mp3",
        "phone": "https://volai.cz/hlasy/lukas-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "ewa",
      "name": "Ewa",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, natural",
      "description": "Polish female voice - calm, natural delivery.",
      "languages": [
        "pl"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/ewa-studio.mp3",
        "phone": "https://volai.cz/hlasy/ewa-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "kacper",
      "name": "Kacper",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, confident",
      "description": "Polish male voice - matter-of-fact, confident delivery.",
      "languages": [
        "pl"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/kacper-studio.mp3",
        "phone": "https://volai.cz/hlasy/kacper-telefon.mp3"
      },
      "default": false
    }
  ]
}

Pole tone popisuje povahu hlasu (klidný, věcný); languages obsahuje kódy jazyků, ve kterých hlas mluví - cs: Milena, Jan, Tereza, Marek; sk: Katarina, Peter; en: Skylar, Daniel; de: Alina, Lukas; pl: Ewa, Kacper; preview nese URL studiové a telefonní ukázky; default značí doporučenou položku katalogu - v portálu nese jen štítek 'Výchozí' na kartě a sama o sobě nic nepředvybírá. Nový agent založený bez voiceId na ni nepřechází - zdědí výchozí hlas svého poskytovatele (u motoru Milenu, u ElevenLabs hlas šablony, viz sekci Agenti výš).

Nástroje agenta

Nástroj je adresa tvého API, kterou agent zavolá uprostřed hovoru (ověřit objednávku, zapsat rezervaci) a odpověď použije v řeči. Nástroj patří účtu, agentovi se přiřadí přes toolIds - samo vytvoření nástroje tedy žádného agenta nezmění.

Limity: nejvýš 10 nástrojů na účet, 10 parametrů a 5 hlaviček na nástroj, timeoutSecs 5 až 30 (výchozí 20). Adresa musí být https a veřejná - vnitřní sítě a loopback odmítáme (private_address), protože jinak by šlo naším serverem oťukávat cizí infrastrukturu.

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

{
  "tools": [
    {
      "id": "tl_5c2a91f4",
      "name": "overit_objednavku",
      "label": "Ověřit objednávku",
      "description": "Zjistí stav objednávky podle čísla. Použij, když se volající ptá, kde je jeho objednávka.",
      "url": "https://api.tvojeappka.cz/objednavky",
      "method": "POST",
      "headers": { "Authorization": "Bear***" },
      "params": [
        {
          "name": "cislo_objednavky",
          "type": "string",
          "source": "llm",
          "description": "Číslo objednávky, které volající nadiktoval.",
          "required": true
        },
        { "name": "telefon", "type": "string", "source": "caller_number" },
        { "name": "zdroj", "type": "string", "source": "constant", "constantValue": "telefon" }
      ],
      "timeoutSecs": 20,
      "createdAt": 1756111000000,
      "updatedAt": 1756111000000
    }
  ]
}

curl -X POST https://volai.cz/v1/tools \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Ověřit objednávku",
    "description": "Zjistí stav objednávky podle čísla. Použij, když se volající ptá, kde je jeho objednávka.",
    "url": "https://api.tvojeappka.cz/objednavky",
    "method": "POST",
    "headers": { "Authorization": "Bearer tvuj_klic" },
    "params": [
      {
        "name": "cislo_objednavky",
        "type": "string",
        "source": "llm",
        "description": "Číslo objednávky, které volající nadiktoval.",
        "required": true
      },
      { "name": "telefon", "type": "string", "source": "caller_number" },
      { "name": "zdroj", "type": "string", "source": "constant", "constantValue": "telefon" }
    ],
    "timeoutSecs": 20
  }'

{
  "tool": {
    "id": "tl_5c2a91f4",
    "name": "overit_objednavku",
    "label": "Ověřit objednávku",
    "description": "Zjistí stav objednávky podle čísla. Použij, když se volající ptá, kde je jeho objednávka.",
    "url": "https://api.tvojeappka.cz/objednavky",
    "method": "POST",
    "headers": { "Authorization": "Bear***" },
    "params": [
      {
        "name": "cislo_objednavky",
        "type": "string",
        "source": "llm",
        "description": "Číslo objednávky, které volající nadiktoval.",
        "required": true
      },
      { "name": "telefon", "type": "string", "source": "caller_number" },
      { "name": "zdroj", "type": "string", "source": "constant", "constantValue": "telefon" }
    ],
    "timeoutSecs": 20,
    "createdAt": 1756111000000,
    "updatedAt": 1756111000000
  }
}

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

{
  "tool": {
    "id": "tl_5c2a91f4",
    "name": "overit_objednavku",
    "label": "Ověřit objednávku",
    "description": "Zjistí stav objednávky podle čísla. Použij, když se volající ptá, kde je jeho objednávka.",
    "url": "https://api.tvojeappka.cz/objednavky",
    "method": "POST",
    "headers": { "Authorization": "Bear***" },
    "params": [
      {
        "name": "cislo_objednavky",
        "type": "string",
        "source": "llm",
        "description": "Číslo objednávky, které volající nadiktoval.",
        "required": true
      },
      { "name": "telefon", "type": "string", "source": "caller_number" },
      { "name": "zdroj", "type": "string", "source": "constant", "constantValue": "telefon" }
    ],
    "timeoutSecs": 20,
    "createdAt": 1756111000000,
    "updatedAt": 1756111000000,
    "agents": [{ "id": "ag_kx91fa2b", "name": "Recepční" }]
  }
}

curl -X PATCH https://volai.cz/v1/tools/tl_5c2a91f4 \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"timeoutSecs": 10}'

{
  "tool": {
    "id": "tl_5c2a91f4",
    "name": "overit_objednavku",
    "label": "Ověřit objednávku",
    "description": "Zjistí stav objednávky podle čísla. Použij, když se volající ptá, kde je jeho objednávka.",
    "url": "https://api.tvojeappka.cz/objednavky",
    "method": "POST",
    "headers": { "Authorization": "Bear***" },
    "params": [
      {
        "name": "cislo_objednavky",
        "type": "string",
        "source": "llm",
        "description": "Číslo objednávky, které volající nadiktoval.",
        "required": true
      },
      { "name": "telefon", "type": "string", "source": "caller_number" },
      { "name": "zdroj", "type": "string", "source": "constant", "constantValue": "telefon" }
    ],
    "timeoutSecs": 10,
    "createdAt": 1756111000000,
    "updatedAt": 1756111890000
  }
}

curl -X DELETE https://volai.cz/v1/tools/tl_5c2a91f4 \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "deleted": true,
  "agents": [
    { "id": "ag_kx91fa2b", "name": "Recepční" }
  ]
}

curl -X POST https://volai.cz/v1/tools/test \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.yourapp.com/orders", "method": "GET", "params": [{"name": "order", "type": "string", "source": "llm", "description": "Order number."}]}'

{
  "status": 200,
  "durationMs": 214,
  "body": "{\"status\":\"shipped\"}",
  "note": null
}

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

{
  "status": 200,
  "durationMs": 214,
  "body": "{\"status\":\"shipped\"}",
  "note": null
}

Parametry nástroje: pole source

Každý parametr má name, type (string, number, boolean) a source - odkud se vezme hodnota. U GET jdou parametry do query, u POST do JSON těla.

Zkušební hovor

„Nech si zavolat od svého agenta" - reálný odchozí hovor přes makeAgentCall, jen s vlastním denním limitem 3 hovory na účet (napříč všemi agenty), aby zkušební volání nešlo zneužít jako obchvat běžného limitu hovorů.

curl -X POST https://volai.cz/v1/agents/ag_kx91fa2b/test-call \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456"}'

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

Relay - vlastní agent

Jednorázový pronájem SIP jména z relay poolu pro odchozí hovor tvého vlastního hlasového agenta (ElevenLabs i jiná platforma) - bez agentní přirážky 2,50 Kč/min, tu totiž platíš u své platformy sám. Kompletní návod s nastavením ElevenLabs je na stránce Vlastní agent.

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

{
  "id": "rl_4f2a91cd",
  "sipName": "volai_relay_2",
  "sipUri": "sip:volai_relay_2@sip.volai.cz",
  "expiresAt": 1756111760000,
  "callId": "c_9d4e2b7f"
}

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

{
  "leases": [
    {
      "id": "rl_4f2a91cd",
      "sipName": "volai_relay_2",
      "sipUri": "sip:volai_relay_2@sip.volai.cz",
      "from": "+420601234567",
      "to": "+420777123456",
      "callId": "c_9d4e2b7f",
      "status": "active",
      "createdAt": 1756111640000,
      "expiresAt": 1756111760000
    }
  ]
}

curl -X DELETE https://volai.cz/v1/relay/rl_4f2a91cd \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "cancelled": true
}

Seznam nevolat (DNC)

Čísla, na která tvůj agent (vlastní i zabudovaný) nemá volat - ať přes POST /v1/calls, zkušební hovor nebo relay. DNC platí jen pro hovory - odeslání SMS na číslo v seznamu nijak neomezuje.

Kromě ručního seznamu volai destinaci automaticky (a dočasně) zablokuje samo - po 3 neúspěšných pokusech za 24 hodin (obsazeno, nezvednuto, odmítnuto) přestane na číslo volat na 30 dní. Blokaci jde zrušit v portálu (Nastavení) nebo přes POST /v1/dnc/{e164}/unblock - jinak sama odezní.

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

{
  "numbers": ["+420777998877"],
  "blocked": [
    {
      "e164": "+420777123456",
      "blockedAt": 1757600000000,
      "expiresAt": 1760192000000
    }
  ]
}

curl -X POST https://volai.cz/v1/dnc \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"e164": "+420777998877"}'

{
  "added": true,
  "e164": "+420777998877"
}

curl -X DELETE "https://volai.cz/v1/dnc/+420777998877" \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "removed": true,
  "e164": "+420777998877"
}

curl -X POST "https://volai.cz/v1/dnc/+420777998877/unblock" \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "unblocked": true,
  "e164": "+420777998877"
}

Webhook

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

{
  "url": "https://tvoje-appka.cz/webhooks/volai",
  "events": ["call.completed", "call.failed", "message.sent"],
  "recentDeliveries": [
    {
      "id": "whd_9f2b7a1c4e",
      "event": "call.completed",
      "url": "https://tvoje-appka.cz/webhooks/volai",
      "status": 200,
      "attempts": 1,
      "ok": true,
      "durationMs": 184,
      "createdAt": 1756111641000
    }
  ]
}

curl -X PUT "https://volai.cz/v1/webhook" \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tvoje-appka.cz/webhooks/volai","events":["call.completed","call.failed","message.sent"]}'

{
  "url": "https://tvoje-appka.cz/webhooks/volai",
  "secret": "whsec_9f2b7a1c4e6d8f0a",
  "events": ["call.completed", "call.failed", "message.sent"]
}

curl -X DELETE https://volai.cz/v1/webhook \
  -H "Authorization: Bearer $VOLAI_API_KEY"

{"removed":true}

curl -X POST https://volai.cz/v1/webhook/test \
  -H "Authorization: Bearer vk_TVUJ_KLIC"

{
  "delivered": true,
  "status": 200,
  "attempts": 1,
  "durationMs": 184
}