Sprievodcovia

Úlohy

Úloha vytočí zoznam príjemcov jedným agentom podľa pravidiel, ktoré nastavíte vopred - rozpočet, volacie okno, počet pokusov. Nič sa nevytáča, kým úlohu sami nespustíte.

Čo je úloha

Úloha (task_...) je odchádzajúca kampaň: jeden agent na motore volai, zoznam príjemcov s telefónnym číslom a voliteľnými premennými pre systémový prompt a pravidlá (rozpočet, volacie okno, maximálny počet pokusov a dĺžka hovoru). Tri typy podľa účelu - invoice (upomienka platby), appointment (potvrdenie termínu) a custom (čokoľvek iné) - pri prvých dvoch navyše, keď source je integration, každý príjemca nesie odkaz na doklad alebo udalosť (externalRefs), ktorú agent v hovore spomína.

Stavy a prechody

V praxi ide úloha vždy zo `draft` rovno do `running` (`start`); zmazať (`DELETE`) sa dá len v označených stavoch.

Presná podmienka zmazania: stav je jeden z vyššie označených A ŽIADNA položka nemá status: "in_progress" (rozvolaný hovor, ktorý ešte neskončil) - inak task_not_deletable.

Import príjemcov (CSV)

POST /v1/tasks/csv-preview naparsuje CSV a vráti ho späť s chybami pri jednotlivých riadkoch - NIČ sa neukladá, ide len o náhľad pred založením alebo úpravou úlohy. Rovnakú funkciu volá aj formulár novej úlohy v portáli.

• Oddeľovač sa spozná automaticky (čiarka alebo bodkočiarka) podľa prvého riadku.
• Musí existovať stĺpec phone - veľkosť písmen, medzery okolo názvu ani dvojbodka za ním nerozhodujú a prejde aj telefon, tel alebo mobil; v náhľade sa stĺpec vracia vždy ako phone. Samotný zoznam čísel bez hlavičky (jedno na riadok, jediný stĺpec) prejde tiež. Inak celé CSV padá na jedinú chybu phone pri hlavičke.
• Každý ďalší stĺpec je premenná pre systémový prompt agenta ({{column_name}}) - najviac 20 stĺpcov, názov max 64 znakov, hodnota max 512 znakov.
• Telefónne číslo sa normalizuje rovnako ako všade v API (normalizePhone) - neplatné alebo prázdne číslo je chyba len na TOM riadku, zvyšok CSV sa spracuje ďalej.
• Bunka, ktorá vyzerá ako vzorec tabuľkového procesora (začína =, +, - alebo @), sa odmietne - ochrana proti CSV injection pri otvorení v Exceli.
• Najviac 1000 riadkov na jedno CSV (rovnaký strop ako počet príjemcov úlohy) a 1 MB surového textu; celá úloha aj s podkladmi sa musí zmestiť do 2 MB, inak založenie vráti validation.

Odpoveď nesie headers, delimiter, rows (každý riadok so svojimi chybami), validRows (len bezchybné, presne v tvare, aký recipients v POST /v1/tasks očakáva) a súhrnné errors. Pošlite validRows rovno ako recipients pri založení alebo úprave úlohy.

Rozpočet a volacie okno

Rozpočet

budgetHal je STROP výdavkov v halieroch za celú úlohu. Pri založení musí pokryť aspoň jeden pokus v maximálnej dĺžke (inak budget_too_low); pri štarte sa pred KAŽDÝM vytočením rezervuje najvyššia možná cena pokusu (reservedBudgetHal), až zdvihnutý hovor ju premietne do spentHal. Rezervácia je cena hovoru presne v dĺžke maxDurationSecs (noha hovoru a noha agenta, každá zaokrúhlená nahor na halier rovnako ako pri účtovaní) a hovor ukončený stropom dĺžky sa účtuje najviac za maxDurationSecs, aj keď skončí o zlomok sekundy neskôr. Úloha nikdy neminie viac, než koľko jej dáte do budgetHal.

Volacie okno

callingWindow je {timezone: "Europe/Prague", start, end, days} - dnes jediné podporované pásmo je pražské, start/end v tvare HH:MM (koniec vrátane celej minúty: okno 09:00-18:00 pustí posledný hovor o 18:00:59, okno do 23:59 pokrýva celý deň) a days čísla 0-6 (0 = nedeľa). Bez zadania platia pracovné dni 9:00-18:00. Mimo okna start vráti window_closed - buď počkajte na otvorenie, alebo okno upravíte cez PATCH. Voliteľné expiresAt je koniec kampane ako kladné bezpečné celé číslo v Unix milisekundách. Kontroluje sa pri štarte a pred každým vytočením vrátane prvého. Od tohto okamihu nový hovor nezačne a pokus sa nespotrebuje; prebiehajúci hovor dobehne. Horizont opakovania politiky lorela_enterprise (retryMaxAgeDays, predvolene 5) sa naopak počíta ako N × 24 hodín od prvého započítaného pokusu, nie od založenia úlohy.

Pokusy a dĺžka hovoru

maxAttempts je bez politiky 1-3 (predvolene 1), s retryPolicy: "lorela_enterprise" 1-4 (pri založení predvolene 4). Určuje najvyšší počet automatických vytočení jedného kontaktu vrátane prvého (1 = bez opakovania). Počíta sa každý pokus, pri ktorom hovor mohol prebehnúť, teda aj nezdvihnutý alebo odmietnutý volaným a pokus s neistým výsledkom. Nepočíta sa pokus, ktorý volai odmietol ešte pred vytočením (napríklad blokované, vlastné alebo neplatné číslo, zoznam nevolať, číslo, na ktoré práve beží iný hovor, limity hovorov); takýto pokus má items[].attempts[].countsAsAttempt: false. Nepočíta sa ani hovor, ktorému operátor nedostal včas cieľ, takže telefón volaného vôbec nezazvonil (pokus má errorCode: "relay_not_routed", hovor endReason: "rejected"): kontakt dostane nový pokus najskôr o minútu (s politikou lorela_enterprise podľa jej rozvrhu) a po treťom takomto pokuse za sebou ide na kontrolu s reviewReason: "call:relay_not_routed". Nepočíta sa ani hovor, o ktorom náš hlasový motor nikdy nedal vedieť a ktorý sme po dvoch hodinách bez správy uzavreli ako nevytočený a bez ceny (pokus má errorCode: "no_provider_report"): kontakt sa vracia medzi čakajúce a dostane nový pokus najskôr o minútu (s politikou lorela_enterprise podľa jej rozvrhu). Tri nepočítané pokusy za sebou, aj zmiešané s pokusmi relay_not_routed, pošlú kontakt na kontrolu s reviewReason podľa posledného z nich, teda call:no_provider_report; kontakty, ktoré takýto hovor poslal na kontrolu skôr (call:failed, s politikou call:unknown), sa samy neobnovujú. Bez politiky platí strop len pre automatické vytočenia: kontakt, ktorému po vyčerpaní pokusov dáte resolve s action: "retry", dostane ešte jedno vytočenie navyše. maxDurationSecs (30-300) je strop dĺžky JEDNÉHO hovoru, po ktorom sa automaticky ukončí - predvolená dĺžka je 120 sekúnd. Voliteľná politika lorela_enterprise sa zapína cez API alebo MCP pred prvým pokusom; existujúce úlohy sa samy nemenia. Druhý pokus je najskôr 8 minút od začiatku prvého skutočného pokusu v čase 08:00-22:00 Europe/Prague. Tretí ide do ďalšieho iného okna 08:00-09:00 alebo 17:00-19:00, štvrtý do opačného okna nasledujúci kalendárny deň. Vždy platí aj callingWindow a jeho dni; po horizonte opakovania už politika znova nevolá: voliteľný retryMaxAgeDays je celé číslo dní 1-30 (bez zadania 5) a platí len s politikou. Horizont končí N × 24 hodín od prvého započítaného pokusu kontaktu (pevné 24-hodinové dni, takže cez zmenu času sa miestny čas konca posunie o hodinu). Dá sa zmeniť cez PATCH aj po začiatku pokusov (nie pri úlohe running alebo completed, tú upraviť nejde): zvýšenie pri pozastavenej úlohe vráti kontakty, ktoré prepadli len kvôli horizontu (reviewReason: "retry_age_expired"), späť do stavu failed (čakajú na ďalší pokus) s novým nextAttemptAt, ak majú ešte voľný pokus a najbližší slot rozvrhu padne do nového horizontu a pred expiresAt; zníženie nič neotvorí. Znova otvára len PATCH, ktorý horizont zvyšuje, preto retryMaxAgeDays a predĺžený expiresAt posielajte v jednej požiadavke. Opakuje len no_answer, missed, busy, dokončenú hlasovú schránku a zdvihnutý hovor, v ktorom volaný nič nepovedal (všetko bez kontaktu s človekom). Kontakt s človekom, odmietnutie a chyba motora automatické opakovanie zastavia; nejasný výsledok ide na kontrolu. Posledný dovolený pokus (maxAttempts), ktorý skončí takýmto opakovateľným výsledkom (nezdvihnuté, obsadené, hlasová schránka alebo zdvihnutý hovor, v ktorom volaný nič nepovedal), uzavrie kontakt ako skipped s reviewReason: "retry_policy_exhausted" (ako retry_age_expired po uplynutí horizontu): nie je čo kontrolovať ani opakovať. Nejasný výsledok posledného pokusu zostane v review s rovnakým dôvodom. Bez politiky sa nič nemení: posledný nezdvihnutý pokus je naďalej review. Overený ľudský callback po vyčerpaní pokusov kontakt prepne na completed. DNC, rozpočet a limity zostávajú v platnosti: automatická blokácia po 3 neúspechoch za 24 hodín môže zastaviť aj štvrtý pokus. Pri PATCH bez maxAttempts zostane doterajší limit. S politikou vracia ručný resolve s action: "retry" chybu validation; povolené sú len jej automaticky naplánované pokusy. Výnimkou je obnova preukázateľne nevytočeného zaniknutého claimu pred prvým skutočným pokusom: bez aktívneho workera, dispatch zámeru, provider call ID, rezervácie, ceny alebo callbacku a len s preukázanými odmietnutiami pred vytočením v histórii. Obnova zachová históriu a stropy a vráti kontakt medzi čakajúce v pozastavenej úlohe; sama nevolá. Pripomienky takto znova otvoriť nemožno. Ručné opakovanie teda neobíde štyri pokusy, horizont opakovania ani ukončenie po kontakte s človekom.

Globálna priepustnosť

Postup pre agenta

Typický beh, v tomto poradí:

1. Agent úlohy musí byť PUBLIKOVANÝ a publikovaná verzia OTESTOVANÁ (POST /v1/agents/{id}/draft/publish, potom POST /v1/agents/{id}/simulate) - inak neskorší start vráti agent_not_ready.
2. Voliteľne POST /v1/tasks/csv-preview - skontroluje CSV príjemcov, kým sa založí úloha.
3. POST /v1/tasks - založí úlohu v stave draft. Nič sa nevytáča.
4. GET /v1/tasks/{id} - prečítajte issues (dry-run validácia) a overte, že úloha je pripravená na štart.
5. Podľa potreby PATCH /v1/tasks/{id} - upravte pravidlá, VŽDY s revision z posledného čítania.
6. POST /v1/tasks/{id}/start - spustí vytáčanie. Každý zdvihnutý hovor sa účtuje hneď.
7. POST /v1/tasks/{id}/pause kedykoľvek za behu, POST /v1/tasks/{id}/start znova obnoví.
8. Po prerušení (pozastavenie uprostred hovoru, zaniknutý claim, hovor s doteraz neznámou cenou alebo neisté vytočenie, ku ktorému sa hovor dohľadal) POST /v1/tasks/{id}/reconcile zosúladí stav so skutočnými hovormi; takáto úloha s prácou skončí v paused, aj keď niektoré kontakty čakajú v review, a dá sa znova spustiť cez start. Bežiacu úlohu ani iný dôvod (variables_limit, zlyhanie overenia faktúry alebo kalendára, neisté vytočenie, ku ktorému sa hovor nedohľadal) reconcile nemení; kontakty na kontrolu vybavte cez resolve.
9. Kontakt, ktorý skončil na kontrole (items[].status: "review"), vybavte POST /v1/tasks/{id}/items/{itemId}/resolve s action: "retry" alebo "skip". Pri bežnom dôvode vráti retry kontakt medzi čakajúce a úlohu do paused; skip ho uzavrie a úloha prejde do paused, ak zostáva práca, alebo do completed, ak sú všetky kontakty hotové či preskočené. Úlohu v paused potom obnovte POST /v1/tasks/{id}/start.
10. Keď má kontakt reviewReason: "dial:destination_auto_blocked", číslo je 30 dní automaticky blokované po opakovane nezdvihnutých hovoroch a samotný retry ho neodblokuje - kontakt by sa hneď vrátil do review. Najprv zrušte blokáciu (POST /v1/dnc/{e164}/unblock, v MCP unblock_destination, číslo vezmite z items[].phone), potom resolve s action: "retry". Pri dial:on_dnc najprv odoberte číslo zo zoznamu nevolať (DELETE /v1/dnc/{e164}), inak kontakt preskočte. Pri vlastnom čísle účtu, čísle iného účtu volai, neplatnom čísle, čísle mimo Česka a Slovenska a prémiovej linke (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) ďalší pokus nepomôže: použite len skip.
11. Keď má kontakt reviewReason: "billing_unknown", pôvodný hovor už mohol prebehnúť, len ešte nemá známu cenu. Najprv zavolajte reconcile a skontrolujte nadviazaný hovor. retry si zapamätá, že sa má kontakt skúsiť znova, ale nový hovor nepovolí, kým sa pôvodná cena neusadí; potom úloha prejde do paused a vyžaduje nový start. skip zabráni ďalšiemu hovoru; pôvodný hovor zostáva nadviazaný a jeho rezervácia sa naďalej počíta do rozpočtu, kým sa cena neusadí. Ak zostáva práca, úloha po skip prejde rovno do paused a dá sa spustiť; bez ďalšej práce počká v needs_attention a po usadení ceny skončí v completed. Hovor, ktorý sa vôbec nevytočil (motor ho odmietol), sa nikdy neúčtuje a usadí sa hneď na 0.
12. Kontakt, ktorý medzitým nakúpil alebo sa odhlásil, preskočte bez hovoru cez resolve s action: "skip", reason: "customer_purchased" alebo "unsubscribed", revision, stálym operationId a evidenceRef, ktorý odkazuje na doklad nákupu alebo odhlásenia (nikdy na telefón či e-mail). Dá sa to pri pending kontakte v draft úlohe a pri pending/failed v paused úlohe bez nevyrovnaného hovoru; pokusy, ceny aj zoznam nevolať zostanú. GET /v1/tasks/{id} potom ukáže doklad v items[].resolution (reason, operationId, evidenceRef, resolvedAt); rovnaké telo možno bezpečne zopakovať, iný reason alebo evidenceRef pri tom istom kontakte je 409 revision_conflict. Preskočenie číslo na zoznam nevolať nezapisuje: ak sa má kontakt už nikdy nevolať, pridajte ho cez POST /v1/dnc.
13. DELETE /v1/tasks/{id} na konci, ak úloha nikdy neprebehla alebo už dobehla a chcete záznam zmazať.

Takmer každé zapisujúce volanie (PATCH, start, pause, DELETE) berie revision z posledného prečítania úlohy - rovnaká optimistická súbežnosť ako pri konceptoch agenta. Nezhoda vráti revision_conflict: načítajte úlohu znova (GET) a zopakujte s aktuálnou revision. reconcile je výnimka - revision je tam nepovinná.

MCP

Rovnaké nástroje ako REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - okrem jedného rozdielu pri štarte.

start_task potvrdzuje čísla

MCP start_task berie navyše confirmedRecipients a confirmedBudgetHal - musia presne sedieť na skutočný počet príjemcov a rozpočet úlohy, inak vráti validation s vypísanými skutočnými hodnotami a NIČ nespustí. Cudzí AI agent na jednom nejasne pochopenom pokyne tak nemôže omylom rozbehnúť platenú kampaň na vymyslených číslach - REST POST .../start túto mechaniku nemá, pretože tam volá priamo vlastník účtu vlastným kľúčom.

delete_task a náhľad CSV v MCP nie sú - zmazanie zostáva v REST a portáli (nevratná akcia s opísaním názvu), CSV náhľad je len krok formulára.

Chyby

• task_not_found - Žiadna úloha s týmto id na účte nie je.
• task_not_editable - Úloha beží alebo je hotová (running/completed), alebo je needs_attention bez možnosti obnovy - pravidlá teraz meniť nejde. Rovnaký kód vracia aj POST .../items/{itemId}/resolve pri bežiacej úlohe: kontakt v review sa objaví, už keď úloha volá ostatné kontakty a je ešte running - počkajte, kým prejde do needs_attention, alebo ju pozastavte (POST .../pause).
• items_immutable - Zoznam príjemcov nejde nahradiť po tom, čo sa aspoň jeden pokus o vytočenie odohral alebo bol kontakt preskočený s reason (nákup či odhlásenie).
• budget_too_low - Rozpočet nepokryje ani jeden pokus v maximálnej dĺžke hovoru - zvýšte budgetHal alebo znížte maxDurationSecs.
• task_not_startable - Úloha nie je v stave draft/ready/paused, alebo nemá žiadneho čakajúceho príjemcu.
• task_needs_attention - Pred ďalším štartom je potrebný POST .../reconcile - niečo (verzia agenta, motor) sa počas behu zmenilo.
• agent_not_ready - Koncept agenta buď nie je publikovaný, alebo publikovaná verzia nie je otestovaná - publikujte ho (POST /v1/agents/{id}/draft/publish) a potom otestujte publikovanú verziu (POST /v1/agents/{id}/simulate) pred štartom.
• agent_version_changed - Konfigurácia agenta sa zmenila POČAS bežiacej úlohy - otestujte a reštartujte cez reconcile.
• engine_required - Agent úlohy nie je na motore volai (useForOutboundTasks: true) - odchádzajúce kampane dnes vyžadujú motor, nie ElevenLabs.
• engine_contract_unavailable - Motor momentálne neinzeruje podporu pre premenné a stropy odchádzajúcich úloh - skúste štart znova neskôr.
• window_closed - Mimo nastaveného volacieho okna - počkajte na otvorenie, alebo upravte callingWindow.
• task_not_running - Pauza ide len pri bežiacej úlohe.
• item_not_resolvable - Kontakt nie je v stave review - rozhodnúť (retry/skip) sa dá len o kontakte čakajúcom na kontrolu, a len pri úlohe, ktorá nebeží. Výnimkou je preskočenie s reason (customer_purchased, unsubscribed): to chce neaktívny pending kontakt v draft úlohe, alebo pending/failed v paused, bez nevyrovnaného hovoru.
• task_not_deletable - Zmazať ide len úloha bez položky in_progress v stave draft/ready/paused/completed/needs_attention.
• revision_conflict - Úloha sa medzitým zmenila - načítajte ju znova (GET) a zopakujte s aktuálnou revision.

Úplnú tabuľku chýb pre každý endpoint nájdete v sekcii Úlohy v REST API referencii.