Průvodci

Úkoly

Úkol vytočí seznam příjemců jedním agentem podle pravidel, která nastavíš předem - rozpočet, volací okno, počet pokusů. Nic se nevytáčí, dokud úkol sám nespustíš.

Co je úkol

Úkol (task_...) je odchozí kampaň: jeden agent na motoru volai, seznam příjemců s telefonním číslem a volitelnými proměnnými pro systémový prompt, a pravidla (rozpočet, volací okno, maximální počet pokusů a délka hovoru). Tři typy podle účelu - invoice (upomínka platby), appointment (potvrzení termínu) a custom (cokoli jiného) - u prvních dvou navíc, když source je integration, každý příjemce nese referenci na doklad nebo událost (externalRefs), kterou agent v hovoru zmiňuje.

Stavy a přechody

V praxi jde úkol vždy ze `draft` rovnou do `running` (`start`); smazat (`DELETE`) jde jen v označených stavech.

Přesná podmínka smazání: stav je jeden z výše označených A ŽÁDNÁ položka nemá status: "in_progress" (rozvolaný hovor, který ještě neskončil) - jinak task_not_deletable.

Import příjemců (CSV)

POST /v1/tasks/csv-preview naparsuje CSV a vrátí ho zpátky s chybami u jednotlivých řádků - NIC se neukládá, jde jen o náhled před založením nebo úpravou úkolu. Stejnou funkci volá i formulář nového úkolu v portálu.

• Oddělovač se pozná automaticky (čárka nebo středník) podle prvního řádku.
• Musí existovat sloupec phone (velikost písmen nerozhoduje) - jinak celé CSV padá na chybu phone.
• Každý další sloupec je proměnná pro systémový prompt agenta ({{jméno_sloupce}}) - nejvýš 20 sloupců, název max 64 znaků, hodnota max 512 znaků.
• Telefonní číslo se normalizuje stejně jako všude v API (normalizePhone) - neplatné nebo prázdné číslo je chyba jen na TOM řádku, zbytek CSV se dál zpracuje.
• Buňka, která vypadá jako vzorec tabulkového procesoru (začíná =, +, - nebo @), se odmítne - ochrana proti CSV injection při otevření v Excelu.
• Nejvýš 100 řádků na jedno CSV (stejný strop jako počet příjemců úkolu) a 1 MB syrového textu.

Odpověď nese headers, delimiter, rows (každý řádek se svými chybami), validRows (jen bezvadné, přesně ve tvaru, který recipients v POST /v1/tasks očekává) a souhrnné errors. Pošli validRows rovnou jako recipients při založení nebo úpravě úkolu.

Rozpočet a volací okno

Rozpočet

budgetHal je STROP útraty v haléřích za celý úkol. Při založení musí pokrýt aspoň jeden pokus v maximální délce (budget_too_low, jinak); při startu se před KAŽDÝM vytočením rezervuje odhadovaná cena volání (reservedBudgetHal), teprve zvednutý hovor ji promítne do spentHal. Úkol nikdy neutratí víc, než kolik mu dáš do budgetHal.

Volací okno

callingWindow je {timezone: "Europe/Prague", start, end, days} - dnes jediné podporované pásmo je pražské, start/end ve tvaru HH:MM a days čísla 0-6 (0 = neděle). Bez zadání platí pracovní dny 9:00-18:00. Mimo okno start vrátí window_closed - buď počkej na otevření, nebo oknem upravíš přes PATCH.

Pokusy a délka hovoru

maxAttempts (1-3) říká, kolikrát se má nezvednuté číslo zkusit znovu; maxDurationSecs (30-300) je strop délky JEDNOHO hovoru, po kterém se automaticky ukončí - obojí volitelné, motor bez nich použije rozumné výchozí hodnoty.

Globální propustnost

Postup pro agenta

Typický běh, v tomto pořadí:

1. Agent úkolu musí být PUBLIKOVANÝ a publikovaná verze OTESTOVANÁ (POST /v1/agents/{id}/draft/publish, pak POST /v1/agents/{id}/simulate) - jinak pozdější start vrátí agent_not_ready.
2. Volitelně POST /v1/tasks/csv-preview - zkontroluje CSV příjemců, než se založí úkol.
3. POST /v1/tasks - založí úkol ve stavu draft. Nic se nevytáčí.
4. GET /v1/tasks/{id} - přečti issues (dry-run validace) a ověř, že úkol je připravený na start.
5. Podle potřeby PATCH /v1/tasks/{id} - uprav pravidla, VŽDY se revision z posledního čtení.
6. POST /v1/tasks/{id}/start - spustí vytáčení. Každý zvednutý hovor se účtuje ihned.
7. POST /v1/tasks/{id}/pause kdykoli za běhu, POST /v1/tasks/{id}/start znovu obnoví.
8. Po přerušení (výpadek, needs_attention) POST /v1/tasks/{id}/reconcile sladí stav se skutečnými hovory.
9. DELETE /v1/tasks/{id} na konci, pokud úkol nikdy neproběhl nebo už doběhl a chceš záznam smazat.

Skoro každé zapisující volání (PATCH, start, pause, DELETE) bere revision z posledního přečtení úkolu - stejná optimistická souběžnost jako u konceptů agenta. Neshoda vrátí revision_conflict: načti úkol znovu (GET) a zopakuj s aktuální revision. reconcile je výjimka - revision je tam nepovinná.

MCP

Stejných sedm nástrojů jako REST (list_tasks, get_task, create_task, update_task, pause_task, reconcile_task, start_task) - kromě jednoho rozdílu u startu.

start_task potvrzuje čísla

MCP start_task bere navíc confirmedRecipients a confirmedBudgetHal - musí přesně sedět na skutečný počet příjemců a rozpočet úkolu, jinak vrátí validation s vypsanými skutečnými hodnotami a NIC nespustí. Cizí AI agent na jednom nejasně pochopeném pokynu tak nemůže omylem rozjet placenou kampaň na vymyšlených číslech - REST POST .../start tuhle mechaniku nemá, protože tam volá přímo vlastník účtu vlastním klíčem.

delete_task a náhled CSV v MCP nejsou - smazání zůstává v REST a portálu (nevratná akce s opsáním názvu), CSV náhled je jen krok formuláře.

Chyby

• task_not_found - Žádný úkol s tímhle id na účtu není.
• task_not_editable - Úkol běží nebo je hotový (running/completed), nebo je needs_attention bez možnosti obnovy - pravidla teď měnit nejdou.
• items_immutable - Seznam příjemců nejde nahradit poté, co se aspoň jeden pokus o vytočení odehrál.
• budget_too_low - Rozpočet nepokryje ani jeden pokus v maximální délce hovoru - zvyš budgetHal nebo sniž maxDurationSecs.
• task_not_startable - Úkol není ve stavu draft/ready/paused, nebo nemá žádného čekajícího příjemce.
• task_needs_attention - Před dalším startem je potřeba POST .../reconcile - něco (verze agenta, motor) se za běhu změnilo.
• agent_not_ready - Koncept agenta buď není publikovaný, nebo publikovaná verze není otestovaná - publikuj ho (POST /v1/agents/{id}/draft/publish) a pak otestuj publikovanou verzi (POST /v1/agents/{id}/simulate) před startem.
• agent_version_changed - Konfigurace agenta se změnila BĚHEM běžícího úkolu - otestuj a restartuj přes reconcile.
• engine_required - Agent úkolu není na motoru volai (useForOutboundTasks: true) - odchozí kampaně dnes vyžadují motor, ne ElevenLabs.
• engine_contract_unavailable - Motor momentálně neinzeruje podporu pro proměnné a stropy odchozích úkolů - zkus start znovu později.
• window_closed - Mimo nastavené volací okno - počkej na otevření, nebo uprav callingWindow.
• task_not_running - Pauza jde jen u běžícího úkolu.
• task_not_deletable - Smazat jde jen úkol bez položky in_progress ve stavu draft/ready/paused/completed/needs_attention.
• revision_conflict - Úkol se mezitím změnil - načti ho znovu (GET) a zopakuj s aktuální revision.

Úplnou tabulku chyb pro každý endpoint najdeš v sekci Úkoly v REST API referenci.