Vodiči

Naloge

Naloga z enim agentom pokliče seznam prejemnikov po pravilih, ki jih določite vnaprej - proračun, klicno okno, število poskusov. Nič se ne kliče, dokler nalogo sami ne zaženete.

Kaj je naloga

Naloga (task_...) je odhodna kampanja: en agent na motorju volai, seznam prejemnikov s telefonsko številko in neobveznimi spremenljivkami za sistemski prompt ter pravila (proračun, klicno okno, največje število poskusov in trajanje klica). Trije tipi glede na namen - invoice (opomnik za plačilo), appointment (potrditev termina) in custom (karkoli drugega) - pri prvih dveh pa, kadar je source enak integration, vsak prejemnik nosi sklic na dokument ali dogodek (externalRefs), ki ga agent v klicu omeni.

Stanja in prehodi

V praksi naloga vedno preide iz `draft` neposredno v `running` (`start`); brisanje (`DELETE`) je mogoče le v označenih stanjih.

Natančen pogoj za brisanje: stanje je eno od zgoraj označenih IN NOBEN element nima status: "in_progress" (začet klic, ki se še ni končal) - sicer task_not_deletable.

Uvoz prejemnikov (CSV)

POST /v1/tasks/csv-preview razčleni CSV in ga vrne nazaj z napakami pri posameznih vrsticah - NIČ se ne shrani, gre le za predogled pred ustvarjanjem ali urejanjem naloge. Isto funkcijo kliče tudi obrazec nove naloge v portalu.

• Ločilo se prepozna samodejno (vejica ali podpičje) po prvi vrstici.
• Obstajati mora stolpec phone - velikost črk, presledki okoli imena in dvopičje za njim ne vplivajo, veljajo pa tudi telefon, tel ali mobil; v predogledu se stolpec vedno vrne kot phone. Veljaven je tudi sam seznam številk brez glave (ena na vrstico, en sam stolpec). Sicer celoten CSV pade na eno samo napako phone pri glavi.
• Vsak nadaljnji stolpec je spremenljivka za sistemski prompt agenta ({{column_name}}) - največ 20 stolpcev, ime do 64 znakov, vrednost do 512 znakov.
• Telefonska številka se normalizira enako kot povsod v API (normalizePhone) - neveljavna ali prazna številka je napaka le v TEJ vrstici, ostanek CSV se obdela naprej.
• Celica, ki izgleda kot formula preglednice (začne se z =, +, - ali @), se zavrne - zaščita pred vbrizgavanjem v CSV ob odpiranju v Excelu.
• Največ 1000 vrstic na en CSV (enaka zgornja meja kot število prejemnikov naloge) in 1 MB surovega besedila; cela naloga z gradivi se mora prilegati v 2 MB, sicer ustvarjanje vrne validation.

Odgovor vsebuje headers, delimiter, rows (vsaka vrstica s svojimi napakami), validRows (samo brezhibne, natanko v obliki, ki jo recipients v POST /v1/tasks pričakuje) in zbirne errors. validRows pošljite kar kot recipients pri ustvarjanju ali urejanju naloge.

Proračun in klicno okno

Proračun

budgetHal je ZGORNJA MEJA porabe v stotinih (halerjih) za celotno nalogo. Ob ustvarjanju mora pokriti vsaj en poskus v največji dolžini (sicer budget_too_low); ob zagonu se pred VSAKIM klicanjem rezervira najvišja možna cena poskusa (reservedBudgetHal), šele sprejeti klic jo prenese v spentHal. Rezervacija je cena klica natanko v dolžini maxDurationSecs (krak klica in krak agenta, vsak zaokrožen navzgor na stotin kot pri obračunavanju), klic, končan z omejitvijo trajanja, pa se obračuna največ za maxDurationSecs, tudi če se konča delček sekunde pozneje. Naloga nikoli ne porabi več, kot ji daste v budgetHal.

Klicno okno

callingWindow je {timezone: "Europe/Prague", start, end, days} - danes je edino podprto časovno območje praško, start/end v obliki HH:MM (konec vključno s celo minuto: okno 09:00-18:00 spusti zadnji klic ob 18:00:59, okno do 23:59 pokriva cel dan) in days števila 0-6 (0 = nedelja). Brez vnosa veljajo delovni dnevi 9:00-18:00. Zunaj okna start vrne window_closed - počakajte, da se okno odpre, ali pa okno uredite prek PATCH. Neobvezni expiresAt je konec kampanje kot pozitivno varno celo število v Unix milisekundah. Preverja se ob zagonu in pred vsakim klicanjem, vključno s prvim. Od tega trenutka nov klic ne začne in poskus se ne porabi; tekoči klic se dokonča. Obzorje ponavljanja politike lorela_enterprise (retryMaxAgeDays, privzeto 5) se nasprotno šteje kot N × 24 ur od prvega všetega poskusa, ne od ustvarjanja naloge.

Poskusi in trajanje klica

maxAttempts je brez politike 1-3 (privzeto 1), s retryPolicy: "lorela_enterprise" 1-4 (ob ustvarjanju privzeto 4). Določa najvišje število samodejnih klicanj enega stika, vključno s prvim (1 = brez ponavljanja). Šteje se vsak poskus, pri katerem je klic lahko potekel, torej tudi neodgovorjen ali zavrnjen s strani klicanega in poskus z negotovim izidom. Ne šteje se poskus, ki ga je volai zavrnil še pred klicanjem (na primer blokirana, lastna ali neveljavna številka, seznam ne kliči, številka, na katero trenutno teče drug klic, omejitve klicev); tak poskus ima items[].attempts[].countsAsAttempt: false. Ne šteje se niti klic, pri katerem operater cilja ni pravočasno prejel, zato telefon klicanega sploh ni zazvonil (poskus ima errorCode: "relay_not_routed", klic endReason: "rejected"): stik dobi nov poskus najprej čez minuto (s politiko lorela_enterprise po njenem razporedu), po tretjem takem zaporednem poskusu pa gre v pregled z reviewReason: "call:relay_not_routed". Ne šteje se niti klic, o katerem naš glasovni motor nikoli ni sporočil in ki smo ga po dveh urah brez poročila zaprli kot nepoklican in brez cene (poskus ima errorCode: "no_provider_report"): stik se vrne med čakajoče in dobi nov poskus najprej čez minuto (s politiko lorela_enterprise po njenem razporedu). Trije neštevni poskusi zapored, tudi pomešani s poskusi relay_not_routed, pošljejo stik v pregled z reviewReason po zadnjem od njih, torej call:no_provider_report; stikov, ki jih je tak klic prej poslal v pregled (call:failed, s politiko call:unknown), se samodejno ne obnavlja. Brez politike omejitev velja le za samodejna klicanja: stik, ki mu po izčrpanju poskusov date resolve z action: "retry", dobi še eno dodatno klicanje. maxDurationSecs (30-300) je zgornja meja trajanja ENEGA klica, po kateri se samodejno konča - privzeto trajanje je 120 sekund. Neobvezna politika lorela_enterprise se vklopi prek API ali MCP pred prvim poskusom; obstoječe naloge se same ne spreminjajo. Drugi poskus je najprej 8 minut od začetka prvega dejanskega poskusa v času 08:00-22:00 Europe/Prague. Tretji gre v naslednje drugačno okno 08:00-09:00 ali 17:00-19:00, četrti v nasprotno okno naslednji koledarski dan. Vedno veljata tudi callingWindow in njegovi dnevi; po obzorju ponavljanja politika ne kliče več: neobvezni retryMaxAgeDays je celo število dni 1-30 (brez vnosa 5) in velja le s politiko. Obzorje se konča N × 24 ur od prvega všetega poskusa stika (stalni 24-urni dnevi, zato se ob spremembi časa lokalni čas konca premakne za uro). Spremeniti ga je mogoče prek PATCH tudi po začetku poskusov (ne pri nalogi running ali completed, te urejati ni mogoče): zvišanje pri ustavljeni nalogi vrne stike, ki so propadli le zaradi obzorja (reviewReason: "retry_age_expired"), nazaj v stanje failed (čakajo na naslednji poskus) z novim nextAttemptAt, če imajo še prost poskus in najbližja reža razporeda pade v novo obzorje in pred expiresAt; znižanje ničesar ne odpre. Ponovno odpira samo PATCH, ki obzorje zvišuje, zato retryMaxAgeDays in podaljšani expiresAt pošljite v isti zahtevi. Ponavlja le no_answer, missed, busy, dokončan odzivnik in sprejet klic, v katerem klicani ni ničesar rekel (vse brez stika s človekom). Stik s človekom, zavrnitev in napaka motorja samodejno ponavljanje ustavijo; nejasen izid gre v pregled. Zadnji dovoljeni poskus (maxAttempts), ki se konča z takim ponovljivim izidom (neodgovorjeno, zasedeno, odzivnik ali sprejet klic, v katerem klicani ni ničesar rekel), stik zapre kot skipped z reviewReason: "retry_policy_exhausted" (kot retry_age_expired po izteku obzorja): ni kaj pregledovati ali ponavljati. Nejasen izid zadnjega poskusa ostane v review z istim razlogom. Brez politike se nič ne spremeni: zadnji neodgovorjeni poskus je še naprej review. Preverjen človeški povratni klic po izčrpanju poskusov stik prestavi na completed. DNC, proračun in omejitve ostanejo v veljavi: samodejna blokada po 3 neuspehih v 24 urah lahko ustavi tudi četrti poskus. Pri PATCH brez maxAttempts ostane dosedanja omejitev. S politiko ročni resolve z action: "retry" vrne napako validation; dovoljeni so samo njeni samodejno načrtovani poskusi. Izjema je obnova dokazljivo nepoklicanega poteklega claima pred prvim dejanskim poskusom: brez aktivnega delavca, namena razpošiljanja, ID-ja klica pri ponudniku, rezervacije, cene ali povratnega klica in samo z dokazanimi zavrnitvami pred klicanjem v zgodovini. Obnova ohrani zgodovino in omejitve ter vrne stik med čakajoče v ustavljeni nalogi; sama ne kliče. Opomnikov na ta način ni mogoče znova odpreti. Ročno ponavljanje torej ne zaobide štirih poskusov, obzorja ponavljanja ali končanja po stiku s človekom.

Globalna prepustnost

Postopek za agenta

Tipičen potek, v tem vrstnem redu:

1. Agent naloge mora biti OBJAVLJEN in objavljena različica PREIZKUŠENA (POST /v1/agents/{id}/draft/publish, nato POST /v1/agents/{id}/simulate) - sicer poznejši start vrne agent_not_ready.
2. Neobvezno POST /v1/tasks/csv-preview - preveri CSV prejemnikov, preden se naloga ustvari.
3. POST /v1/tasks - ustvari nalogo v stanju draft. Nič se ne kliče.
4. GET /v1/tasks/{id} - preberite issues (validacija na suho) in preverite, da je naloga pripravljena na zagon.
5. Po potrebi PATCH /v1/tasks/{id} - uredite pravila, VEDNO z revision iz zadnjega branja.
6. POST /v1/tasks/{id}/start - zažene klicanje. Vsak sprejet klic se obračuna takoj.
7. POST /v1/tasks/{id}/pause kadar koli med potekom, POST /v1/tasks/{id}/start znova nadaljuje.
8. Po prekinitvi (premor sredi klica, potekel claim, klic s še neznano ceno ali negotovo klicanje, za katero se je klic našel) POST /v1/tasks/{id}/reconcile uskladi stanje z dejanskimi klici; taka naloga z delom konča v paused, tudi če nekateri stiki čakajo v review, in jo je mogoče znova zagnati prek start. Tekoče naloge ali drugega razloga (variables_limit, neuspeh preverjanja računa ali koledarja, negotovo klicanje, za katero se klic ni našel) reconcile ne spreminja; stike za pregled rešite prek resolve.
9. Stik, ki je končal v pregledu (items[].status: "review"), rešite z POST /v1/tasks/{id}/items/{itemId}/resolve z action: "retry" ali "skip". Pri običajnem razlogu retry vrne stik med čakajoče in nalogo v paused; skip ga zapre in naloga preide v paused, če dela ostaja, ali v completed, če so vsi stiki opravljeni ali preskočeni. Nalogo v paused nato obnovite z POST /v1/tasks/{id}/start.
10. Kadar ima stik reviewReason: "dial:destination_auto_blocked", je številka 30 dni samodejno blokirana po ponavljajoče neodgovorjenih klicih in samo retry je ne odblokira - stik bi se takoj vrnil v review. Najprej prekličite blokado (POST /v1/dnc/{e164}/unblock, v MCP unblock_destination, številko vzemite iz items[].phone), nato resolve z action: "retry". Pri dial:on_dnc najprej odstranite številko s seznama ne kliči (DELETE /v1/dnc/{e164}), sicer stik preskočite. Pri lastni številki računa, številki drugega računa volai, neveljavni številki, številki zunaj Češke in Slovaške ter premijski liniji (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) nadaljnji poskus ne pomaga: uporabite samo skip.
11. Kadar ima stik reviewReason: "billing_unknown", je prvotni klic morda že potekel, le cena mu še ni znana. Najprej pokličite reconcile in preverite povezani klic. retry si zapomni, da naj se stik poskusi znova, vendar novega klica ne dovoli, dokler se prvotna cena ne ustali; nato naloga preide v paused in zahteva nov start. skip prepreči nadaljnji klic; prvotni klic ostane povezan in njegova rezervacija se še naprej šteje v proračun, dokler se cena ne ustali. Če dela ostaja, naloga po skip preide kar v paused in jo je mogoče zagnati; brez nadaljnjega dela počaka v needs_attention in po ustalitvi cene konča v completed. Klic, ki se sploh ni poklical (motor ga je zavrnil), se nikoli ne obračuna in se ustali takoj na 0.
12. Stik, ki je medtem kupil ali se odjavil, preskočite brez klica prek resolve z action: "skip", reason: "customer_purchased" ali "unsubscribed", revision, stalnim operationId in evidenceRef, ki kaže na dokazilo o nakupu ali odjavi (nikoli na telefon ali e-pošto). To je mogoče pri stiku pending v nalogi draft in pri pending/failed v nalogi paused brez neporavnanega klica; poskusi, cene in seznam ne kliči ostanejo. GET /v1/tasks/{id} nato pokaže dokazilo v items[].resolution (reason, operationId, evidenceRef, resolvedAt); isto telo je mogoče varno ponoviti, drug reason ali evidenceRef pri istem stiku je 409 revision_conflict. Preskok številke ne zapiše na seznam ne kliči: če stika ne smete nikoli več poklicati, ga dodajte prek POST /v1/dnc.
13. DELETE /v1/tasks/{id} na koncu, če naloga ni nikoli potekla ali je že končana in želite zapis izbrisati.

Skoraj vsak pisalni klic (PATCH, start, pause, DELETE) vzame revision iz zadnjega branja naloge - enaka optimistična sočasnost kot pri osnutkih agenta. Neujemanje vrne revision_conflict: ponovno naložite nalogo (GET) in ponovite z aktualno revision. reconcile je izjema - revision je tam neobvezna.

MCP

Ista orodja kot REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - razen ene razlike pri zagonu.

start_task potrjuje številke

MCP start_task dodatno vzame confirmedRecipients in confirmedBudgetHal - ujemati se morata natanko z dejanskim številom prejemnikov in proračunom naloge, sicer vrne validation z izpisanimi dejanskimi vrednostmi in NIČESAR ne zažene. Tuj AI-agent tako na enem nejasno razumljenem navodilu ne more pomotoma zagnati plačljive kampanje z izmišljenimi številkami - REST POST .../start te mehanike nima, ker tam kliče neposredno lastnik računa z lastnim ključem.

delete_task in predogleda CSV v MCP ni - brisanje ostaja v REST in portalu (nepovratno dejanje s prepisom imena), predogled CSV je le korak obrazca.

Napake

• task_not_found - Na računu ni naloge s tem id.
• task_not_editable - Naloga teče ali je končana (running/completed) ali pa je needs_attention brez možnosti obnove - pravil zdaj ni mogoče spreminjati. Isto kodo vrne tudi POST .../items/{itemId}/resolve pri tekoči nalogi: stik v review se pojavi že, ko naloga kliče ostale stike in je še running - počakajte, da preide v needs_attention, ali pa jo ustavite (POST .../pause).
• items_immutable - Seznama prejemnikov ni mogoče zamenjati, ko je bil izveden vsaj en poskus klicanja ali je bil stik preskočen z reason (nakup ali odjava).
• budget_too_low - Proračun ne pokrije niti enega poskusa v največji dolžini klica - zvišajte budgetHal ali znižajte maxDurationSecs.
• task_not_startable - Naloga ni v stanju draft/ready/paused ali nima nobenega čakajočega prejemnika.
• task_needs_attention - Pred naslednjim zagonom je treba POST .../reconcile - nekaj (različica agenta, motor) se je med potekom spremenilo.
• agent_not_ready - Osnutek agenta ni objavljen ali pa objavljena različica ni preizkušena - objavite ga (POST /v1/agents/{id}/draft/publish) in nato pred zagonom preizkusite objavljeno različico (POST /v1/agents/{id}/simulate).
• agent_version_changed - Konfiguracija agenta se je spremenila MED tekočo nalogo - preizkusite in znova zaženite prek reconcile.
• engine_required - Agent naloge ni na motorju volai (useForOutboundTasks: true) - odhodne kampanje danes zahtevajo motor, ne ElevenLabs.
• engine_contract_unavailable - Motor trenutno ne oglašuje podpore za spremenljivke in omejitve odhodnih nalog - poskusite zagon znova pozneje.
• window_closed - Zunaj nastavljenega klicnega okna - počakajte, da se odpre, ali uredite callingWindow.
• task_not_running - Premor je mogoč le pri tekoči nalogi.
• item_not_resolvable - Stik ni v stanju review - odločiti (retry/skip) je mogoče samo o stiku, ki čaka na pregled, in samo pri nalogi, ki ne teče. Izjema je preskok z reason (customer_purchased, unsubscribed): ta zahteva neaktiven stik pending v nalogi draft ali pending/failed v paused, brez neporavnanega klica.
• task_not_deletable - Izbrisati je mogoče samo nalogo brez elementa in_progress v stanju draft/ready/paused/completed/needs_attention.
• revision_conflict - Naloga se je medtem spremenila - ponovno jo naložite (GET) in ponovite z aktualno revision.

Celotno tabelo napak za vsako končno točko najdete v razdelku Naloge v referenci REST API.