Przewodniki

Zadania

Zadanie wybiera numery z listy odbiorców jednym agentem według reguł ustawionych z góry - budżet, okno dzwonienia, liczba prób. Nic nie jest wybierane, dopóki sami nie uruchomią Państwo zadania.

Czym jest zadanie

Zadanie (task_...) to kampania wychodząca: jeden agent na silniku volai, lista odbiorców z numerem telefonu i opcjonalnymi zmiennymi do promptu systemowego oraz reguły (budżet, okno dzwonienia, maksymalna liczba prób i długość rozmowy). Są trzy typy według celu - invoice (przypomnienie o płatności), appointment (potwierdzenie terminu) i custom (cokolwiek innego) - a w dwóch pierwszych, gdy source ma wartość integration, każdy odbiorca niesie odwołanie do dokumentu lub zdarzenia (externalRefs), o którym agent wspomina w rozmowie.

Statusy i przejścia

W praktyce zadanie zawsze przechodzi ze `draft` prosto do `running` (`start`); usunąć (`DELETE`) można tylko w oznaczonych statusach.

Dokładny warunek usunięcia: status jest jednym z oznaczonych wyżej ORAZ ŻADNA pozycja nie ma status: "in_progress" (rozpoczęta rozmowa, która jeszcze się nie zakończyła) - w przeciwnym razie task_not_deletable.

Import odbiorców (CSV)

POST /v1/tasks/csv-preview parsuje CSV i zwraca je z błędami przy poszczególnych wierszach - NIC nie jest zapisywane, to tylko podgląd przed założeniem lub edycją zadania. Tę samą funkcję wywołuje formularz nowego zadania w portalu.

• Separator jest rozpoznawany automatycznie (przecinek lub średnik) według pierwszego wiersza.
• Musi istnieć kolumna phone - wielkość liter, spacje wokół nazwy ani dwukropek po niej nie mają znaczenia, a przejdzie też telefon, tel lub mobil; w podglądzie kolumna jest zawsze zwracana jako phone. Przejdzie także sama lista numerów bez nagłówka (jeden na wiersz, jedyna kolumna). W przeciwnym razie całe CSV odpada z jednym błędem phone przy nagłówku.
• Każda kolejna kolumna jest zmienną do promptu systemowego agenta ({{column_name}}) - najwyżej 20 kolumn, nazwa maks. 64 znaki, wartość maks. 512 znaków.
• Numer telefonu jest normalizowany tak samo jak wszędzie w API (normalizePhone) - nieprawidłowy lub pusty numer jest błędem tylko w TYM wierszu, reszta CSV jest przetwarzana dalej.
• Komórka wyglądająca jak formuła arkusza kalkulacyjnego (zaczyna się od =, +, - lub @) jest odrzucana - ochrona przed wstrzyknięciem CSV przy otwarciu w Excelu.
• Najwyżej 1000 wierszy w jednym CSV (ten sam limit co liczba odbiorców zadania) i 1 MB surowego tekstu; całe zadanie wraz z materiałami musi zmieścić się w 2 MB, w przeciwnym razie założenie zwróci validation.

Odpowiedź zawiera headers, delimiter, rows (każdy wiersz z własnymi błędami), validRows (tylko bezbłędne, dokładnie w kształcie, jakiego recipients w POST /v1/tasks oczekuje) oraz zbiorcze errors. validRows proszę wysłać wprost jako recipients przy zakładaniu lub edycji zadania.

Budżet i okno dzwonienia

Budżet

budgetHal to LIMIT wydatków w groszach (setnych części waluty) na całe zadanie. Przy zakładaniu musi pokrywać co najmniej jedną próbę o maksymalnej długości (w przeciwnym razie budget_too_low); przy starcie przed KAŻDYM wybraniem numeru rezerwowana jest najwyższa możliwa cena próby (reservedBudgetHal), a dopiero odebrana rozmowa przenosi ją do spentHal. Rezerwacja to cena rozmowy dokładnie o długości maxDurationSecs (odcinek rozmowy i odcinek agenta, każdy zaokrąglony w górę do jednostki tak samo jak przy rozliczaniu), a rozmowa zakończona limitem długości jest rozliczana najwyżej za maxDurationSecs, nawet jeśli skończy się ułamek sekundy później. Zadanie nigdy nie wyda więcej, niż przeznaczą na nie Państwo w budgetHal.

Okno dzwonienia

callingWindow to {timezone: "Europe/Prague", start, end, days} - dziś jedyną obsługiwaną strefą jest praska, start/end w formacie HH:MM (koniec włącznie z całą minutą: okno 09:00-18:00 przepuści ostatnie połączenie o 18:00:59, okno do 23:59 obejmuje cały dzień), a days to liczby 0-6 (0 = niedziela). Bez ustawienia obowiązują dni robocze 9:00-18:00. Poza oknem start zwraca window_closed - albo poczekają Państwo na otwarcie, albo zmienią okno przez PATCH. Opcjonalne expiresAt to koniec kampanii jako dodatnia bezpieczna liczba całkowita w milisekundach Unix. Jest sprawdzane przy starcie i przed każdym wybraniem numeru, także pierwszym. Od tego momentu nowa rozmowa się nie zaczyna, a próba nie jest zużywana; trwająca rozmowa dobiega końca. Horyzont powtórzeń polityki lorela_enterprise (retryMaxAgeDays, domyślnie 5) liczy się natomiast jako N × 24 godziny od pierwszej zaliczonej próby, a nie od założenia zadania.

Próby i długość rozmowy

maxAttempts bez polityki wynosi 1-3 (domyślnie 1), z retryPolicy: "lorela_enterprise" 1-4 (przy zakładaniu domyślnie 4). Określa najwyższą liczbę automatycznych wybrań jednego kontaktu wraz z pierwszym (1 = bez powtórzeń). Zalicza się każda próba, w której rozmowa mogła się odbyć, a więc także nieodebrana lub odrzucona przez wywoływanego oraz próba z niepewnym wynikiem. Nie zalicza się próby, którą volai odrzuciło jeszcze przed wybraniem numeru (na przykład numer zablokowany, własny lub nieprawidłowy, lista nie dzwonić, numer, na który właśnie trwa inna rozmowa, limity połączeń); taka próba ma items[].attempts[].countsAsAttempt: false. Nie zalicza się też rozmowy, której operator nie dostał na czas celu, więc telefon wywoływanego w ogóle nie zadzwonił (próba ma errorCode: "relay_not_routed", rozmowa endReason: "rejected"): kontakt dostaje nową próbę najwcześniej po minucie (z polityką lorela_enterprise według jej harmonogramu), a po trzeciej takiej próbie z rzędu trafia do kontroli z reviewReason: "call:relay_not_routed". Nie zalicza się także rozmowy, o której nasz silnik głosowy nigdy nie dał znać i którą po dwóch godzinach bez wiadomości zamknęliśmy jako niewybraną i bez ceny (próba ma errorCode: "no_provider_report"): kontakt wraca do oczekujących i dostaje nową próbę najwcześniej po minucie (z polityką lorela_enterprise według jej harmonogramu). Trzy niezaliczone próby z rzędu, także zmieszane z próbami relay_not_routed, kierują kontakt do kontroli z reviewReason według ostatniej z nich, czyli call:no_provider_report; kontakty, które taka rozmowa skierowała do kontroli wcześniej (call:failed, z polityką call:unknown), nie wznawiają się same. Bez polityki limit dotyczy tylko automatycznych wybrań: kontakt, któremu po wyczerpaniu prób nadadzą Państwo resolve z action: "retry", dostanie jeszcze jedno dodatkowe wybranie. maxDurationSecs (30-300) to limit długości JEDNEJ rozmowy, po którym jest ona automatycznie kończona - domyślna długość to 120 sekund. Opcjonalną politykę lorela_enterprise włącza się przez API lub MCP przed pierwszą próbą; istniejące zadania nie zmieniają się same. Druga próba następuje najwcześniej po 8 minutach od początku pierwszej faktycznej próby w godzinach 08:00-22:00 Europe/Prague. Trzecia przypada na następne, inne okno 08:00-09:00 lub 17:00-19:00, czwarta na przeciwne okno następnego dnia kalendarzowego. Zawsze obowiązuje też callingWindow i jego dni; po upływie horyzontu powtórzeń polityka już nie dzwoni: opcjonalne retryMaxAgeDays to liczba całkowita dni 1-30 (bez ustawienia 5) i obowiązuje tylko z polityką. Horyzont kończy się N × 24 godziny po pierwszej zaliczonej próbie kontaktu (stałe 24-godzinne doby, więc przy zmianie czasu lokalny czas końca przesuwa się o godzinę). Można go zmienić przez PATCH także po rozpoczęciu prób (nie w zadaniu running ani completed, tego nie da się edytować): zwiększenie w wstrzymanym zadaniu przywraca kontakty, które odpadły wyłącznie z powodu horyzontu (reviewReason: "retry_age_expired"), do statusu failed (czekają na kolejną próbę) z nowym nextAttemptAt, jeśli mają jeszcze wolną próbę, a najbliższy slot harmonogramu mieści się w nowym horyzoncie i przed expiresAt; zmniejszenie niczego nie otwiera. Ponownie otwiera tylko PATCH, który horyzont zwiększa, dlatego retryMaxAgeDays i wydłużone expiresAt proszę wysyłać w jednym żądaniu. Powtarza tylko no_answer, missed, busy, zakończoną pocztę głosową i odebraną rozmowę, w której wywoływany nic nie powiedział (wszystko bez kontaktu z człowiekiem). Kontakt z człowiekiem, odmowa i błąd silnika zatrzymują automatyczne powtarzanie; niejasny wynik trafia do kontroli. Ostatnia dozwolona próba (maxAttempts), która kończy się takim powtarzalnym wynikiem (nieodebrane, zajęte, poczta głosowa lub odebrana rozmowa, w której wywoływany nic nie powiedział), zamyka kontakt jako skipped z reviewReason: "retry_policy_exhausted" (jak retry_age_expired po upływie horyzontu): nie ma czego kontrolować ani powtarzać. Niejasny wynik ostatniej próby pozostaje w review z tym samym powodem. Bez polityki nic się nie zmienia: ostatnia nieodebrana próba nadal jest review. Zweryfikowany ludzki callback po wyczerpaniu prób przełącza kontakt na completed. DNC, budżet i limity pozostają w mocy: automatyczna blokada po 3 niepowodzeniach w ciągu 24 godzin może zatrzymać także czwartą próbę. Przy PATCH bez maxAttempts zostaje dotychczasowy limit. Z polityką ręczne resolve z action: "retry" zwraca błąd validation; dozwolone są tylko jej automatycznie zaplanowane próby. Wyjątkiem jest odzyskanie dowodnie niewybranego, wygasłego claimu przed pierwszą faktyczną próbą: bez aktywnego workera, zamiaru dispatch, provider call ID, rezerwacji, ceny lub callbacku i tylko z udowodnionymi odmowami przed wybraniem numeru w historii. Odzyskanie zachowuje historię i limity i zwraca kontakt do oczekujących w wstrzymanym zadaniu; samo nie dzwoni. Przypomnień w ten sposób nie można ponownie otworzyć. Ręczne powtórzenie nie omija więc czterech prób, horyzontu powtórzeń ani zakończenia po kontakcie z człowiekiem.

Globalna przepustowość

Procedura dla agenta

Typowy przebieg, w tej kolejności:

1. Agent zadania musi być OPUBLIKOWANY, a opublikowana wersja PRZETESTOWANA (POST /v1/agents/{id}/draft/publish, następnie POST /v1/agents/{id}/simulate) - w przeciwnym razie późniejszy start zwróci agent_not_ready.
2. Opcjonalnie POST /v1/tasks/csv-preview - sprawdza CSV odbiorców przed założeniem zadania.
3. POST /v1/tasks - zakłada zadanie w statusie draft. Nic nie jest wybierane.
4. GET /v1/tasks/{id} - proszę odczytać issues (walidacja dry-run) i sprawdzić, że zadanie jest gotowe do startu.
5. W razie potrzeby PATCH /v1/tasks/{id} - zmiana reguł, ZAWSZE z revision z ostatniego odczytu.
6. POST /v1/tasks/{id}/start - uruchamia wybieranie numerów. Każda odebrana rozmowa jest rozliczana od razu.
7. POST /v1/tasks/{id}/pause w dowolnym momencie podczas działania, POST /v1/tasks/{id}/start wznawia.
8. Po przerwaniu (pauza w trakcie rozmowy, wygasły claim, rozmowa ze wciąż nieznaną ceną lub niepewne wybranie, do którego rozmowa została odnaleziona) POST /v1/tasks/{id}/reconcile uzgadnia stan z faktycznymi rozmowami; takie zadanie z pracą kończy w paused, nawet jeśli niektóre kontakty czekają w review, i można je ponownie uruchomić przez start. Działającego zadania ani innego powodu (variables_limit, niepowodzenie weryfikacji faktury lub kalendarza, niepewne wybranie, do którego rozmowy nie odnaleziono) reconcile nie zmienia; kontakty do kontroli proszę załatwić przez resolve.
9. Kontakt, który trafił do kontroli (items[].status: "review"), proszę załatwić przez POST /v1/tasks/{id}/items/{itemId}/resolve z action: "retry" lub "skip". Przy zwykłym powodzie retry zwraca kontakt do oczekujących, a zadanie do paused; skip go zamyka, a zadanie przechodzi do paused, jeśli zostaje praca, lub do completed, jeśli wszystkie kontakty są zakończone albo pominięte. Zadanie w paused wznawiają Państwo przez POST /v1/tasks/{id}/start.
10. Jeśli kontakt ma reviewReason: "dial:destination_auto_blocked", numer jest automatycznie blokowany przez 30 dni po wielokrotnie nieodebranych rozmowach, a samo retry go nie odblokuje - kontakt od razu wróciłby do review. Najpierw proszę zdjąć blokadę (POST /v1/dnc/{e164}/unblock, w MCP unblock_destination, numer pochodzi z items[].phone), potem resolve z action: "retry". Przy dial:on_dnc najpierw proszę usunąć numer z listy nie dzwonić (DELETE /v1/dnc/{e164}), w przeciwnym razie kontakt pominąć. Przy własnym numerze konta, numerze innego konta volai, nieprawidłowym numerze, numerze spoza Czech i Słowacji oraz linii premium (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) kolejna próba nie pomoże: proszę użyć wyłącznie skip.
11. Jeśli kontakt ma reviewReason: "billing_unknown", pierwotna rozmowa mogła już się odbyć, tylko nie ma jeszcze znanej ceny. Proszę najpierw wywołać reconcile i sprawdzić powiązaną rozmowę. retry zapamiętuje, że kontakt ma być ponowiony, ale nie dopuści nowej rozmowy, dopóki cena pierwotnej się nie ustabilizuje; potem zadanie przechodzi do paused i wymaga nowego start. skip zapobiega kolejnej rozmowie; pierwotna rozmowa pozostaje powiązana, a jej rezerwacja nadal wlicza się do budżetu, dopóki cena się nie ustabilizuje. Jeśli zostaje praca, zadanie po skip przechodzi od razu do paused i można je uruchomić; bez dalszej pracy poczeka w needs_attention, a po ustabilizowaniu ceny zakończy się w completed. Rozmowa, która w ogóle nie została wybrana (silnik ją odrzucił), nigdy nie jest rozliczana i stabilizuje się od razu na 0.
12. Kontakt, który w międzyczasie dokonał zakupu lub się wypisał, proszę pominąć bez rozmowy przez resolve z action: "skip", reason: "customer_purchased" lub "unsubscribed", revision, stałym operationId i evidenceRef odwołującym się do dowodu zakupu lub wypisania (nigdy do telefonu czy e-maila). Jest to możliwe dla kontaktu pending w zadaniu draft oraz pending/failed w zadaniu paused bez nierozliczonej rozmowy; próby, ceny i lista nie dzwonić pozostają. GET /v1/tasks/{id} pokaże następnie dowód w items[].resolution (reason, operationId, evidenceRef, resolvedAt); to samo ciało można bezpiecznie powtórzyć, inny reason lub evidenceRef przy tym samym kontakcie to 409 revision_conflict. Pominięcie nie zapisuje numeru na listę nie dzwonić: jeśli kontakt ma już nigdy nie być wybierany, proszę dodać go przez POST /v1/dnc.
13. DELETE /v1/tasks/{id} na końcu, jeśli zadanie nigdy się nie odbyło lub już się zakończyło, a chcą Państwo usunąć zapis.

Prawie każde wywołanie zapisujące (PATCH, start, pause, DELETE) przyjmuje revision z ostatniego odczytu zadania - ta sama optymistyczna współbieżność co przy wersjach roboczych agenta. Niezgodność zwraca revision_conflict: proszę wczytać zadanie ponownie (GET) i powtórzyć z aktualnym revision. reconcile jest wyjątkiem - revision jest tam opcjonalne.

MCP

Te same narzędzia co w REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - z wyjątkiem jednej różnicy przy starcie.

start_task potwierdza liczby

MCP start_task przyjmuje dodatkowo confirmedRecipients i confirmedBudgetHal - muszą dokładnie odpowiadać faktycznej liczbie odbiorców i budżetowi zadania, w przeciwnym razie zwraca validation z wypisanymi faktycznymi wartościami i NICZEGO nie uruchamia. Obcy agent AI na podstawie jednego niejasno zrozumianego polecenia nie może więc przez pomyłkę rozpocząć płatnej kampanii na zmyślonych liczbach - REST POST .../start nie ma tego mechanizmu, bo wywołuje go bezpośrednio właściciel konta własnym kluczem.

delete_task i podgląd CSV w MCP nie istnieją - usuwanie pozostaje w REST i portalu (nieodwracalna operacja z przepisaniem nazwy), podgląd CSV jest tylko krokiem formularza.

Błędy

• task_not_found - Na koncie nie ma zadania o tym id.
• task_not_editable - Zadanie działa lub jest zakończone (running/completed), albo jest needs_attention bez możliwości wznowienia - reguł nie można teraz zmieniać. Ten sam kod zwraca też POST .../items/{itemId}/resolve dla działającego zadania: kontakt w review pojawia się już wtedy, gdy zadanie dzwoni do pozostałych kontaktów i jest jeszcze running - proszę poczekać, aż przejdzie do needs_attention, lub je wstrzymać (POST .../pause).
• items_immutable - Listy odbiorców nie można zastąpić po tym, jak odbyła się co najmniej jedna próba wybrania numeru lub kontakt został pominięty z reason (zakup lub wypisanie).
• budget_too_low - Budżet nie pokrywa nawet jednej próby o maksymalnej długości rozmowy - proszę zwiększyć budgetHal lub zmniejszyć maxDurationSecs.
• task_not_startable - Zadanie nie jest w statusie draft/ready/paused albo nie ma żadnego oczekującego odbiorcy.
• task_needs_attention - Przed kolejnym startem potrzebny jest POST .../reconcile - coś (wersja agenta, silnik) zmieniło się w trakcie działania.
• agent_not_ready - Wersja robocza agenta nie jest opublikowana albo opublikowana wersja nie jest przetestowana - proszę ją opublikować (POST /v1/agents/{id}/draft/publish), a potem przetestować opublikowaną wersję (POST /v1/agents/{id}/simulate) przed startem.
• agent_version_changed - Konfiguracja agenta zmieniła się W TRAKCIE działającego zadania - proszę przetestować i zrestartować przez reconcile.
• engine_required - Agent zadania nie działa na silniku volai (useForOutboundTasks: true) - kampanie wychodzące wymagają dziś silnika, a nie ElevenLabs.
• engine_contract_unavailable - Silnik chwilowo nie deklaruje obsługi zmiennych i limitów zadań wychodzących - proszę spróbować startu ponownie później.
• window_closed - Poza ustawionym oknem dzwonienia - proszę poczekać na otwarcie lub zmienić callingWindow.
• task_not_running - Pauza jest możliwa tylko dla działającego zadania.
• item_not_resolvable - Kontakt nie jest w statusie review - decyzję (retry/skip) można podjąć tylko dla kontaktu czekającego na kontrolę i tylko w zadaniu, które nie działa. Wyjątkiem jest pominięcie z reason (customer_purchased, unsubscribed): wymaga ono nieaktywnego kontaktu pending w zadaniu draft lub pending/failed w paused, bez nierozliczonej rozmowy.
• task_not_deletable - Usunąć można tylko zadanie bez pozycji in_progress w statusie draft/ready/paused/completed/needs_attention.
• revision_conflict - Zadanie w międzyczasie się zmieniło - proszę wczytać je ponownie (GET) i powtórzyć z aktualnym revision.

Pełną tabelę błędów dla każdego endpointu znajdą Państwo w sekcji Zadania w referencji REST API.