Vejledninger

Opgaver

En opgave ringer en liste af modtagere op med én agent efter de regler, du fastsætter på forhånd - budget, opkaldsvindue, antal forsøg. Intet ringes op, før du selv starter opgaven.

Hvad er en opgave

En opgave (task_...) er en udgående kampagne: én agent på volais motor, en liste af modtagere med telefonnummer og valgfrie variabler til systemprompten samt regler (budget, opkaldsvindue, maksimalt antal forsøg og opkaldets længde). Tre typer efter formål - invoice (betalingspåmindelse), appointment (bekræftelse af en aftale) og custom (alt andet) - hvor hver modtager i de to første, når source er integration, desuden bærer en reference til et dokument eller en begivenhed (externalRefs), som agenten nævner i opkaldet.

Statusser og overgange

I praksis går en opgave altid direkte fra `draft` til `running` (`start`); sletning (`DELETE`) er kun mulig i de markerede statusser.

Den præcise betingelse for sletning: status er en af de ovenfor markerede OG INGEN post har status: "in_progress" (et opkald, der er sluppet af sted og endnu ikke er slut) - ellers task_not_deletable.

Import af modtagere (CSV)

POST /v1/tasks/csv-preview parser CSV-filen og returnerer den med fejl på de enkelte rækker - INTET gemmes, det er blot en forhåndsvisning før oprettelse eller redigering af en opgave. Den samme funktion kaldes af formularen til en ny opgave i portalen.

• Skilletegnet genkendes automatisk (komma eller semikolon) ud fra den første række.
• Der skal findes en kolonne phone - store og små bogstaver, mellemrum omkring navnet og kolon efter det er ligegyldige, og telefon, tel eller mobil accepteres også; i forhåndsvisningen returneres kolonnen altid som phone. En ren liste af numre uden overskrift (ét pr. række, én kolonne) accepteres også. Ellers fejler hele CSV-filen med den ene fejl phone ved overskriften.
• Hver yderligere kolonne er en variabel til agentens systemprompt ({{column_name}}) - højst 20 kolonner, navn højst 64 tegn, værdi højst 512 tegn.
• Telefonnummeret normaliseres som alle andre steder i API'et (normalizePhone) - et ugyldigt eller tomt nummer er kun en fejl på DEN række, resten af CSV-filen behandles videre.
• En celle, der ligner en formel i et regneark (begynder med =, +, - eller @), afvises - beskyttelse mod CSV-injektion ved åbning i Excel.
• Højst 1000 rækker pr. CSV (samme loft som antallet af modtagere i en opgave) og 1 MB rå tekst; hele opgaven med bilag skal kunne være i 2 MB, ellers returnerer oprettelsen validation.

Svaret indeholder headers, delimiter, rows (hver række med sine fejl), validRows (kun de fejlfri, præcis i den form, som recipients i POST /v1/tasks forventer) og de samlede errors. Send validRows direkte som recipients ved oprettelse eller redigering af opgaven.

Budget og opkaldsvindue

Budget

budgetHal er et LOFT for forbruget i hundrededele af den lokale mønt for hele opgaven. Ved oprettelsen skal det dække mindst ét forsøg i maksimal længde (ellers budget_too_low); ved start reserveres den højest mulige pris for et forsøg FØR HVER opringning (reservedBudgetHal), og først et besvaret opkald overfører den til spentHal. Reservationen er prisen på opkaldet i præcis længden maxDurationSecs (opkaldsleddet og agentleddet, hver rundet op til nærmeste enhed ligesom ved afregningen), og et opkald afsluttet af længdeloftet afregnes højst for maxDurationSecs, selv om det slutter et brøkdels sekund senere. En opgave bruger aldrig mere, end du giver den i budgetHal.

Opkaldsvindue

callingWindow er {timezone: "Europe/Prague", start, end, days} - i dag er den eneste understøttede tidszone den prag'ske, start/end i formen HH:MM (slut inklusive hele minuttet: vinduet 09:00-18:00 lader det sidste opkald gå igennem kl. 18:00:59, vinduet til 23:59 dækker hele dagen) og days tallene 0-6 (0 = søndag). Uden angivelse gælder hverdage 9:00-18:00. Uden for vinduet returnerer start window_closed - enten vent, til det åbner, eller ret vinduet via PATCH. Den valgfrie expiresAt er kampagnens slutning som et positivt sikkert heltal i Unix-millisekunder. Den kontrolleres ved start og før hver opringning, også den første. Fra dette tidspunkt begynder intet nyt opkald, og forsøget bruges ikke; et igangværende opkald kører færdigt. Gentagelseshorisonten i politikken lorela_enterprise (retryMaxAgeDays, standard 5) regnes derimod som N × 24 timer fra det første medregnede forsøg, ikke fra oprettelsen af opgaven.

Forsøg og opkaldets længde

maxAttempts er uden politik 1-3 (standard 1), med retryPolicy: "lorela_enterprise" 1-4 (ved oprettelsen standard 4). Det bestemmer det højeste antal automatiske opringninger af én kontakt inklusive den første (1 = uden gentagelser). Hvert forsøg, hvor opkaldet kunne forløbe, tælles med, altså også et ubesvaret eller afvist af den opringede og et forsøg med usikkert resultat. Et forsøg, som volai afviste allerede før opringningen (for eksempel et blokeret, eget eller ugyldigt nummer, en Do-not-call-liste, et nummer, hvorpå der netop kører et andet opkald, opkaldsgrænser), tælles ikke med; et sådant forsøg har items[].attempts[].countsAsAttempt: false. Heller ikke et opkald tælles med, hvor operatøren ikke fik destinationen i tide, så den opringedes telefon slet ikke ringede (forsøget har errorCode: "relay_not_routed", opkaldet endReason: "rejected"): kontakten får et nyt forsøg tidligst om et minut (med politikken lorela_enterprise efter dens plan), og efter det tredje sådanne forsøg i træk går den til kontrol med reviewReason: "call:relay_not_routed". Heller ikke et opkald tælles med, som vores stemmemotor aldrig meldte tilbage om, og som vi efter to timer uden besked lukkede som ikke ringet op og uden pris (forsøget har errorCode: "no_provider_report"): kontakten vender tilbage blandt de ventende og får et nyt forsøg tidligst om et minut (med politikken lorela_enterprise efter dens plan). Tre ikke-medregnede forsøg i træk, også blandet med forsøg af typen relay_not_routed, sender kontakten til kontrol med reviewReason efter det sidste af dem, altså call:no_provider_report; kontakter, som et sådant opkald tidligere sendte til kontrol (call:failed, med politikken call:unknown), genoptages ikke af sig selv. Uden politik gælder loftet kun for automatiske opringninger: en kontakt, som du efter opbrugte forsøg giver resolve med action: "retry", får endnu én ekstra opringning. maxDurationSecs (30-300) er loftet for længden af ÉT opkald, hvorefter det afsluttes automatisk - standardlængden er 120 sekunder. Den valgfrie politik lorela_enterprise slås til via API eller MCP før det første forsøg; eksisterende opgaver ændrer sig ikke af sig selv. Det andet forsøg er tidligst 8 minutter fra begyndelsen af det første egentlige forsøg i tidsrummet 08:00-22:00 Europe/Prague. Det tredje går til det næste, andet vindue 08:00-09:00 eller 17:00-19:00, det fjerde til det modsatte vindue den følgende kalenderdag. Altid gælder også callingWindow og dets dage; efter gentagelseshorisonten ringer politikken ikke igen: den valgfrie retryMaxAgeDays er et helt antal dage 1-30 (uden angivelse 5) og gælder kun med politikken. Horisonten slutter N × 24 timer efter kontaktens første medregnede forsøg (faste 24-timers døgn, så den lokale sluttid forskydes med en time over en tidsomstilling). Den kan ændres via PATCH også efter forsøgenes begyndelse (ikke for en opgave i running eller completed, den kan ikke redigeres): en forhøjelse på en pauseret opgave sætter kontakter, der kun faldt fra på grund af horisonten (reviewReason: "retry_age_expired"), tilbage til status failed (venter på et nyt forsøg) med en ny nextAttemptAt, hvis de stadig har et ledigt forsøg, og den nærmeste plads i planen falder inden for den nye horisont og før expiresAt; en sænkning åbner intet. Kun en PATCH, der hæver horisonten, åbner igen, så send retryMaxAgeDays og en forlænget expiresAt i samme anmodning. Kun no_answer, missed, busy, en gennemført telefonsvarer og et besvaret opkald, hvor den opringede intet sagde, gentages (alt uden kontakt med et menneske). Kontakt med et menneske, afvisning og en fejl i motoren stopper den automatiske gentagelse; et uklart resultat går til kontrol. Det sidste tilladte forsøg (maxAttempts), der ender med et sådant gentageligt resultat (ubesvaret, optaget, telefonsvarer eller et besvaret opkald, hvor den opringede intet sagde), lukker kontakten som skipped med reviewReason: "retry_policy_exhausted" (som retry_age_expired efter horisontens udløb): der er intet at kontrollere eller gentage. Et uklart resultat af det sidste forsøg bliver stående i review med samme årsag. Uden politik ændres intet: det sidste ubesvarede forsøg er stadig review. Et verificeret menneskeligt callback efter opbrugte forsøg skifter kontakten til completed. DNC, budget og grænser forbliver gældende: den automatiske blokering efter 3 mislykkede forsøg på 24 timer kan også stoppe et fjerde forsøg. Ved PATCH uden maxAttempts bevares den hidtidige grænse. Med politikken returnerer et manuelt resolve med action: "retry" fejlen validation; kun dens automatisk planlagte forsøg er tilladt. Undtagelsen er genoptagelsen af en påviseligt ikke-ringet udløbet claim før det første egentlige forsøg: uden en aktiv worker, dispatch-hensigt, udbyderens opkalds-ID, reservation, pris eller callback og kun med påviste afvisninger før opringningen i historikken. Genoptagelsen bevarer historikken og lofterne og sætter kontakten tilbage blandt de ventende i en pauseret opgave; den ringer ikke selv. Påmindelser kan ikke genåbnes på denne måde. Et manuelt gentaget forsøg omgår altså ikke fire forsøg, gentagelseshorisonten eller afslutningen efter kontakt med et menneske.

Global gennemstrømning

Fremgangsmåde for agenten

Et typisk forløb, i denne rækkefølge:

1. Opgavens agent skal være OFFENTLIGGJORT og den offentliggjorte version TESTET (POST /v1/agents/{id}/draft/publish, derefter POST /v1/agents/{id}/simulate) - ellers returnerer et senere start agent_not_ready.
2. Eventuelt POST /v1/tasks/csv-preview - kontrollerer modtagernes CSV, før opgaven oprettes.
3. POST /v1/tasks - opretter opgaven i status draft. Intet ringes op.
4. GET /v1/tasks/{id} - læs issues (dry-run-validering), og kontrollér, at opgaven er klar til start.
5. Efter behov PATCH /v1/tasks/{id} - ret reglerne, ALTID med revision fra den seneste læsning.
6. POST /v1/tasks/{id}/start - starter opringningen. Hvert besvaret opkald afregnes straks.
7. POST /v1/tasks/{id}/pause når som helst under kørslen, POST /v1/tasks/{id}/start genoptager igen.
8. Efter en afbrydelse (pause midt i et opkald, udløbet claim, et opkald med endnu ukendt pris eller en usikker opringning, hvor opkaldet blev fundet) afstemmer POST /v1/tasks/{id}/reconcile tilstanden med de faktiske opkald; en sådan opgave med arbejde ender i paused, selv om nogle kontakter venter i review, og kan startes igen via start. En kørende opgave og enhver anden årsag (variables_limit, svigtende kontrol af faktura eller kalender, en usikker opringning, hvor opkaldet ikke blev fundet) ændrer reconcile ikke; kontakter til kontrol håndteres via resolve.
9. En kontakt, der endte til kontrol (items[].status: "review"), håndteres med POST /v1/tasks/{id}/items/{itemId}/resolve med action: "retry" eller "skip". Ved en almindelig årsag sætter retry kontakten tilbage blandt de ventende og opgaven til paused; skip lukker den, og opgaven går til paused, hvis der er arbejde tilbage, eller til completed, hvis alle kontakter er færdige eller sprunget over. En opgave i paused genoptages så med POST /v1/tasks/{id}/start.
10. Har en kontakt reviewReason: "dial:destination_auto_blocked", er nummeret automatisk blokeret i 30 dage efter gentagne ubesvarede opkald, og et retry alene ophæver ikke blokeringen - kontakten ville straks vende tilbage til review. Ophæv først blokeringen (POST /v1/dnc/{e164}/unblock, i MCP unblock_destination, tag nummeret fra items[].phone), derefter resolve med action: "retry". Ved dial:on_dnc fjern først nummeret fra Do-not-call-listen (DELETE /v1/dnc/{e164}), ellers spring kontakten over. Ved kontoens eget nummer, en anden volai-kontos nummer, et ugyldigt nummer, et nummer uden for Tjekkiet og Slovakiet og en premium-linje (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) hjælper et nyt forsøg ikke: brug kun skip.
11. Har en kontakt reviewReason: "billing_unknown", kan det oprindelige opkald allerede være forløbet, det har blot endnu ikke en kendt pris. Kald først reconcile, og kontrollér det tilknyttede opkald. retry husker, at kontakten skal prøves igen, men tillader ikke et nyt opkald, før den oprindelige pris er faldet til ro; derefter går opgaven til paused og kræver et nyt start. skip forhindrer et yderligere opkald; det oprindelige opkald forbliver tilknyttet, og dets reservation tæller fortsat med i budgettet, indtil prisen er faldet til ro. Er der arbejde tilbage, går opgaven efter skip straks til paused og kan startes; uden yderligere arbejde venter den i needs_attention og ender i completed, når prisen er faldet til ro. Et opkald, der slet ikke blev ringet op (motoren afviste det), afregnes aldrig og falder straks til ro på 0.
12. En kontakt, der i mellemtiden har købt eller afmeldt sig, springes over uden opkald via resolve med action: "skip", reason: "customer_purchased" eller "unsubscribed", revision, et fast operationId og en evidenceRef, der henviser til dokumentationen for købet eller afmeldingen (aldrig til telefon eller e-mail). Det er muligt for en pending kontakt i en draft-opgave og for pending/failed i en paused-opgave uden et uafklaret opkald; forsøg, priser og Do-not-call-listen bevares. GET /v1/tasks/{id} viser så dokumentationen i items[].resolution (reason, operationId, evidenceRef, resolvedAt); den samme krop kan trygt gentages, en anden reason eller evidenceRef på samme kontakt er 409 revision_conflict. Overspringningen skriver ikke nummeret på Do-not-call-listen: skal kontakten aldrig ringes op igen, tilføj den via POST /v1/dnc.
13. DELETE /v1/tasks/{id} til sidst, hvis opgaven aldrig er kørt eller allerede er kørt færdig, og du vil slette posten.

Næsten hvert skrivende kald (PATCH, start, pause, DELETE) tager revision fra den seneste læsning af opgaven - samme optimistiske samtidighed som ved agentens kladder. En uoverensstemmelse returnerer revision_conflict: hent opgaven igen (GET), og gentag med den aktuelle revision. reconcile er en undtagelse - revision er dér valgfri.

MCP

De samme værktøjer som REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - bortset fra én forskel ved start.

start_task bekræfter tallene

MCP start_task tager desuden confirmedRecipients og confirmedBudgetHal - de skal præcis svare til det faktiske antal modtagere og opgavens budget, ellers returnerer den validation med de faktiske værdier opført og starter INTET. En fremmed AI-agent kan således ikke på baggrund af en uklart forstået instruktion ved en fejl sætte en betalt kampagne i gang på opdigtede tal - REST POST .../start har ikke denne mekanik, fordi det dér er kontoens ejer, der selv kalder med sin egen nøgle.

delete_task og forhåndsvisningen af CSV findes ikke i MCP - sletning forbliver i REST og portalen (en uigenkaldelig handling med indtastning af navnet), CSV-forhåndsvisningen er kun et trin i formularen.

Fejl

• task_not_found - Der er ingen opgave med dette id på kontoen.
• task_not_editable - Opgaven kører eller er færdig (running/completed), eller er needs_attention uden mulighed for genoptagelse - reglerne kan nu ikke ændres. Den samme kode returnerer også POST .../items/{itemId}/resolve ved en kørende opgave: en kontakt i review dukker op, allerede mens opgaven ringer de øvrige kontakter op og stadig er running - vent, til den går til needs_attention, eller sæt den på pause (POST .../pause).
• items_immutable - Listen af modtagere kan ikke erstattes, når mindst ét opringningsforsøg har fundet sted, eller en kontakt er sprunget over med en reason (køb eller afmelding).
• budget_too_low - Budgettet dækker ikke engang ét forsøg i opkaldets maksimale længde - hæv budgetHal, eller sænk maxDurationSecs.
• task_not_startable - Opgaven er ikke i status draft/ready/paused, eller har ingen ventende modtager.
• task_needs_attention - Før næste start er POST .../reconcile nødvendig - noget (agentens version, motoren) er ændret under kørslen.
• agent_not_ready - Agentens kladde er enten ikke offentliggjort, eller den offentliggjorte version er ikke testet - offentliggør den (POST /v1/agents/{id}/draft/publish), og test derefter den offentliggjorte version (POST /v1/agents/{id}/simulate) før start.
• agent_version_changed - Agentens konfiguration blev ændret UNDER en kørende opgave - test, og genstart via reconcile.
• engine_required - Opgavens agent er ikke på volais motor (useForOutboundTasks: true) - udgående kampagner kræver i dag motoren, ikke ElevenLabs.
• engine_contract_unavailable - Motoren annoncerer i øjeblikket ikke understøttelse af variabler og lofter for udgående opgaver - prøv start igen senere.
• window_closed - Uden for det indstillede opkaldsvindue - vent, til det åbner, eller ret callingWindow.
• task_not_running - Pause er kun mulig for en kørende opgave.
• item_not_resolvable - Kontakten er ikke i status review - en beslutning (retry/skip) er kun mulig for en kontakt, der venter på kontrol, og kun for en opgave, der ikke kører. Undtagelsen er overspringning med en reason (customer_purchased, unsubscribed): den kræver en inaktiv pending kontakt i en draft-opgave eller pending/failed i en paused-opgave, uden et uafklaret opkald.
• task_not_deletable - Kun en opgave uden en post i in_progress i status draft/ready/paused/completed/needs_attention kan slettes.
• revision_conflict - Opgaven er i mellemtiden ændret - hent den igen (GET), og gentag med den aktuelle revision.

Den fulde tabel over fejl for hvert endpoint findes i afsnittet Opgaver i REST API-referencen.