Ghiduri

Sarcini

O sarcină sună o listă de destinatari cu un singur agent, după regulile pe care le stabiliți dinainte - buget, fereastră de apelare, număr de încercări. Nu se sună nimic până când nu porniți sarcina dumneavoastră.

Ce este o sarcină

O sarcină (task_...) este o campanie de apeluri efectuate: un agent pe motorul volai, o listă de destinatari cu număr de telefon și variabile opționale pentru promptul de sistem, plus regulile (buget, fereastră de apelare, număr maxim de încercări și durata apelului). Trei tipuri, după scop - invoice (reamintirea unei plăți), appointment (confirmarea unui termen) și custom (orice altceva) - iar la primele două, când source este integration, fiecare destinatar poartă o referință la document sau la eveniment (externalRefs), pe care agentul o menționează în apel.

Stări și tranziții

În practică, o sarcină trece întotdeauna din `draft` direct în `running` (`start`); ștergerea (`DELETE`) este posibilă doar în stările marcate.

Condiția exactă de ștergere: starea este una dintre cele marcate mai sus ȘI NICIUN element nu are status: "in_progress" (un apel în desfășurare care nu s-a încheiat încă) - altfel task_not_deletable.

Importul destinatarilor (CSV)

POST /v1/tasks/csv-preview analizează CSV-ul și îl returnează înapoi, cu erorile fiecărui rând - NU se salvează NIMIC, este doar o previzualizare înainte de crearea sau modificarea sarcinii. Aceeași funcție o apelează și formularul de sarcină nouă din portal.

• Separatorul se recunoaște automat (virgulă sau punct și virgulă) după primul rând.
• Trebuie să existe o coloană phone - majusculele, spațiile din jurul numelui și două puncte după el nu contează și trece și telefon, tel sau mobil; în previzualizare coloana este returnată întotdeauna ca phone. Trece și o simplă listă de numere fără antet (unul pe rând, o singură coloană). Altfel întregul CSV cade pe o singură eroare phone la antet.
• Fiecare altă coloană este o variabilă pentru promptul de sistem al agentului ({{column_name}}) - cel mult 20 de coloane, numele de maximum 64 de caractere, valoarea de maximum 512 caractere.
• Numărul de telefon se normalizează la fel ca peste tot în API (normalizePhone) - un număr invalid sau gol este o eroare doar pe ACEL rând, restul CSV-ului se procesează în continuare.
• O celulă care arată ca o formulă de foaie de calcul (începe cu =, +, - sau @) este respinsă - protecție împotriva CSV injection la deschiderea în Excel.
• Cel mult 1000 de rânduri pe un CSV (același plafon ca numărul de destinatari ai sarcinii) și 1 MB de text brut; întreaga sarcină, cu toate documentele, trebuie să încapă în 2 MB, altfel crearea returnează validation.

Răspunsul conține headers, delimiter, rows (fiecare rând cu erorile lui), validRows (doar cele fără erori, exact în forma pe care o așteaptă recipients din POST /v1/tasks) și errors sintetice. Trimiteți validRows direct ca recipients la crearea sau modificarea sarcinii.

Buget și fereastră de apelare

Buget

budgetHal este PLAFONUL de cheltuieli în bani (subunități) pentru întreaga sarcină. La creare trebuie să acopere cel puțin o încercare de durată maximă (altfel budget_too_low); la pornire, înainte de FIECARE apelare se rezervă cel mai mare preț posibil al încercării (reservedBudgetHal), iar abia un apel răspuns îl trece în spentHal. Rezerva este prețul apelului exact la durata maxDurationSecs (segmentul apelului și segmentul agentului, fiecare rotunjit în sus la cea mai mică subunitate, la fel ca la taxare), iar un apel încheiat de plafonul de durată se taxează cel mult pentru maxDurationSecs, chiar dacă se termină cu o fracțiune de secundă mai târziu. O sarcină nu cheltuiește niciodată mai mult decât îi acordați în budgetHal.

Fereastră de apelare

callingWindow este {timezone: "Europe/Prague", start, end, days} - azi singurul fus orar acceptat este cel al Pragăi, start/end în forma HH:MM (sfârșitul include minutul întreg: fereastra 09:00-18:00 lasă ultimul apel la 18:00:59, iar o fereastră până la 23:59 acoperă toată ziua) și days numere 0-6 (0 = duminică). Fără indicație se aplică zilele lucrătoare 9:00-18:00. În afara ferestrei, start returnează window_closed - fie așteptați deschiderea, fie modificați fereastra prin PATCH. expiresAt opțional este sfârșitul campaniei ca număr întreg pozitiv sigur, în milisecunde Unix. Se verifică la pornire și înainte de fiecare apelare, inclusiv prima. Din acel moment nu mai începe niciun apel nou și nicio încercare nu se consumă; apelul în desfășurare se încheie. Orizontul de repetare al politicii lorela_enterprise (retryMaxAgeDays, implicit 5) se numără, în schimb, ca N × 24 de ore de la prima încercare numărată, nu de la crearea sarcinii.

Încercări și durata apelului

maxAttempts este 1-3 fără politică (implicit 1), iar cu retryPolicy: "lorela_enterprise" 1-4 (implicit 4 la creare). Stabilește numărul maxim de apelări automate ale unui contact, inclusiv prima (1 = fără repetare). Se numără orice încercare la care apelul ar fi putut avea loc, deci și un apel fără răspuns sau respins de persoana apelată, precum și o încercare cu rezultat incert. Nu se numără o încercare pe care volai a respins-o înainte de apelare (de exemplu un număr blocat, propriu sau invalid, lista de neapelat, un număr pe care rulează chiar atunci alt apel, limitele de apeluri); o astfel de încercare are items[].attempts[].countsAsAttempt: false. Nu se numără nici un apel a cărui destinație nu a ajuns la timp la operator, astfel încât telefonul apelat nu a sunat deloc (încercarea are errorCode: "relay_not_routed", apelul endReason: "rejected"): contactul primește o nouă încercare cel mai devreme peste un minut (cu politica lorela_enterprise, după programul ei), iar după a treia astfel de încercare consecutivă merge la verificare cu reviewReason: "call:relay_not_routed". Nu se numără nici un apel despre care motorul nostru vocal nu a dat niciodată de știre și pe care, după două ore fără mesaj, l-am închis ca neapelat și fără preț (încercarea are errorCode: "no_provider_report"): contactul revine printre cele în așteptare și primește o nouă încercare cel mai devreme peste un minut (cu politica lorela_enterprise, după programul ei). Trei încercări nenumărate consecutive, chiar amestecate cu încercări relay_not_routed, trimit contactul la verificare cu reviewReason după ultima dintre ele, adică call:no_provider_report; contactele pe care un astfel de apel le-a trimis mai devreme la verificare (call:failed, cu politica call:unknown) nu se reiau singure. Fără politică, plafonul se aplică doar apelărilor automate: un contact căruia, după epuizarea încercărilor, îi dați resolve cu action: "retry" primește încă o apelare în plus. maxDurationSecs (30-300) este plafonul duratei UNUI apel, după care acesta se încheie automat - durata implicită este de 120 de secunde. Politica opțională lorela_enterprise se activează prin API sau MCP înainte de prima încercare; sarcinile existente nu se schimbă singure. A doua încercare este cel mai devreme la 8 minute de la începutul primei încercări reale, în intervalul 08:00-22:00 Europe/Prague. A treia merge în următoarea fereastră diferită, 08:00-09:00 sau 17:00-19:00, a patra în fereastra opusă din ziua calendaristică următoare. Se aplică întotdeauna și callingWindow cu zilele ei; după orizontul de repetare, politica nu mai sună: retryMaxAgeDays opțional este un număr întreg de zile 1-30 (fără indicație 5) și se aplică doar cu politica. Orizontul se încheie la N × 24 de ore de la prima încercare numărată a contactului (zile fixe de 24 de ore, deci peste schimbarea orei, ora locală a sfârșitului se mută cu o oră). Se poate modifica prin PATCH și după începerea încercărilor (nu la o sarcină running sau completed, aceea nu se poate modifica): creșterea la o sarcină pusă pe pauză readuce contactele care au căzut doar din cauza orizontului (reviewReason: "retry_age_expired") în starea failed (așteaptă o nouă încercare) cu un nou nextAttemptAt, dacă mai au o încercare liberă, iar cel mai apropiat slot al programului cade în noul orizont și înainte de expiresAt; o reducere nu redeschide nimic. Redeschide doar un PATCH care crește orizontul, de aceea trimiteți retryMaxAgeDays și expiresAt prelungit într-o singură cerere. Repetă doar no_answer, missed, busy, un robot telefonic finalizat și un apel răspuns în care persoana apelată nu a spus nimic (toate fără contact cu o persoană). Un contact cu o persoană, o respingere și o eroare a motorului opresc repetarea automată; un rezultat neclar merge la verificare. Ultima încercare permisă (maxAttempts) care se încheie cu un astfel de rezultat repetabil (fără răspuns, ocupat, robot telefonic sau un apel răspuns în care persoana apelată nu a spus nimic) închide contactul ca skipped cu reviewReason: "retry_policy_exhausted" (ca retry_age_expired după expirarea orizontului): nu mai este nimic de verificat sau de repetat. Un rezultat neclar al ultimei încercări rămâne în review cu același motiv. Fără politică nu se schimbă nimic: ultima încercare fără răspuns rămâne review. Un callback uman verificat după epuizarea încercărilor trece contactul în completed. DNC, bugetul și limitele rămân în vigoare: blocarea automată după 3 eșecuri în 24 de ore poate opri chiar și a patra încercare. La PATCH fără maxAttempts rămâne limita de până atunci. Cu politica, resolve manual cu action: "retry" returnează eroarea validation; sunt permise doar încercările ei planificate automat. Excepție este reluarea unui claim expirat, dovedit ca neapelat, înainte de prima încercare reală: fără worker activ, intenție de dispatch, ID de apel al furnizorului, rezervă, preț sau callback și doar cu respingeri dovedite înainte de apelare în istoric. Reluarea păstrează istoricul și plafoanele și readuce contactul printre cele în așteptare într-o sarcină pusă pe pauză; ea însăși nu sună. Reamintirile nu pot fi redeschise astfel. Repetarea manuală nu ocolește, așadar, cele patru încercări, orizontul de repetare și încheierea după contactul cu o persoană.

Debit global

Procedura pentru agent

Un parcurs tipic, în această ordine:

1. Agentul sarcinii trebuie să fie PUBLICAT, iar versiunea publicată TESTATĂ (POST /v1/agents/{id}/draft/publish, apoi POST /v1/agents/{id}/simulate) - altfel un start ulterior returnează agent_not_ready.
2. Opțional POST /v1/tasks/csv-preview - verifică CSV-ul destinatarilor înainte de crearea sarcinii.
3. POST /v1/tasks - creează sarcina în starea draft. Nu se sună nimic.
4. GET /v1/tasks/{id} - citiți issues (validare dry-run) și verificați că sarcina este pregătită de pornire.
5. După nevoie PATCH /v1/tasks/{id} - modificați regulile, ÎNTOTDEAUNA cu revision din ultima citire.
6. POST /v1/tasks/{id}/start - pornește apelarea. Fiecare apel răspuns se taxează imediat.
7. POST /v1/tasks/{id}/pause oricând în timpul rulării, POST /v1/tasks/{id}/start o reia din nou.
8. După o întrerupere (pauză în mijlocul unui apel, claim expirat, un apel cu preț încă necunoscut sau o apelare incertă pentru care apelul a fost găsit) POST /v1/tasks/{id}/reconcile aliniază starea cu apelurile reale; o astfel de sarcină cu muncă rămasă ajunge în paused, chiar dacă unele contacte așteaptă în review, și poate fi repornită prin start. O sarcină în rulare sau un alt motiv (variables_limit, eșecul verificării facturii sau al calendarului, o apelare incertă pentru care apelul nu a fost găsit) nu sunt modificate de reconcile; contactele de verificat le rezolvați prin resolve.
9. Un contact care a ajuns la verificare (items[].status: "review") îl rezolvați cu POST /v1/tasks/{id}/items/{itemId}/resolve cu action: "retry" sau "skip". La un motiv obișnuit, retry întoarce contactul printre cele în așteptare, iar sarcina în paused; skip îl închide, iar sarcina trece în paused dacă mai rămâne muncă, sau în completed dacă toate contactele sunt încheiate ori omise. Sarcina din paused o reluați apoi cu POST /v1/tasks/{id}/start.
10. Când un contact are reviewReason: "dial:destination_auto_blocked", numărul este blocat automat 30 de zile după apeluri repetate fără răspuns, iar un simplu retry nu îl deblochează - contactul ar reveni imediat în review. Mai întâi anulați blocarea (POST /v1/dnc/{e164}/unblock, în MCP unblock_destination, numărul îl luați din items[].phone), apoi resolve cu action: "retry". La dial:on_dnc scoateți mai întâi numărul din lista de neapelat (DELETE /v1/dnc/{e164}), altfel omiteți contactul. La numărul propriu al contului, numărul altui cont volai, un număr invalid, un număr din afara Cehiei și Slovaciei și o linie premium (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) o nouă încercare nu ajută: folosiți doar skip.
11. Când un contact are reviewReason: "billing_unknown", apelul inițial ar fi putut deja să aibă loc, doar că nu i se cunoaște încă prețul. Mai întâi apelați reconcile și verificați apelul asociat. retry reține că trebuie încercat din nou contactul, dar nu permite un apel nou până când prețul inițial nu se stabilizează; apoi sarcina trece în paused și necesită un nou start. skip împiedică un alt apel; apelul inițial rămâne asociat, iar rezerva lui continuă să se numere în buget până când prețul se stabilizează. Dacă mai rămâne muncă, după skip sarcina trece direct în paused și poate fi pornită; fără alte lucruri de făcut așteaptă în needs_attention și, după stabilizarea prețului, se încheie în completed. Un apel care nu a fost deloc apelat (motorul l-a respins) nu se taxează niciodată și se stabilizează imediat la 0.
12. Un contact care între timp a cumpărat sau s-a dezabonat îl omiteți fără apel prin resolve cu action: "skip", reason: "customer_purchased" sau "unsubscribed", revision, un operationId stabil și un evidenceRef care trimite la dovada cumpărării sau a dezabonării (niciodată la telefon ori e-mail). Se poate la un contact pending dintr-o sarcină draft și la pending/failed într-o sarcină paused fără apel nedecontat; încercările, prețurile și lista de neapelat rămân. GET /v1/tasks/{id} arată apoi dovada în items[].resolution (reason, operationId, evidenceRef, resolvedAt); același corp poate fi repetat în siguranță, un alt reason sau evidenceRef la același contact este 409 revision_conflict. Omiterea nu scrie numărul în lista de neapelat: dacă un contact nu mai trebuie sunat niciodată, adăugați-l prin POST /v1/dnc.
13. DELETE /v1/tasks/{id} la final, dacă sarcina nu a rulat niciodată sau s-a încheiat deja și doriți să ștergeți înregistrarea.

Aproape fiecare apel de scriere (PATCH, start, pause, DELETE) ia revision din ultima citire a sarcinii - aceeași concurență optimistă ca la ciornele agentului. O nepotrivire returnează revision_conflict: încărcați din nou sarcina (GET) și repetați cu revision actual. reconcile este o excepție - revision este acolo opțional.

MCP

Aceleași instrumente ca REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - cu o singură deosebire la pornire.

start_task confirmă cifrele

MCP start_task primește suplimentar confirmedRecipients și confirmedBudgetHal - acestea trebuie să corespundă exact numărului real de destinatari și bugetului sarcinii, altfel returnează validation cu valorile reale și NU pornește NIMIC. Un agent AI străin nu poate astfel să lanseze din greșeală, pe baza unei instrucțiuni înțelese neclar, o campanie plătită cu cifre inventate - REST POST .../start nu are acest mecanism, pentru că acolo apelează direct proprietarul contului, cu propria cheie.

delete_task și previzualizarea CSV nu există în MCP - ștergerea rămâne în REST și în portal (acțiune ireversibilă, cu rescrierea numelui), previzualizarea CSV este doar un pas al formularului.

Erori

• task_not_found - Nicio sarcină cu acest id în cont.
• task_not_editable - Sarcina rulează sau este încheiată (running/completed), ori este needs_attention fără posibilitate de reluare - regulile nu mai pot fi schimbate acum. Același cod îl returnează și POST .../items/{itemId}/resolve la o sarcină în rulare: un contact în review apare deja când sarcina sună celelalte contacte și este încă running - așteptați până trece în needs_attention sau puneți-o pe pauză (POST .../pause).
• items_immutable - Lista destinatarilor nu poate fi înlocuită după ce cel puțin o încercare de apelare a avut loc sau un contact a fost omis cu reason (cumpărare ori dezabonare).
• budget_too_low - Bugetul nu acoperă nici măcar o încercare de durată maximă a apelului - creșteți budgetHal sau reduceți maxDurationSecs.
• task_not_startable - Sarcina nu este în starea draft/ready/paused sau nu are niciun destinatar în așteptare.
• task_needs_attention - Înainte de următoarea pornire este nevoie de POST .../reconcile - ceva (versiunea agentului, motorul) s-a schimbat în timpul rulării.
• agent_not_ready - Ciorna agentului fie nu este publicată, fie versiunea publicată nu este testată - publicați-o (POST /v1/agents/{id}/draft/publish) și apoi testați versiunea publicată (POST /v1/agents/{id}/simulate) înainte de pornire.
• agent_version_changed - Configurația agentului s-a schimbat ÎN TIMPUL rulării sarcinii - testați și reporniți prin reconcile.
• engine_required - Agentul sarcinii nu este pe motorul volai (useForOutboundTasks: true) - campaniile de apeluri efectuate necesită azi motorul, nu ElevenLabs.
• engine_contract_unavailable - Motorul nu anunță momentan suport pentru variabilele și plafoanele sarcinilor de apeluri efectuate - încercați din nou pornirea mai târziu.
• window_closed - În afara ferestrei de apelare setate - așteptați deschiderea sau modificați callingWindow.
• task_not_running - Pauza este posibilă doar la o sarcină în rulare.
• item_not_resolvable - Contactul nu este în starea review - se poate decide (retry/skip) doar asupra unui contact care așteaptă verificarea, și doar la o sarcină care nu rulează. Excepție este omiterea cu reason (customer_purchased, unsubscribed): aceasta cere un contact pending inactiv într-o sarcină draft sau pending/failed într-una paused, fără apel nedecontat.
• task_not_deletable - Se poate șterge doar o sarcină fără element in_progress, în starea draft/ready/paused/completed/needs_attention.
• revision_conflict - Sarcina s-a schimbat între timp - încărcați-o din nou (GET) și repetați cu revision actual.

Tabelul complet al erorilor pentru fiecare endpoint îl găsiți în secțiunea Sarcini din referința API REST.