Guider

Uppgifter

En uppgift ringer upp en lista med mottagare med en enda agent enligt regler som ställs in i förväg - budget, samtalsfönster, antal försök. Ingenting ringas upp förrän uppgiften startas manuellt.

Vad en uppgift är

En uppgift (task_...) är en utgående kampanj: en agent på volais motor, en lista med mottagare med telefonnummer och valfria variabler för systemprompten, samt regler (budget, samtalsfönster, högsta antal försök och samtalslängd). Tre typer efter syfte - invoice (betalningspåminnelse), appointment (bekräftelse av tid) och custom (allt annat) - för de två första dessutom, när source är integration, bär varje mottagare en referens till ett dokument eller en händelse (externalRefs) som agenten nämner i samtalet.

Statusar och övergångar

I praktiken går en uppgift alltid från `draft` direkt till `running` (`start`); borttagning (`DELETE`) går bara i markerade statusar.

Exakt villkor för borttagning: statusen är en av de markerade ovan OCH INGEN post har status: "in_progress" (ett pågående samtal som ännu inte slutat) - annars task_not_deletable.

Import av mottagare (CSV)

POST /v1/tasks/csv-preview tolkar CSV-filen och returnerar den med fel för enskilda rader - INGET sparas, det är bara en förhandsgranskning före skapande eller ändring av en uppgift. Samma funktion anropas av formuläret för ny uppgift i portalen.

• Avgränsaren känns igen automatiskt (kommatecken eller semikolon) utifrån första raden.
• Kolumnen phone måste finnas - versaler, mellanslag runt namnet och kolon efter det spelar ingen roll, och även telefon, tel eller mobil godtas; i förhandsgranskningen returneras kolumnen alltid som phone. En ren lista med nummer utan rubrik (ett per rad, en enda kolumn) godtas också. Annars faller hela CSV-filen på ett enda fel phone vid rubriken.
• Varje ytterligare kolumn är en variabel för agentens systemprompt ({{column_name}}) - högst 20 kolumner, namn högst 64 tecken, värde högst 512 tecken.
• Telefonnumret normaliseras på samma sätt som överallt i API:t (normalizePhone) - ett ogiltigt eller tomt nummer är ett fel bara på DEN raden, resten av CSV-filen behandlas vidare.
• En cell som ser ut som en kalkylbladsformel (börjar med =, +, - eller @) avvisas - skydd mot CSV-injektion när filen öppnas i Excel.
• Högst 1000 rader per CSV (samma tak som antalet mottagare i en uppgift) och 1 MB rå text; hela uppgiften med underlag måste rymmas inom 2 MB, annars returnerar skapandet validation.

Svaret innehåller headers, delimiter, rows (varje rad med sina fel), validRows (bara felfria, exakt i den form som recipients i POST /v1/tasks förväntar sig) och sammanfattande errors. validRows skickas direkt som recipients vid skapande eller ändring av en uppgift.

Budget och samtalsfönster

Budget

budgetHal är TAKET för utgifterna i minsta enhet (hal) för hela uppgiften. Vid skapandet måste det täcka minst ett försök av maximal längd (annars budget_too_low); vid start reserveras före VARJE uppringning det högsta möjliga priset för försöket (reservedBudgetHal), och först ett besvarat samtal för över det till spentHal. Reservationen är priset för ett samtal på exakt maxDurationSecs (samtalsbenet och agentbenet, vart och ett avrundat uppåt till en hal på samma sätt som vid debiteringen) och ett samtal som avslutas av längdtaket debiteras högst för maxDurationSecs, även om det slutar en bråkdels sekund senare. En uppgift spenderar aldrig mer än det som anges i budgetHal.

Samtalsfönster

callingWindow är {timezone: "Europe/Prague", start, end, days} - i dag stöds bara Pragtidszonen, start/end i formatet HH:MM (slutet inklusive hela minuten: fönstret 09:00-18:00 släpper igenom det sista samtalet kl. 18:00:59, ett fönster till 23:59 täcker hela dygnet) och days är talen 0-6 (0 = söndag). Utan angivelse gäller vardagar 9:00-18:00. Utanför fönstret returnerar start window_closed - vänta antingen tills fönstret öppnas eller ändra fönstret via PATCH. Det valfria expiresAt är kampanjens slut som ett positivt säkert heltal i Unix-millisekunder. Det kontrolleras vid start och före varje uppringning, den första inräknad. Från den tidpunkten påbörjas inget nytt samtal och ett försök förbrukas inte; ett pågående samtal avslutas. Horisonten för upprepning i policyn lorela_enterprise (retryMaxAgeDays, standard 5) räknas däremot som N × 24 timmar från det första räknade försöket, inte från att uppgiften skapades.

Försök och samtalslängd

maxAttempts är 1-3 utan policy (standard 1), med retryPolicy: "lorela_enterprise" 1-4 (vid skapandet standard 4). Det anger det högsta antalet automatiska uppringningar av en kontakt, den första inräknad (1 = ingen upprepning). Varje försök där samtalet kunde ha genomförts räknas, alltså även obesvarade eller avvisade av den uppringda och ett försök med osäkert resultat. Ett försök som volai avvisade redan före uppringningen räknas inte (till exempel ett blockerat, eget eller ogiltigt nummer, spärrlistan, ett nummer dit just nu ett annat samtal pågår, samtalsgränser); ett sådant försök har items[].attempts[].countsAsAttempt: false. Inte heller räknas ett samtal vars mål operatören inte fick i tid, så att den uppringdas telefon aldrig ringde (försöket har errorCode: "relay_not_routed", samtalet endReason: "rejected"): kontakten får ett nytt försök tidigast efter en minut (med policyn lorela_enterprise enligt dess schema) och efter det tredje sådana försöket i rad går den till kontroll med reviewReason: "call:relay_not_routed". Inte heller räknas ett samtal som vår röstmotor aldrig rapporterade och som vi efter två timmar utan meddelande stängde som ej uppringt och utan pris (försöket har errorCode: "no_provider_report"): kontakten återgår bland de väntande och får ett nytt försök tidigast efter en minut (med policyn lorela_enterprise enligt dess schema). Tre icke räknade försök i rad, även blandade med försök av typen relay_not_routed, skickar kontakten till kontroll med reviewReason enligt det sista av dem, alltså call:no_provider_report; kontakter som ett sådant samtal tidigare skickade till kontroll (call:failed, med policyn call:unknown) återupptas inte av sig själva. Utan policy gäller taket bara automatiska uppringningar: en kontakt som efter förbrukade försök får resolve med action: "retry" får ytterligare en uppringning. maxDurationSecs (30-300) är taket för längden på ETT samtal, varefter det avslutas automatiskt - standardlängden är 120 sekunder. Den valfria policyn lorela_enterprise slås på via API eller MCP före det första försöket; befintliga uppgifter ändras inte av sig själva. Det andra försöket sker tidigast 8 minuter efter början av det första faktiska försöket under tiden 08:00-22:00 Europe/Prague. Det tredje går till nästa andra fönster 08:00-09:00 eller 17:00-19:00, det fjärde till det motsatta fönstret nästa kalenderdag. Alltid gäller också callingWindow och dess dagar; efter upprepningshorisonten ringer policyn inte igen: det valfria retryMaxAgeDays är ett heltal dagar 1-30 (utan angivelse 5) och gäller bara med policyn. Horisonten slutar N × 24 timmar efter kontaktens första räknade försök (fasta 24-timmarsdygn, så över en tidsomställning förskjuts slutets lokala tid med en timme). Den kan ändras via PATCH även efter att försöken börjat (inte för en uppgift som är running eller completed, den kan inte ändras): en höjning för en pausad uppgift återför kontakter som föll bort bara på grund av horisonten (reviewReason: "retry_age_expired") till status failed (väntar på nästa försök) med nytt nextAttemptAt, om de ännu har ett ledigt försök och schemats närmaste slot hamnar inom den nya horisonten och före expiresAt; en sänkning öppnar ingenting. Bara en PATCH som höjer horisonten öppnar på nytt, så retryMaxAgeDays och ett förlängt expiresAt ska skickas i samma anrop. Policyn upprepar bara no_answer, missed, busy, en slutförd röstbrevlåda och ett besvarat samtal där den uppringda inte sa något (allt utan kontakt med en människa). Kontakt med en människa, avvisande och motorfel stoppar den automatiska upprepningen; ett oklart resultat går till kontroll. Det sista tillåtna försöket (maxAttempts) som slutar med ett sådant upprepningsbart resultat (obesvarat, upptaget, röstbrevlåda eller ett besvarat samtal där den uppringda inte sa något) stänger kontakten som skipped med reviewReason: "retry_policy_exhausted" (som retry_age_expired efter att horisonten löpt ut): det finns inget att kontrollera eller upprepa. Ett oklart resultat av det sista försöket stannar i review med samma orsak. Utan policy ändras ingenting: det sista obesvarade försöket är fortfarande review. En verifierad mänsklig återuppringning efter förbrukade försök sätter kontakten på completed. DNC, budget och gränser gäller fortfarande: den automatiska blockeringen efter 3 misslyckanden på 24 timmar kan stoppa även ett fjärde försök. Vid PATCH utan maxAttempts ligger den hittillsvarande gränsen kvar. Med policyn returnerar en manuell resolve med action: "retry" felet validation; tillåtna är bara dess automatiskt schemalagda försök. Undantaget är återställning av en bevisligen ej uppringd utgången claim före det första faktiska försöket: utan aktiv worker, dispatch-avsikt, provider call ID, reservation, pris eller callback och bara med belagda avvisanden före uppringningen i historiken. Återställningen bevarar historiken och taken och återför kontakten bland de väntande i den pausade uppgiften; den ringer inte själv. Påminnelser kan inte öppnas på nytt på det här sättet. Manuell upprepning kringgår alltså inte fyra försök, upprepningshorisonten eller avslutet efter kontakt med en människa.

Global genomströmning

Arbetsgång för agenten

Ett typiskt förlopp, i den här ordningen:

1. Uppgiftens agent måste vara PUBLICERAD och den publicerade versionen TESTAD (POST /v1/agents/{id}/draft/publish, därefter POST /v1/agents/{id}/simulate) - annars returnerar en senare start agent_not_ready.
2. Valfritt POST /v1/tasks/csv-preview - kontrollerar mottagarnas CSV innan uppgiften skapas.
3. POST /v1/tasks - skapar uppgiften i status draft. Ingenting ringas upp.
4. GET /v1/tasks/{id} - läs issues (dry-run-validering) och kontrollera att uppgiften är redo för start.
5. Vid behov PATCH /v1/tasks/{id} - justera reglerna, ALLTID med revision från den senaste läsningen.
6. POST /v1/tasks/{id}/start - startar uppringningen. Varje besvarat samtal debiteras genast.
7. POST /v1/tasks/{id}/pause när som helst under körningen, POST /v1/tasks/{id}/start återupptar igen.
8. Efter ett avbrott (paus mitt i ett samtal, utgången claim, ett samtal med ännu okänt pris eller en osäker uppringning där samtalet hittats) justerar POST /v1/tasks/{id}/reconcile läget mot de faktiska samtalen; en sådan uppgift med arbete kvar hamnar i paused även om vissa kontakter väntar i review, och går att starta på nytt via start. En körande uppgift eller en annan orsak (variables_limit, misslyckad kontroll av faktura eller kalender, en osäker uppringning där samtalet inte hittats) ändras inte av reconcile; kontakter för kontroll hanteras via resolve.
9. En kontakt som hamnat i kontroll (items[].status: "review") hanteras med POST /v1/tasks/{id}/items/{itemId}/resolve med action: "retry" eller "skip". Vid en vanlig orsak återför retry kontakten bland de väntande och uppgiften till paused; skip stänger den och uppgiften går över till paused om arbete återstår, eller till completed om alla kontakter är klara eller överhoppade. En uppgift i paused återupptas sedan med POST /v1/tasks/{id}/start.
10. När en kontakt har reviewReason: "dial:destination_auto_blocked" är numret automatiskt blockerat i 30 dagar efter upprepade obesvarade samtal och enbart retry häver inte blockeringen - kontakten skulle genast hamna i review igen. Häv först blockeringen (POST /v1/dnc/{e164}/unblock, i MCP unblock_destination, numret hämtas från items[].phone) och gör därefter resolve med action: "retry". Vid dial:on_dnc tas först numret bort från spärrlistan (DELETE /v1/dnc/{e164}), annars hoppas kontakten över. För kontots eget nummer, ett annat volai-kontos nummer, ett ogiltigt nummer, ett nummer utanför Tjeckien och Slovakien och en premiumlinje (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) hjälper inget ytterligare försök: använd bara skip.
11. När en kontakt har reviewReason: "billing_unknown" kan det ursprungliga samtalet redan ha genomförts, bara utan känt pris ännu. Anropa först reconcile och kontrollera det kopplade samtalet. retry noterar att kontakten ska prövas igen men tillåter inget nytt samtal förrän det ursprungliga priset har landat; därefter går uppgiften över till paused och kräver en ny start. skip förhindrar ytterligare samtal; det ursprungliga samtalet förblir kopplat och dess reservation räknas fortfarande in i budgeten tills priset har landat. Återstår arbete går uppgiften efter skip direkt till paused och kan startas; utan mer arbete väntar den i needs_attention och hamnar i completed när priset har landat. Ett samtal som aldrig ringdes upp (motorn avvisade det) debiteras aldrig och landar genast på 0.
12. En kontakt som under tiden har köpt eller avregistrerat sig hoppas över utan samtal via resolve med action: "skip", reason: "customer_purchased" eller "unsubscribed", revision, ett stabilt operationId och en evidenceRef som pekar på underlaget för köpet eller avregistreringen (aldrig på telefon eller e-post). Det går för en pending-kontakt i en uppgift i draft och för pending/failed i en uppgift i paused utan olöst samtal; försök, priser och spärrlistan bevaras. GET /v1/tasks/{id} visar sedan underlaget i items[].resolution (reason, operationId, evidenceRef, resolvedAt); samma body kan upprepas säkert, ett annat reason eller en annan evidenceRef för samma kontakt ger 409 revision_conflict. Överhoppningen skriver inte numret till spärrlistan: ska en kontakt aldrig mer ringas läggs den till via POST /v1/dnc.
13. DELETE /v1/tasks/{id} i slutet, om uppgiften aldrig har körts eller redan är klar och posten ska tas bort.

Nästan varje skrivande anrop (PATCH, start, pause, DELETE) tar revision från den senaste läsningen av uppgiften - samma optimistiska samtidighet som för agentutkast. En avvikelse returnerar revision_conflict: läs uppgiften på nytt (GET) och upprepa med den aktuella revision. reconcile är ett undantag - revision är där valfri.

MCP

Samma verktyg som i REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - förutom en skillnad vid start.

start_task bekräftar siffrorna

MCP start_task tar dessutom confirmedRecipients och confirmedBudgetHal - de måste stämma exakt med det faktiska antalet mottagare och uppgiftens budget, annars returneras validation med de faktiska värdena utskrivna och INGET startas. En främmande AI-agent kan därmed inte på grund av en enda missförstådd instruktion av misstag sätta igång en betald kampanj på påhittade siffror - REST POST .../start har inte den mekaniken, eftersom där kontoägaren själv anropar med sin egen nyckel.

delete_task och CSV-förhandsgranskning finns inte i MCP - borttagning finns kvar i REST och portalen (en oåterkallelig åtgärd med inskrivning av namnet), CSV-förhandsgranskningen är bara ett steg i formuläret.

Fel

• task_not_found - Ingen uppgift med det här id finns på kontot.
• task_not_editable - Uppgiften körs eller är klar (running/completed), eller är needs_attention utan möjlighet till återupptagande - reglerna går inte att ändra nu. Samma kod returneras även av POST .../items/{itemId}/resolve för en körande uppgift: en kontakt i review dyker upp redan när uppgiften ringer övriga kontakter och fortfarande är running - vänta tills den går över till needs_attention, eller pausa den (POST .../pause).
• items_immutable - Mottagarlistan kan inte ersättas efter att minst ett uppringningsförsök har ägt rum eller en kontakt har hoppats över med reason (köp eller avregistrering).
• budget_too_low - Budgeten täcker inte ens ett försök av maximal samtalslängd - höj budgetHal eller sänk maxDurationSecs.
• task_not_startable - Uppgiften är inte i status draft/ready/paused, eller har ingen väntande mottagare.
• task_needs_attention - Före nästa start behövs POST .../reconcile - något (agentens version, motorn) har ändrats under körningen.
• agent_not_ready - Agentens utkast är antingen inte publicerat, eller så är den publicerade versionen inte testad - publicera det (POST /v1/agents/{id}/draft/publish) och testa sedan den publicerade versionen (POST /v1/agents/{id}/simulate) före start.
• agent_version_changed - Agentens konfiguration ändrades UNDER en körande uppgift - testa och starta om via reconcile.
• engine_required - Uppgiftens agent ligger inte på volais motor (useForOutboundTasks: true) - utgående kampanjer kräver i dag motorn, inte ElevenLabs.
• engine_contract_unavailable - Motorn annonserar för tillfället inget stöd för variabler och tak för utgående uppgifter - försök starta igen senare.
• window_closed - Utanför det inställda samtalsfönstret - vänta tills det öppnas eller ändra callingWindow.
• task_not_running - Paus går bara för en körande uppgift.
• item_not_resolvable - Kontakten är inte i status review - avgörande (retry/skip) går bara för en kontakt som väntar på kontroll, och bara för en uppgift som inte körs. Undantaget är överhoppning med reason (customer_purchased, unsubscribed): den kräver en inaktiv pending-kontakt i en uppgift i draft, eller pending/failed i paused, utan olöst samtal.
• task_not_deletable - Bara en uppgift utan post i in_progress i status draft/ready/paused/completed/needs_attention kan tas bort.
• revision_conflict - Uppgiften har under tiden ändrats - läs den på nytt (GET) och upprepa med den aktuella revision.

Den fullständiga felkodstabellen för varje endpoint finns i avsnittet Uppgifter i REST-API-referensen.