Pamācības

Uzdevumi

Uzdevums ar vienu aģentu sazvana adresātu sarakstu pēc noteikumiem, ko iestatāt iepriekš - budžets, zvanu logs, mēģinājumu skaits. Nekas netiek zvanīts, kamēr uzdevumu paši nepalaižat.

Kas ir uzdevums

Uzdevums (task_...) ir izejoša kampaņa: viens aģents uz volai dzinēja, adresātu saraksts ar tālruņa numuru un neobligātiem mainīgajiem sistēmas uzvednei, un noteikumi (budžets, zvanu logs, maksimālais mēģinājumu skaits un zvana garums). Trīs veidi pēc nolūka - invoice (maksājuma atgādinājums), appointment (laika apstiprinājums) un custom (jebkas cits) - pirmajiem diviem papildus, ja source ir integration, katram adresātam ir atsauce uz dokumentu vai notikumu (externalRefs), ko aģents zvana laikā piemin.

Statusi un pārejas

Praksē uzdevums vienmēr iet no `draft` uzreiz uz `running` (`start`); dzēst (`DELETE`) var tikai atzīmētajos statusos.

Precīzs dzēšanas nosacījums: statuss ir viens no iepriekš atzīmētajiem UN NEVIENAI pozīcijai nav status: "in_progress" (sāktais zvans, kas vēl nav beidzies) - citādi task_not_deletable.

Adresātu imports (CSV)

POST /v1/tasks/csv-preview izanalizē CSV un atgriež to atpakaļ ar kļūdām pie atsevišķām rindām - NEKAS netiek saglabāts, tas ir tikai priekšskatījums pirms uzdevuma izveides vai labošanas. To pašu funkciju izsauc arī jaunā uzdevuma veidlapa portālā.

• Atdalītājs tiek atpazīts automātiski (komats vai semikols) pēc pirmās rindas.
• Jābūt kolonnai phone - burtu reģistrs, atstarpes ap nosaukumu un kols aiz tā nav svarīgi, un derēs arī telefon, tel vai mobil; priekšskatījumā kolonna vienmēr tiek atgriezta kā phone. Derēs arī tīrs numuru saraksts bez galvenes (viens rindā, viena kolonna). Citādi viss CSV neiztur ar vienu kļūdu phone pie galvenes.
• Katra nākamā kolonna ir mainīgais aģenta sistēmas uzvednei ({{column_name}}) - ne vairāk kā 20 kolonnas, nosaukums līdz 64 rakstzīmēm, vērtība līdz 512 rakstzīmēm.
• Tālruņa numurs tiek normalizēts tāpat kā visur API (normalizePhone) - nederīgs vai tukšs numurs ir kļūda tikai UZ ŠĪS rindas, pārējais CSV tiek apstrādāts tālāk.
• Šūna, kas izskatās pēc izklājlapas formulas (sākas ar =, +, - vai @), tiek noraidīta - aizsardzība pret CSV injekciju atverot Excel.
• Ne vairāk kā 1000 rindu uz vienu CSV (tādi paši griesti kā uzdevuma adresātu skaitam) un 1 MB neapstrādāta teksta; viss uzdevums kopā ar pielikumiem jāiegulda 2 MB, citādi izveide atgriež validation.

Atbilde satur headers, delimiter, rows (katra rinda ar savām kļūdām), validRows (tikai nevainojamās, tieši tādā formā, kādu recipients gaida POST /v1/tasks) un kopsavilkuma errors. Sūtiet validRows uzreiz kā recipients uzdevuma izveides vai labošanas laikā.

Budžets un zvanu logs

Budžets

budgetHal ir izdevumu GRIESTI haléros par visu uzdevumu. Izveides brīdī tam jāsedz vismaz viens mēģinājums maksimālajā garumā (budget_too_low, citādi); startā pirms KATRA sazvana tiek rezervēta augstākā iespējamā mēģinājuma cena (reservedBudgetHal), un tikai pacelts zvans to pārnes uz spentHal. Rezervācija ir zvana cena tieši maxDurationSecs garumā (zvana kājas un aģenta kājas, katra noapaļota uz augšu līdz halérim tāpat kā rēķinot) un zvans, ko pārtrauc garuma griesti, tiek rēķināts ne vairāk kā par maxDurationSecs, pat ja beidzas sekundes daļu vēlāk. Uzdevums nekad neiztērēs vairāk, nekā budgetHal norādāt.

Zvanu logs

callingWindow ir {timezone: "Europe/Prague", start, end, days} - šodien vienīgā atbalstītā josla ir Prāgas, start/end formātā HH:MM (beigas ieskaitot visu minūti: logs 09:00-18:00 ielaiž pēdējo zvanu 18:00:59, logs līdz 23:59 aptver visu dienu) un days ir skaitļi 0-6 (0 = svētdiena). Bez norādes spēkā ir darbdienas 9:00-18:00. Ārpus loga start atgriež window_closed - vai nu gaidiet atvēršanos, vai logu izlabojiet ar PATCH. Neobligātais expiresAt ir kampaņas beigas kā pozitīvs drošs vesels skaitlis Unix milisekundēs. Tas tiek pārbaudīts startā un pirms katra sazvana, ieskaitot pirmo. Kopš šī brīža jauns zvans nesākas un mēģinājums netiek izlietots; notiekošais zvans tiek pabeigts. Politikas lorela_enterprise atkārtošanas horizonts (retryMaxAgeDays, noklusējumā 5), gluži otrādi, tiek skaitīts kā N × 24 stundas no pirmā ieskaitītā mēģinājuma, nevis no uzdevuma izveides.

Mēģinājumi un zvana garums

maxAttempts bez politikas ir 1-3 (noklusējumā 1), ar retryPolicy: "lorela_enterprise" 1-4 (izveidojot noklusējumā 4). Tas nosaka augstāko automātisko sazvanu skaitu vienam kontaktam, ieskaitot pirmo (1 = bez atkārtojumiem). Tiek skaitīts katrs mēģinājums, kurā zvans varēja notikt, tātad arī nepacelts vai zvanītā noraidīts, un mēģinājums ar nenoteiktu rezultātu. Netiek skaitīts mēģinājums, ko volai noraidīja jau pirms sazvana (piemēram, bloķēts, paša vai nederīgs numurs, nezvanīšanas saraksts, numurs, uz kuru tobrīd notiek cits zvans, zvanu limiti); šādam mēģinājumam ir items[].attempts[].countsAsAttempt: false. Netiek skaitīts arī zvans, kam operators laikus nesaņēma mērķi, tāpēc zvanītā tālrunis vispār nezvanīja (mēģinājumam ir errorCode: "relay_not_routed", zvanam endReason: "rejected"): kontakts saņem jaunu mēģinājumu ne agrāk kā pēc minūtes (ar politiku lorela_enterprise pēc tās grafika) un pēc trešā šāda mēģinājuma pēc kārtas nonāk pārbaudē ar reviewReason: "call:relay_not_routed". Netiek skaitīts arī zvans, par kuru mūsu balss dzinējs nekad nedeva ziņu un kuru pēc divām stundām bez ziņojuma slēdzām kā nesazvanītu un bez cenas (mēģinājumam ir errorCode: "no_provider_report"): kontakts atgriežas gaidošo vidū un saņem jaunu mēģinājumu ne agrāk kā pēc minūtes (ar politiku lorela_enterprise pēc tās grafika). Trīs neskaitīti mēģinājumi pēc kārtas, arī sajaukti ar relay_not_routed mēģinājumiem, nosūta kontaktu pārbaudē ar reviewReason pēc pēdējā no tiem, tātad call:no_provider_report; kontakti, kurus šāds zvans pārbaudē nosūtīja agrāk (call:failed, ar politiku call:unknown), paši neatjaunojas. Bez politikas griesti attiecas tikai uz automātiskajiem sazvaniem: kontaktam, kuram pēc mēģinājumu izsmelšanas piemērojat resolve ar action: "retry", tiek dots vēl viens papildu sazvans. maxDurationSecs (30-300) ir VIENA zvana garuma griesti, pēc kuriem tas tiek automātiski pārtraukts - noklusējuma garums ir 120 sekundes. Neobligāto politiku lorela_enterprise ieslēdz ar API vai MCP pirms pirmā mēģinājuma; esošie uzdevumi paši nemainās. Otrais mēģinājums ir ne agrāk kā 8 minūtes no pirmā faktiskā mēģinājuma sākuma laikā 08:00-22:00 Europe/Prague. Trešais iet nākamajā citā logā 08:00-09:00 vai 17:00-19:00, ceturtais pretējā logā nākamajā kalendārajā dienā. Vienmēr ir spēkā arī callingWindow un tā dienas; pēc atkārtošanas horizonta politika vairs nezvana: neobligātais retryMaxAgeDays ir vesels dienu skaitlis 1-30 (bez norādes 5) un darbojas tikai ar politiku. Horizonts beidzas N × 24 stundas pēc kontakta pirmā ieskaitītā mēģinājuma (fiksētas 24 stundu dienas, tāpēc laika maiņas gadījumā beigu vietējais laiks nobīdās par stundu). To var mainīt ar PATCH arī pēc mēģinājumu sākuma (ne uzdevumam running vai completed, to labot nevar): palielinājums pauzētam uzdevumam atgriež kontaktus, kas izkrita tikai horizonta dēļ (reviewReason: "retry_age_expired"), atpakaļ statusā failed (gaida nākamo mēģinājumu) ar jaunu nextAttemptAt, ja tiem vēl ir brīvs mēģinājums un tuvākais grafika slots iekrīt jaunajā horizontā un pirms expiresAt; samazinājums neko neatver. Atkal atver tikai PATCH, kas horizontu palielina, tāpēc retryMaxAgeDays un pagarināto expiresAt sūtiet vienā pieprasījumā. Atkārto tikai no_answer, missed, busy, pabeigtu balss pastu un pacelta zvana, kurā zvanītais neko neteica (viss bez kontakta ar cilvēku). Kontakts ar cilvēku, noraidījums un dzinēja kļūda automātisko atkārtošanu aptur; neskaidrs rezultāts iet pārbaudē. Pēdējais atļautais mēģinājums (maxAttempts), kas beidzas ar šādu atkārtojamu rezultātu (nepacelts, aizņemts, balss pasts vai pacelts zvans, kurā zvanītais neko neteica), kontaktu slēdz kā skipped ar reviewReason: "retry_policy_exhausted" (kā retry_age_expired pēc horizonta beigām): nav ko pārbaudīt vai atkārtot. Neskaidrs pēdējā mēģinājuma rezultāts paliek review ar to pašu iemeslu. Bez politikas nekas nemainās: pēdējais nepacelts mēģinājums joprojām ir review. Apstiprināts cilvēka atzvans pēc mēģinājumu izsmelšanas kontaktu pārslēdz uz completed. DNC, budžets un limiti paliek spēkā: automātiska bloķēšana pēc 3 neveiksmēm 24 stundās var apturēt pat ceturto mēģinājumu. PATCH bez maxAttempts līdzšinējais limits saglabājas. Ar politiku manuāls resolve ar action: "retry" atgriež kļūdu validation; atļauti ir tikai tās automātiski ieplānotie mēģinājumi. Izņēmums ir pierādāmi nesazvanīta izbeigta claim atjaunošana pirms pirmā faktiskā mēģinājuma: bez aktīva darbinieka, dispatch nodoma, nodrošinātāja zvana ID, rezervācijas, cenas vai callback un tikai ar pierādītiem noraidījumiem pirms sazvana vēsturē. Atjaunošana saglabā vēsturi un griestus un atgriež kontaktu gaidošo vidū pauzētā uzdevumā; pati nezvana. Atgādinājumus šādi atkārtoti atvērt nevar. Manuāls atkārtojums tātad neapiet četrus mēģinājumus, atkārtošanas horizontu vai pārtraukšanu pēc kontakta ar cilvēku.

Globālā caurlaidspēja

Darbību secība aģentam

Tipiska norise šādā secībā:

1. Uzdevuma aģentam jābūt PUBLICĒTAM un publicētajai versijai IZMĒĢINĀTAI (POST /v1/agents/{id}/draft/publish, tad POST /v1/agents/{id}/simulate) - citādi vēlāks start atgriež agent_not_ready.
2. Pēc izvēles POST /v1/tasks/csv-preview - pārbauda adresātu CSV, pirms tiek izveidots uzdevums.
3. POST /v1/tasks - izveido uzdevumu statusā draft. Nekas netiek zvanīts.
4. GET /v1/tasks/{id} - izlasiet issues (dry-run validācija) un pārliecinieties, ka uzdevums ir gatavs startam.
5. Pēc vajadzības PATCH /v1/tasks/{id} - labojiet noteikumus, VIENMĒR ar revision no pēdējās nolasīšanas.
6. POST /v1/tasks/{id}/start - sāk zvanīšanu. Katrs pacelts zvans tiek rēķināts uzreiz.
7. POST /v1/tasks/{id}/pause jebkurā brīdī darbības laikā, POST /v1/tasks/{id}/start atkal atjauno.
8. Pēc pārtraukuma (pauze zvana vidū, izbeidzies claim, zvans ar vēl nezināmu cenu vai nenoteikts sazvans, pie kura zvans tika atrasts) POST /v1/tasks/{id}/reconcile saskaņo stāvokli ar faktiskajiem zvaniem; šāds uzdevums ar darbu beidzas paused, pat ja daži kontakti gaida review, un to var atkal palaist ar start. Notiekošu uzdevumu vai citu iemeslu (variables_limit, rēķina vai kalendāra pārbaudes neveiksme, nenoteikts sazvans, pie kura zvanu neizdevās atrast) reconcile nemaina; kontaktus pārbaudei atrisiniet ar resolve.
9. Kontaktu, kas nonāca pārbaudē (items[].status: "review"), atrisiniet ar POST /v1/tasks/{id}/items/{itemId}/resolve ar action: "retry" vai "skip". Parasta iemesla gadījumā retry atgriež kontaktu gaidošo vidū un uzdevumu uz paused; skip to slēdz un uzdevums pāriet uz paused, ja darbs vēl ir atlicis, vai uz completed, ja visi kontakti ir pabeigti vai izlaisti. Uzdevumu paused pēc tam atjaunojiet ar POST /v1/tasks/{id}/start.
10. Ja kontaktam ir reviewReason: "dial:destination_auto_blocked", numurs ir automātiski bloķēts uz 30 dienām pēc atkārtoti nepacelta zvana un pats retry to neatbloķē - kontakts uzreiz atgrieztos review. Vispirms atceliet bloķēšanu (POST /v1/dnc/{e164}/unblock, MCP unblock_destination, numuru ņemiet no items[].phone), pēc tam resolve ar action: "retry". Pie dial:on_dnc vispirms izņemiet numuru no nezvanīšanas saraksta (DELETE /v1/dnc/{e164}), citādi kontaktu izlaidiet. Konta paša numuram, cita volai konta numuram, nederīgam numuram, numuram ārpus Čehijas un Slovākijas un maksas līnijai (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) nākamais mēģinājums nelīdz: izmantojiet tikai skip.
11. Ja kontaktam ir reviewReason: "billing_unknown", sākotnējais zvans jau varēja notikt, tikai tā cena vēl nav zināma. Vispirms izsauciet reconcile un pārbaudiet saistīto zvanu. retry iegaumē, ka kontaktu jāmēģina vēlreiz, bet jaunu zvanu neatļauj, kamēr sākotnējā cena nav nostabilizējusies; pēc tam uzdevums pāriet uz paused un prasa jaunu start. skip novērš nākamo zvanu; sākotnējais zvans paliek saistīts un tā rezervācija turpina ieskaitīties budžetā, līdz cena nostabilizējas. Ja darbs ir atlicis, uzdevums pēc skip pāriet uzreiz uz paused un to var palaist; bez cita darba tas gaidīs needs_attention un pēc cenas nostabilizēšanās beigsies completed. Zvans, kas vispār netika sazvanīts (dzinējs to noraidīja), nekad netiek rēķināts un nostabilizējas uzreiz uz 0.
12. Kontaktu, kas pa to laiku nopirka vai atrakstījās, izlaidiet bez zvana ar resolve ar action: "skip", reason: "customer_purchased" vai "unsubscribed", revision, stabilu operationId un evidenceRef, kas norāda uz pirkuma vai atrakstīšanās dokumentu (nekad uz tālruni vai e-pastu). To var darīt ar pending kontaktu draft uzdevumā un ar pending/failed paused uzdevumā bez neizskaidrota zvana; mēģinājumi, cenas un nezvanīšanas saraksts paliek. GET /v1/tasks/{id} pēc tam parāda dokumentu items[].resolution (reason, operationId, evidenceRef, resolvedAt); to pašu pieprasījuma pamattekstu var droši atkārtot, cits reason vai evidenceRef tam pašam kontaktam ir 409 revision_conflict. Izlaišana numuru nezvanīšanas sarakstā neieraksta: ja kontaktu vairs nekad nedrīkst zvanīt, pievienojiet to ar POST /v1/dnc.
13. DELETE /v1/tasks/{id} beigās, ja uzdevums nekad nav norisinājies vai jau ir beidzies un ierakstu vēlaties izdzēst.

Gandrīz katrs rakstošais izsaukums (PATCH, start, pause, DELETE) ņem revision no uzdevuma pēdējās nolasīšanas - tāda pati optimistiskā vienlaicība kā aģenta melnrakstiem. Neatbilstība atgriež revision_conflict: ielādējiet uzdevumu vēlreiz (GET) un atkārtojiet ar aktuālo revision. reconcile ir izņēmums - revision tur nav obligāts.

MCP

Tie paši rīki kā REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - izņemot vienu atšķirību startā.

start_task apstiprina skaitļus

MCP start_task papildus ņem confirmedRecipients un confirmedBudgetHal - tiem precīzi jāatbilst uzdevuma faktiskajam adresātu skaitam un budžetam, citādi tas atgriež validation ar izrakstītajām faktiskajām vērtībām un NEKO nepalaiž. Svešs AI aģents uz viena neskaidri saprasta norādījuma tādējādi nevar kļūdaini palaist maksas kampaņu ar izdomātiem skaitļiem - REST POST .../start šādas mehānikas nav, jo tur tieši ar savu atslēgu zvana konta īpašnieks.

delete_task un CSV priekšskatījuma MCP nav - dzēšana paliek REST un portālā (neatgriezeniska darbība ar nosaukuma pārrakstīšanu), CSV priekšskatījums ir tikai veidlapas solis.

Kļūdas

• task_not_found - Kontā nav uzdevuma ar šādu id.
• task_not_editable - Uzdevums darbojas vai ir pabeigts (running/completed), vai ir needs_attention bez atjaunošanas iespējas - noteikumus tagad mainīt nevar. To pašu kodu atgriež arī POST .../items/{itemId}/resolve darbojošam uzdevumam: kontakts review parādās jau tad, kad uzdevums zvana pārējiem kontaktiem un vēl ir running - uzgaidiet, līdz tas pāriet uz needs_attention, vai to apturiet (POST .../pause).
• items_immutable - Adresātu sarakstu nevar aizstāt pēc tam, kad ir noticis vismaz viens sazvana mēģinājums vai kontakts ir izlaists ar reason (pirkums vai atrakstīšanās).
• budget_too_low - Budžets nesedz pat vienu mēģinājumu maksimālajā zvana garumā - palieliniet budgetHal vai samaziniet maxDurationSecs.
• task_not_startable - Uzdevums nav statusā draft/ready/paused vai tam nav neviena gaidoša adresāta.
• task_needs_attention - Pirms nākamā starta nepieciešams POST .../reconcile - kaut kas (aģenta versija, dzinējs) darbības laikā ir mainījies.
• agent_not_ready - Aģenta melnraksts vai nav publicēts, vai publicētā versija nav izmēģināta - publicējiet to (POST /v1/agents/{id}/draft/publish) un pēc tam izmēģiniet publicēto versiju (POST /v1/agents/{id}/simulate) pirms starta.
• agent_version_changed - Aģenta konfigurācija mainījās UZDEVUMA DARBĪBAS LAIKĀ - izmēģiniet un restartējiet ar reconcile.
• engine_required - Uzdevuma aģents nav uz volai dzinēja (useForOutboundTasks: true) - izejošās kampaņas šodien prasa dzinēju, nevis ElevenLabs.
• engine_contract_unavailable - Dzinējs pašlaik nepiedāvā atbalstu mainīgajiem un izejošo uzdevumu griestiem - mēģiniet startu vēlāk vēlreiz.
• window_closed - Ārpus iestatītā zvanu loga - uzgaidiet atvēršanos vai labojiet callingWindow.
• task_not_running - Pauze iespējama tikai darbojošam uzdevumam.
• item_not_resolvable - Kontakts nav statusā review - izlemt (retry/skip) var tikai par kontaktu, kas gaida pārbaudi, un tikai uzdevumā, kas nedarbojas. Izņēmums ir izlaišana ar reason (customer_purchased, unsubscribed): tai nepieciešams neaktīvs pending kontakts draft uzdevumā vai pending/failed paused uzdevumā bez neizskaidrota zvana.
• task_not_deletable - Dzēst var tikai uzdevumu bez pozīcijas in_progress statusā draft/ready/paused/completed/needs_attention.
• revision_conflict - Uzdevums pa to laiku ir mainījies - ielādējiet to vēlreiz (GET) un atkārtojiet ar aktuālo revision.

Pilnu kļūdu tabulu katram galapunktam atradīsiet sadaļā Uzdevumi REST API atsaucē.