Vodiči

Zadaci

Zadatak jednim agentom poziva popis primatelja prema pravilima koja unaprijed postavite - proračun, vrijeme pozivanja, broj pokušaja. Ništa se ne poziva dok sami ne pokrenete zadatak.

Što je zadatak

Zadatak (task_...) je odlazna kampanja: jedan agent na pogonu volai, popis primatelja s telefonskim brojem i neobveznim varijablama za sistemski prompt te pravila (proračun, vrijeme pozivanja, najveći broj pokušaja i trajanje poziva). Tri vrste prema svrsi - invoice (podsjetnik na plaćanje), appointment (potvrda termina) i custom (sve ostalo) - kod prve dvije, kad je source jednak integration, svaki primatelj nosi referencu na račun ili događaj (externalRefs) koju agent spominje u pozivu.

Stanja i prijelazi

U praksi zadatak uvijek ide iz `draft` izravno u `running` (`start`); brisati (`DELETE`) se može samo u označenim stanjima.

Točan uvjet za brisanje: stanje je jedno od gore označenih I NIJEDNA stavka nema status: "in_progress" (poziv u tijeku koji još nije završio) - inače task_not_deletable.

Uvoz primatelja (CSV)

POST /v1/tasks/csv-preview obrađuje CSV i vraća ga natrag s pogreškama po pojedinim recima - NIŠTA se ne sprema, riječ je samo o pregledu prije otvaranja ili uređivanja zadatka. Istu funkciju poziva i obrazac za novi zadatak u portalu.

• Razdjelnik se prepoznaje automatski (zarez ili točka sa zarezom) prema prvom retku.
• Mora postojati stupac phone - velika i mala slova, razmaci oko naziva ni dvotočka iza njega nisu važni, a prolazi i telefon, tel ili mobil; u pregledu se stupac uvijek vraća kao phone. Prolazi i sam popis brojeva bez zaglavlja (jedan po retku, jedini stupac). Inače cijeli CSV pada na jednu pogrešku phone uz zaglavlje.
• Svaki daljnji stupac je varijabla za sistemski prompt agenta ({{column_name}}) - najviše 20 stupaca, naziv najviše 64 znaka, vrijednost najviše 512 znakova.
• Telefonski broj normalizira se jednako kao posvuda u API-ju (normalizePhone) - neispravan ili prazan broj pogreška je samo u TOM retku, ostatak CSV-a obrađuje se dalje.
• Ćelija koja izgleda kao formula proračunske tablice (počinje s =, +, - ili @) odbija se - zaštita od CSV injectiona pri otvaranju u Excelu.
• Najviše 1000 redaka po jednom CSV-u (ista gornja granica kao broj primatelja zadatka) i 1 MB sirovog teksta; cijeli zadatak s podlogama mora stati u 2 MB, inače otvaranje vraća validation.

Odgovor nosi headers, delimiter, rows (svaki redak sa svojim pogreškama), validRows (samo besprijekorne, točno u obliku koji recipients u POST /v1/tasks očekuje) i zbirne errors. Pošaljite validRows izravno kao recipients pri otvaranju ili uređivanju zadatka.

Proračun i vrijeme pozivanja

Proračun

budgetHal je GORNJA GRANICA potrošnje u lipama (stotinkama) za cijeli zadatak. Pri otvaranju mora pokriti barem jedan pokušaj u najvećoj duljini (budget_too_low, inače); pri pokretanju se prije SVAKOG biranja rezervira najveća moguća cijena pokušaja (reservedBudgetHal), a tek podignut poziv se prenosi u spentHal. Rezervacija je cijena poziva točno u duljini maxDurationSecs (krak poziva i krak agenta, svaki zaokružen naviše na stotinku kao pri obračunu), a poziv prekinut ograničenjem duljine obračunava se najviše za maxDurationSecs, čak i ako završi djelić sekunde kasnije. Zadatak nikada ne potroši više nego što mu date u budgetHal.

Vrijeme pozivanja

callingWindow je {timezone: "Europe/Prague", start, end, days} - danas je jedina podržana zona praška, start/end u obliku HH:MM (kraj uključuje cijelu minutu: prozor 09:00-18:00 pušta zadnji poziv u 18:00:59, prozor do 23:59 pokriva cijeli dan) i days brojevi 0-6 (0 = nedjelja). Bez navođenja vrijede radni dani 9:00-18:00. Izvan prozora start vraća window_closed - ili pričekajte otvaranje ili prozor izmijenite preko PATCH. Neobvezni expiresAt je kraj kampanje kao pozitivan sigurni cijeli broj u Unix milisekundama. Provjerava se pri pokretanju i prije svakog biranja, uključujući prvo. Od tog trenutka novi poziv ne počinje i pokušaj se ne troši; poziv u tijeku završava. Horizont ponavljanja politike lorela_enterprise (retryMaxAgeDays, zadano 5) naprotiv se računa kao N × 24 sata od prvog uračunatog pokušaja, a ne od otvaranja zadatka.

Pokušaji i trajanje poziva

maxAttempts je bez politike 1-3 (zadano 1), s retryPolicy: "lorela_enterprise" 1-4 (pri otvaranju zadano 4). Određuje najveći broj automatskih biranja jednog kontakta uključujući prvo (1 = bez ponavljanja). Računa se svaki pokušaj kod kojeg je poziv mogao proteći, dakle i nepodignut ili odbijen od pozvanog te pokušaj s nesigurnim ishodom. Ne računa se pokušaj koji je volai odbio još prije biranja (na primjer blokirani, vlastiti ili neispravni broj, popis zabranjenih brojeva, broj na koji upravo teče drugi poziv, ograničenja poziva); takav pokušaj ima items[].attempts[].countsAsAttempt: false. Ne računa se ni poziv kojemu operater nije na vrijeme dobio odredište pa telefon pozvanog uopće nije zazvonio (pokušaj ima errorCode: "relay_not_routed", poziv endReason: "rejected"): kontakt dobiva novi pokušaj najranije za minutu (s politikom lorela_enterprise prema njezinu rasporedu), a nakon trećeg takvog pokušaja zaredom ide na provjeru s reviewReason: "call:relay_not_routed". Ne računa se ni poziv o kojem naš glasovni pogon nikada nije javio i koji smo nakon dva sata bez poruke zatvorili kao nepozvan i bez cijene (pokušaj ima errorCode: "no_provider_report"): kontakt se vraća među one na čekanju i dobiva novi pokušaj najranije za minutu (s politikom lorela_enterprise prema njezinu rasporedu). Tri neračunata pokušaja zaredom, i pomiješana s pokušajima relay_not_routed, šalju kontakt na provjeru s reviewReason prema zadnjem od njih, dakle call:no_provider_report; kontakti koje je takav poziv ranije poslao na provjeru (call:failed, s politikom call:unknown) sami se ne obnavljaju. Bez politike gornja granica vrijedi samo za automatska biranja: kontakt kojem nakon iscrpljenih pokušaja date resolve s action: "retry" dobiva još jedno biranje povrh toga. maxDurationSecs (30-300) je gornja granica trajanja JEDNOG poziva nakon koje se automatski prekida - zadano trajanje je 120 sekundi. Neobvezna politika lorela_enterprise uključuje se preko API-ja ili MCP-a prije prvog pokušaja; postojeći zadaci sami se ne mijenjaju. Drugi pokušaj je najranije 8 minuta od početka prvog stvarnog pokušaja u vremenu 08:00-22:00 Europe/Prague. Treći ide u sljedeći drugi prozor 08:00-09:00 ili 17:00-19:00, četvrti u suprotni prozor sljedećeg kalendarskog dana. Uvijek vrijede i callingWindow i njegovi dani; nakon horizonta ponavljanja politika više ne poziva: neobvezni retryMaxAgeDays je cijeli broj dana 1-30 (bez navođenja 5) i vrijedi samo s politikom. Horizont završava N × 24 sata od prvog uračunatog pokušaja kontakta (čvrsti 24-satni dani, pa se pri promjeni vremena lokalno vrijeme završetka pomiče za sat). Može se mijenjati preko PATCH i nakon početka pokušaja (ne kod zadatka running ili completed, njega nije moguće urediti): povećanje kod pauziranog zadatka vraća kontakte koji su otpali samo zbog horizonta (reviewReason: "retry_age_expired") natrag u stanje failed (čekaju sljedeći pokušaj) s novim nextAttemptAt, ako još imaju slobodan pokušaj i najbliži termin rasporeda pada u novi horizont i prije expiresAt; smanjenje ništa ne otvara. Ponovno otvara samo PATCH koji horizont povećava, zato retryMaxAgeDays i produljeni expiresAt šaljite u jednom zahtjevu. Ponavlja samo no_answer, missed, busy, dovršenu govornu poštu i podignut poziv u kojem pozvani ništa nije rekao (sve bez kontakta s čovjekom). Kontakt s čovjekom, odbijanje i pogreška pogona zaustavljaju automatsko ponavljanje; nejasan ishod ide na provjeru. Zadnji dopušteni pokušaj (maxAttempts) koji završi takvim ponovljivim ishodom (nepodignuto, zauzeto, govorna pošta ili podignut poziv u kojem pozvani ništa nije rekao) zatvara kontakt kao skipped s reviewReason: "retry_policy_exhausted" (kao retry_age_expired nakon isteka horizonta): nema se što provjeravati ni ponavljati. Nejasan ishod zadnjeg pokušaja ostaje u review s istim razlogom. Bez politike ništa se ne mijenja: zadnji nepodignuti pokušaj i dalje je review. Provjereni ljudski callback nakon iscrpljenih pokušaja prebacuje kontakt na completed. DNC, proračun i ograničenja ostaju na snazi: automatska blokada nakon 3 neuspjeha u 24 sata može zaustaviti i četvrti pokušaj. Kod PATCH bez maxAttempts ostaje dosadašnje ograničenje. S politikom ručni resolve s action: "retry" vraća pogrešku validation; dopušteni su samo njezini automatski planirani pokušaji. Iznimka je obnova dokazivo nepozvanog isteklog claima prije prvog stvarnog pokušaja: bez aktivnog workera, dispatch namjere, provider call ID-ja, rezervacije, cijene ili callbacka i samo s dokazanim odbijanjima prije biranja u povijesti. Obnova čuva povijest i gornje granice i vraća kontakt među one na čekanju u pauziranom zadatku; sama ne poziva. Podsjetnike na ovaj način nije moguće ponovno otvoriti. Ručno ponavljanje dakle ne zaobilazi četiri pokušaja, horizont ponavljanja ni završetak nakon kontakta s čovjekom.

Globalna propusnost

Postupak za agenta

Tipičan tijek, ovim redoslijedom:

1. Agent zadatka mora biti OBJAVLJEN, a objavljena verzija TESTIRANA (POST /v1/agents/{id}/draft/publish, zatim POST /v1/agents/{id}/simulate) - inače kasniji start vraća agent_not_ready.
2. Neobvezno POST /v1/tasks/csv-preview - provjerava CSV primatelja prije otvaranja zadatka.
3. POST /v1/tasks - otvara zadatak u stanju draft. Ništa se ne poziva.
4. GET /v1/tasks/{id} - pročitajte issues (dry-run validacija) i provjerite je li zadatak spreman za pokretanje.
5. Prema potrebi PATCH /v1/tasks/{id} - prilagodite pravila, UVIJEK s revision iz zadnjeg čitanja.
6. POST /v1/tasks/{id}/start - pokreće biranje. Svaki podignut poziv obračunava se odmah.
7. POST /v1/tasks/{id}/pause bilo kada tijekom rada, POST /v1/tasks/{id}/start ponovno nastavlja.
8. Nakon prekida (pauziranje usred poziva, istekli claim, poziv s još nepoznatom cijenom ili nesigurno biranje za koje je poziv pronađen) POST /v1/tasks/{id}/reconcile usklađuje stanje sa stvarnim pozivima; takav zadatak s poslom završava u paused, čak i ako neki kontakti čekaju u review, i može se ponovno pokrenuti preko start. Zadatak koji radi ni drugi razlog (variables_limit, neuspjela provjera računa ili kalendara, nesigurno biranje za koje poziv nije pronađen) reconcile ne mijenja; kontakte za provjeru riješite preko resolve.
9. Kontakt koji je završio na provjeri (items[].status: "review") riješite s POST /v1/tasks/{id}/items/{itemId}/resolve s action: "retry" ili "skip". Kod uobičajenog razloga retry vraća kontakt među one na čekanju, a zadatak u paused; skip ga zatvara i zadatak prelazi u paused ako preostaje posla ili u completed ako su svi kontakti gotovi ili preskočeni. Zadatak u paused zatim nastavite s POST /v1/tasks/{id}/start.
10. Kad kontakt ima reviewReason: "dial:destination_auto_blocked", broj je 30 dana automatski blokiran nakon više puta nepodignutih poziva, a sam retry ga ne deblokira - kontakt bi se odmah vratio u review. Prvo ukinite blokadu (POST /v1/dnc/{e164}/unblock, u MCP-u unblock_destination, broj uzmite iz items[].phone), zatim resolve s action: "retry". Kod dial:on_dnc prvo uklonite broj s popisa zabranjenih brojeva (DELETE /v1/dnc/{e164}), inače kontakt preskočite. Kod vlastitog broja računa, broja drugog računa volai, neispravnog broja, broja izvan Češke i Slovačke te premium linije (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) novi pokušaj ne pomaže: koristite samo skip.
11. Kad kontakt ima reviewReason: "billing_unknown", izvorni je poziv već mogao proteći, samo još nema poznatu cijenu. Prvo pozovite reconcile i provjerite povezani poziv. retry pamti da kontakt treba ponovno pokušati, ali novi poziv ne dopušta dok se izvorna cijena ne ustali; nakon toga zadatak prelazi u paused i traži novi start. skip sprječava daljnji poziv; izvorni poziv ostaje povezan i njegova se rezervacija i dalje računa u proračun dok se cijena ne ustali. Ako preostaje posla, zadatak nakon skip prelazi odmah u paused i može se pokrenuti; bez daljnjeg posla čeka u needs_attention i nakon ustaljivanja cijene završava u completed. Poziv koji uopće nije biran (pogon ga je odbio) nikada se ne obračunava i ustaljuje se odmah na 0.
12. Kontakt koji je u međuvremenu kupio ili se odjavio preskočite bez poziva preko resolve s action: "skip", reason: "customer_purchased" ili "unsubscribed", revision, stalnim operationId i evidenceRef koji upućuje na dokaz kupnje ili odjave (nikada na telefon ni e-poštu). To je moguće kod pending kontakta u draft zadatku i kod pending/failed u paused zadatku bez neizmirenog poziva; pokušaji, cijene i popis zabranjenih brojeva ostaju. GET /v1/tasks/{id} zatim prikazuje dokaz u items[].resolution (reason, operationId, evidenceRef, resolvedAt); isto tijelo može se sigurno ponoviti, drugi reason ili evidenceRef kod istog kontakta je 409 revision_conflict. Preskakanje ne upisuje broj na popis zabranjenih brojeva: ako se kontakt više nikada ne smije zvati, dodajte ga preko POST /v1/dnc.
13. DELETE /v1/tasks/{id} na kraju, ako zadatak nikada nije proveden ili je već završio, a želite izbrisati zapis.

Gotovo svaki poziv koji piše (PATCH, start, pause, DELETE) uzima revision iz zadnjeg čitanja zadatka - ista optimistična istodobnost kao kod skica agenta. Nepodudarnost vraća revision_conflict: ponovno učitajte zadatak (GET) i ponovite s aktualnim revision. reconcile je iznimka - revision je tamo neobvezan.

MCP

Isti alati kao REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - osim jedne razlike kod pokretanja.

start_task potvrđuje brojeve

MCP start_task uz to uzima confirmedRecipients i confirmedBudgetHal - moraju se točno podudarati sa stvarnim brojem primatelja i proračunom zadatka, inače vraća validation s ispisanim stvarnim vrijednostima i NIŠTA ne pokreće. Tuđi AI agent tako na jednoj nejasno shvaćenoj uputi ne može slučajno pokrenuti plaćenu kampanju na izmišljenim brojevima - REST POST .../start nema taj mehanizam jer tamo izravno poziva vlasnik računa vlastitim ključem.

delete_task i pregled CSV-a u MCP-u ne postoje - brisanje ostaje u REST-u i portalu (nepovratna radnja s prepisivanjem naziva), pregled CSV-a samo je korak obrasca.

Pogreške

• task_not_found - Na računu nema zadatka s ovim id-jem.
• task_not_editable - Zadatak radi ili je gotov (running/completed) ili je needs_attention bez mogućnosti obnove - pravila se sada ne mogu mijenjati. Isti kod vraća i POST .../items/{itemId}/resolve kod zadatka koji radi: kontakt u review pojavljuje se već kad zadatak zove ostale kontakte i još je running - pričekajte da prijeđe u needs_attention ili ga pauzirajte (POST .../pause).
• items_immutable - Popis primatelja ne može se zamijeniti nakon što je barem jedan pokušaj biranja obavljen ili je kontakt preskočen s reason (kupnja ili odjava).
• budget_too_low - Proračun ne pokriva ni jedan pokušaj u najvećoj duljini poziva - povećajte budgetHal ili smanjite maxDurationSecs.
• task_not_startable - Zadatak nije u stanju draft/ready/paused ili nema nijednog primatelja na čekanju.
• task_needs_attention - Prije sljedećeg pokretanja potreban je POST .../reconcile - nešto (verzija agenta, pogon) promijenilo se tijekom rada.
• agent_not_ready - Skica agenta ili nije objavljena ili objavljena verzija nije testirana - objavite je (POST /v1/agents/{id}/draft/publish), a zatim prije pokretanja testirajte objavljenu verziju (POST /v1/agents/{id}/simulate).
• agent_version_changed - Konfiguracija agenta promijenila se TIJEKOM zadatka koji radi - testirajte i ponovno pokrenite preko reconcile.
• engine_required - Agent zadatka nije na pogonu volai (useForOutboundTasks: true) - odlazne kampanje danas zahtijevaju pogon, a ne ElevenLabs.
• engine_contract_unavailable - Pogon trenutačno ne oglašava podršku za varijable i gornje granice odlaznih zadataka - pokušajte ponovno pokrenuti kasnije.
• window_closed - Izvan postavljenog vremena pozivanja - pričekajte otvaranje ili izmijenite callingWindow.
• task_not_running - Pauza je moguća samo kod zadatka koji radi.
• item_not_resolvable - Kontakt nije u stanju review - odlučiti (retry/skip) može se samo o kontaktu koji čeka provjeru, i to samo kod zadatka koji ne radi. Iznimka je preskakanje s reason (customer_purchased, unsubscribed): ono traži neaktivan pending kontakt u draft zadatku ili pending/failed u paused, bez neizmirenog poziva.
• task_not_deletable - Brisati se može samo zadatak bez stavke in_progress u stanju draft/ready/paused/completed/needs_attention.
• revision_conflict - Zadatak se u međuvremenu promijenio - ponovno ga učitajte (GET) i ponovite s aktualnim revision.

Potpunu tablicu pogrešaka za svaki endpoint pronaći ćete u odjeljku Zadaci u referenci REST API-ja.