Handleidingen

Taken

Een taak belt een lijst ontvangers met één agent, volgens regels die u vooraf instelt - budget, belvenster, aantal pogingen. Er wordt niets gebeld totdat u de taak zelf start.

Wat een taak is

Een taak (task_...) is een uitgaande campagne: één agent op de engine van volai, een lijst ontvangers met een telefoonnummer en optionele variabelen voor de systeemprompt, en regels (budget, belvenster, maximaal aantal pogingen en gespreksduur). Er zijn drie typen naar doel - invoice (betalingsherinnering), appointment (afspraakbevestiging) en custom (al het overige) - en bij de eerste twee draagt elke ontvanger, wanneer source gelijk is aan integration, bovendien een verwijzing naar de factuur of afspraak (externalRefs) die de agent in het gesprek noemt.

Statussen en overgangen

In de praktijk gaat een taak altijd van `draft` rechtstreeks naar `running` (`start`); verwijderen (`DELETE`) kan alleen in de gemarkeerde statussen.

De exacte voorwaarde voor verwijderen: de status is een van de hierboven gemarkeerde EN geen enkel item heeft status: "in_progress" (een gesprek dat is begonnen en nog niet is afgelopen) - anders task_not_deletable.

Ontvangers importeren (CSV)

POST /v1/tasks/csv-preview verwerkt een CSV en geeft hem terug met fouten per rij - er wordt NIETS opgeslagen, het is alleen een voorbeeld vóór het aanmaken of wijzigen van een taak. Het formulier voor een nieuwe taak in het portaal roept dezelfde functie aan.

• Het scheidingsteken wordt automatisch herkend (komma of puntkomma) aan de hand van de eerste regel.
• Er moet een kolom phone zijn - hoofdletters, spaties rond de naam en een dubbele punt erachter maken niet uit, en ook telefon, tel of mobil wordt geaccepteerd; in het voorbeeld komt de kolom altijd terug als phone. Een kale lijst nummers zonder kopregel (één per regel, één kolom) wordt ook geaccepteerd. Anders mislukt de hele CSV met één fout phone bij de kopregel.
• Elke andere kolom is een variabele voor de systeemprompt van de agent ({{column_name}}) - maximaal 20 kolommen, naam maximaal 64 tekens, waarde maximaal 512 tekens.
• Het telefoonnummer wordt genormaliseerd zoals overal in de API (normalizePhone) - een ongeldig of leeg nummer is alleen op DIE rij een fout, de rest van de CSV wordt gewoon verwerkt.
• Een cel die op een spreadsheetformule lijkt (begint met =, +, - of @) wordt geweigerd - bescherming tegen CSV-injectie bij het openen in Excel.
• Maximaal 1000 rijen per CSV (hetzelfde plafond als het aantal ontvangers van een taak) en 1 MB ruwe tekst; de hele taak met bijlagen moet in 2 MB passen, anders geeft het aanmaken validation terug.

Het antwoord bevat headers, delimiter, rows (elke rij met zijn eigen fouten), validRows (alleen de foutloze, precies in de vorm die recipients in POST /v1/tasks verwacht) en een samenvattende lijst errors. Stuur validRows rechtstreeks door als recipients bij het aanmaken of wijzigen van de taak.

Budget en belvenster

Budget

budgetHal is het PLAFOND van de uitgaven voor de hele taak, in hellers. Bij het aanmaken moet het minstens één poging van maximale duur dekken (anders budget_too_low); bij de start wordt vóór ELKE belpoging de hoogst mogelijke prijs van de poging gereserveerd (reservedBudgetHal), en pas een opgenomen gesprek zet die om in spentHal. De reservering is de prijs van een gesprek van precies maxDurationSecs (het gedeelte van het gesprek en het gedeelte van de agent, elk naar boven afgerond op een heller zoals bij de afrekening) en een gesprek dat door het tijdplafond wordt beëindigd, wordt voor hooguit maxDurationSecs afgerekend, ook als het een fractie van een seconde later eindigt. Een taak geeft nooit meer uit dan u in budgetHal hebt opgegeven.

Belvenster

callingWindow is {timezone: "Europe/Prague", start, end, days} - momenteel is de tijdzone van Praag de enige ondersteunde, start/end in de vorm HH:MM (het einde geldt inclusief die hele minuut: het venster 09:00-18:00 laat het laatste gesprek om 18:00:59 toe, een venster tot 23:59 beslaat de hele dag) en days zijn de getallen 0-6 (0 = zondag). Zonder opgave gelden werkdagen van 9:00 tot 18:00. Buiten het venster geeft start window_closed terug - wacht tot het venster opent of pas het venster aan met PATCH. Het optionele expiresAt is het einde van de campagne als positief veilig geheel getal in Unix-milliseconden. Het wordt bij de start en vóór elke belpoging gecontroleerd, ook de eerste. Vanaf dit moment begint er geen nieuw gesprek en wordt er geen poging verbruikt; een lopend gesprek wordt afgerond. De herhalingshorizon van het beleid lorela_enterprise (retryMaxAgeDays, standaard 5) wordt daarentegen geteld als N × 24 uur vanaf de eerste getelde poging, niet vanaf het aanmaken van de taak.

Pogingen en gespreksduur

maxAttempts is zonder beleid 1-3 (standaard 1), met retryPolicy: "lorela_enterprise" 1-4 (bij het aanmaken standaard 4). Het is het hoogste aantal automatische belpogingen naar één contact, de eerste meegerekend (1 = geen herhaling). Elke poging waarbij het gesprek had kunnen plaatsvinden, telt mee, dus ook een niet-beantwoord gesprek, een door de gebelde afgewezen gesprek en een poging met een onzeker resultaat. Een poging die volai vóór het bellen heeft geweigerd, telt niet mee (bijvoorbeeld een geblokkeerd, eigen of ongeldig nummer, de niet-bellenlijst, een nummer waarop op dat moment een ander gesprek loopt, gesprekslimieten); zo'n poging heeft items[].attempts[].countsAsAttempt: false. Ook een gesprek waarvan de operator het doel niet op tijd kreeg, zodat de telefoon van de gebelde helemaal niet overging, telt niet mee (de poging heeft errorCode: "relay_not_routed", het gesprek endReason: "rejected"): het contact krijgt op zijn vroegst na een minuut een nieuwe poging (met het beleid lorela_enterprise volgens het schema daarvan) en na de derde zulke poging op rij gaat het ter controle met reviewReason: "call:relay_not_routed". Ook een gesprek waarvan onze spraakengine nooit iets heeft laten weten en dat we na twee uur zonder bericht hebben afgesloten als niet gebeld en zonder prijs, telt niet mee (de poging heeft errorCode: "no_provider_report"): het contact gaat terug naar de wachtenden en krijgt op zijn vroegst na een minuut een nieuwe poging (met het beleid lorela_enterprise volgens het schema daarvan). Drie niet-getelde pogingen op rij, ook gemengd met pogingen relay_not_routed, sturen het contact ter controle met de reviewReason van de laatste, dus call:no_provider_report; contacten die zo'n gesprek eerder ter controle had gestuurd (call:failed, met het beleid call:unknown) worden niet vanzelf heropend. Zonder beleid geldt het plafond alleen voor automatische belpogingen: een contact waarvoor u na het opraken van de pogingen resolve met action: "retry" geeft, krijgt nog één belpoging extra. maxDurationSecs (30-300) is het plafond voor de duur van ÉÉN gesprek, waarna het automatisch wordt beëindigd - de standaardduur is 120 seconden. Het optionele beleid lorela_enterprise schakelt u in via de API of MCP vóór de eerste poging; bestaande taken veranderen niet vanzelf. De tweede poging volgt op zijn vroegst 8 minuten na het begin van de eerste echte poging, binnen 08:00-22:00 Europe/Prague. De derde gaat naar het eerstvolgende andere venster 08:00-09:00 of 17:00-19:00, de vierde naar het tegenovergestelde venster op de volgende kalenderdag. Ook callingWindow en de dagen daarvan blijven gelden; na de herhalingshorizon belt het beleid niet meer: de optionele retryMaxAgeDays is een geheel aantal dagen 1-30 (zonder opgave 5) en geldt alleen met het beleid. De horizon eindigt N × 24 uur na de eerste getelde poging van het contact (vaste dagen van 24 uur, dus bij een wijziging van zomer- naar wintertijd verschuift de lokale eindtijd met een uur). Hij is ook na het begin van de pogingen te wijzigen met PATCH (niet bij een taak die running of completed is, die niet te bewerken is): verhogen bij een gepauzeerde taak zet contacten die alleen vanwege de horizon waren afgevallen (reviewReason: "retry_age_expired") terug naar failed (wachten op een volgende poging) met een nieuwe nextAttemptAt, als ze nog een poging over hebben en het eerstvolgende slot van het schema binnen de nieuwe horizon en vóór expiresAt valt; verlagen heropent niets. Alleen een PATCH die de horizon verhoogt, heropent contacten, stuur retryMaxAgeDays en een verlengde expiresAt dus in één verzoek mee. Alleen no_answer, missed, busy, een afgeronde voicemail en een opgenomen gesprek waarin de gebelde niets zei, komen in aanmerking voor herhaling (alles zonder contact met een mens). Contact met een mens, weigering en een fout van de engine stoppen de automatische herhaling; een onduidelijk resultaat gaat ter controle. De laatste toegestane poging (maxAttempts) die op zo'n herhaalbaar resultaat eindigt (niet opgenomen, bezet, voicemail of een opgenomen gesprek waarin de gebelde niets zei), sluit het contact af als skipped met reviewReason: "retry_policy_exhausted" (zoals retry_age_expired na het verstrijken van de horizon): er is niets te controleren of te herhalen. Een onduidelijk resultaat van de laatste poging blijft in review met dezelfde reden. Zonder beleid verandert er niets: de laatste niet-opgenomen poging is nog steeds review. Een geverifieerde terugbel door een mens na het opraken van de pogingen zet het contact op completed. DNC, budget en limieten blijven gelden: de automatische blokkade na 3 mislukkingen binnen 24 uur kan zelfs een vierde poging verhinderen. Bij PATCH zonder maxAttempts blijft de bestaande limiet staan. Met het beleid geeft een handmatige resolve met action: "retry" de fout validation; alleen de automatisch geplande pogingen van het beleid zijn toegestaan. Een uitzondering is het herstel van een aantoonbaar niet gebelde, verlopen claim vóór de eerste echte poging: zonder actieve worker, dispatch-voornemen, provider-call-ID, reservering, prijs of callback en met in de geschiedenis alleen bewezen weigeringen vóór het bellen. Het herstel behoudt de geschiedenis en de plafonds en zet het contact terug bij de wachtenden in de gepauzeerde taak; het belt zelf niet. Herinneringen kunnen op deze manier niet worden heropend. Handmatig herhalen omzeilt dus de vier pogingen, de herhalingshorizon of het stoppen na contact met een mens niet.

Globale doorvoer

Werkwijze voor een agent

Een typisch verloop, in deze volgorde:

1. De agent van de taak moet GEPUBLICEERD zijn en de gepubliceerde versie GETEST (POST /v1/agents/{id}/draft/publish, daarna POST /v1/agents/{id}/simulate) - anders geeft een latere start agent_not_ready terug.
2. Optioneel POST /v1/tasks/csv-preview - controleert de CSV met ontvangers voordat de taak wordt aangemaakt.
3. POST /v1/tasks - maakt de taak aan met de status draft. Er wordt niets gebeld.
4. GET /v1/tasks/{id} - lees issues (validatie als proefrun) en controleer of de taak klaar is om te starten.
5. Indien nodig PATCH /v1/tasks/{id} - pas de regels aan, ALTIJD met de revision van de laatste leesactie.
6. POST /v1/tasks/{id}/start - start het bellen. Elk opgenomen gesprek wordt direct afgerekend.
7. POST /v1/tasks/{id}/pause op elk moment tijdens het lopen, POST /v1/tasks/{id}/start hervat de taak weer.
8. Na een onderbreking (pauze midden in een gesprek, verlopen claim, een gesprek met een nog onbekende prijs of een onzekere belpoging waarvan het gesprek is teruggevonden) stemt POST /v1/tasks/{id}/reconcile de status af met de werkelijke gesprekken; zo'n taak met resterend werk eindigt in paused, ook als sommige contacten in review wachten, en kan opnieuw worden gestart met start. Een lopende taak en andere redenen (variables_limit, mislukte controle van een factuur of agenda, een belpoging waarvan het gesprek niet te vinden is) wijzigt reconcile niet; contacten ter controle handelt u af met resolve.
9. Een contact dat ter controle is geëindigd (items[].status: "review"), handelt u af met POST /v1/tasks/{id}/items/{itemId}/resolve en action: "retry" of "skip". Bij een gewone reden zet retry het contact terug bij de wachtenden en de taak op paused; skip sluit het af en de taak gaat naar paused als er nog werk is, of naar completed als alle contacten klaar of overgeslagen zijn. Een taak in paused hervat u daarna met POST /v1/tasks/{id}/start.
10. Heeft een contact reviewReason: "dial:destination_auto_blocked", dan is het nummer na herhaaldelijk onbeantwoorde gesprekken 30 dagen automatisch geblokkeerd en deblokkeert retry alleen het niet - het contact zou meteen terugkeren in review. Hef eerst de blokkade op (POST /v1/dnc/{e164}/unblock, in MCP unblock_destination, het nummer haalt u uit items[].phone) en geef dan resolve met action: "retry". Bij dial:on_dnc verwijdert u het nummer eerst van de niet-bellenlijst (DELETE /v1/dnc/{e164}), anders slaat u het contact over. Bij het eigen nummer van het account, het nummer van een ander volai-account, een ongeldig nummer, een nummer buiten Tsjechië en Slowakije en een betaallijn (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) helpt een nieuwe poging niet: gebruik alleen skip.
11. Heeft een contact reviewReason: "billing_unknown", dan kan het oorspronkelijke gesprek al hebben plaatsgevonden, maar is de prijs nog niet bekend. Roep eerst reconcile aan en controleer het gekoppelde gesprek. retry onthoudt dat het contact opnieuw moet worden geprobeerd, maar staat geen nieuw gesprek toe zolang de oorspronkelijke prijs niet is vastgesteld; daarna gaat de taak naar paused en is een nieuwe start nodig. skip voorkomt een nieuw gesprek; het oorspronkelijke gesprek blijft gekoppeld en de reservering ervan blijft meetellen in het budget totdat de prijs is vastgesteld. Is er nog werk, dan gaat de taak na skip meteen naar paused en kan hij worden gestart; zonder verder werk wacht hij in needs_attention en eindigt hij in completed zodra de prijs is vastgesteld. Een gesprek dat helemaal niet is gebeld (de engine weigerde het) wordt nooit afgerekend en staat meteen op 0.
12. Een contact dat intussen heeft gekocht of zich heeft afgemeld, slaat u zonder gesprek over via resolve met action: "skip", reason: "customer_purchased" of "unsubscribed", revision, een vaste operationId en een evidenceRef die verwijst naar het bewijs van de aankoop of afmelding (nooit naar een telefoonnummer of e-mailadres). Dat kan bij een pending contact in een draft taak en bij pending/failed in een paused taak zonder onafgehandeld gesprek; pogingen, prijzen en de niet-bellenlijst blijven behouden. GET /v1/tasks/{id} toont het bewijs daarna in items[].resolution (reason, operationId, evidenceRef, resolvedAt); dezelfde body veilig herhalen kan, een andere reason of evidenceRef voor hetzelfde contact geeft 409 revision_conflict. Overslaan zet het nummer niet op de niet-bellenlijst: moet het contact nooit meer worden gebeld, voeg het dan toe via POST /v1/dnc.
13. DELETE /v1/tasks/{id} aan het einde, als de taak nooit is gelopen of al is afgerond en u het record wilt verwijderen.

Bijna elke schrijfactie (PATCH, start, pause, DELETE) neemt revision van de laatste leesactie van de taak - dezelfde optimistische gelijktijdigheid als bij concepten van agents. Een verschil geeft revision_conflict: lees de taak opnieuw (GET) en herhaal met de actuele revision. reconcile is de uitzondering - revision is daar optioneel.

MCP

Dezelfde tools als REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - behalve één verschil bij de start.

start_task bevestigt de getallen

MCP start_task neemt daarnaast confirmedRecipients en confirmedBudgetHal aan - die moeten exact overeenkomen met het werkelijke aantal ontvangers en het budget van de taak, anders geeft de tool validation terug met de werkelijke waarden en start NIETS. Een AI-agent van een derde partij kan zo op basis van één vaag begrepen instructie niet per ongeluk een betaalde campagne starten met verzonnen getallen - REST POST .../start heeft deze mechaniek niet, omdat de accounteigenaar die daar rechtstreeks met zijn eigen sleutel aanroept.

delete_task en het CSV-voorbeeld zijn er niet in MCP - verwijderen blijft in REST en het portaal (een onomkeerbare actie met overtypen van de naam), het CSV-voorbeeld is alleen een stap van het formulier.

Fouten

• task_not_found - Er is geen taak met deze id op het account.
• task_not_editable - De taak loopt of is afgerond (running/completed), of is needs_attention zonder mogelijkheid tot herstel - de regels zijn nu niet te wijzigen. Dezelfde code geeft ook POST .../items/{itemId}/resolve terug bij een lopende taak: een contact in review verschijnt al terwijl de taak de overige contacten belt en nog running is - wacht tot hij naar needs_attention gaat of pauzeer hem (POST .../pause).
• items_immutable - De lijst ontvangers kan niet worden vervangen nadat minstens één belpoging heeft plaatsgevonden of een contact is overgeslagen met een reason (aankoop of afmelding).
• budget_too_low - Het budget dekt niet eens één poging van maximale gespreksduur - verhoog budgetHal of verlaag maxDurationSecs.
• task_not_startable - De taak heeft niet de status draft/ready/paused, of heeft geen wachtende ontvanger.
• task_needs_attention - Vóór de volgende start is POST .../reconcile nodig - er is tijdens het lopen iets (de versie van de agent, de engine) gewijzigd.
• agent_not_ready - Het concept van de agent is niet gepubliceerd of de gepubliceerde versie is niet getest - publiceer het (POST /v1/agents/{id}/draft/publish) en test daarna de gepubliceerde versie (POST /v1/agents/{id}/simulate) vóór de start.
• agent_version_changed - De configuratie van de agent is gewijzigd TERWIJL de taak liep - test hem en herstart via reconcile.
• engine_required - De agent van de taak staat niet op de engine van volai (useForOutboundTasks: true) - uitgaande campagnes vereisen nu de engine, niet ElevenLabs.
• engine_contract_unavailable - De engine meldt momenteel geen ondersteuning voor variabelen en plafonds van uitgaande taken - probeer de start later opnieuw.
• window_closed - Buiten het ingestelde belvenster - wacht tot het opent of pas callingWindow aan.
• task_not_running - Pauzeren kan alleen bij een lopende taak.
• item_not_resolvable - Het contact heeft niet de status review - een beslissing (retry/skip) kan alleen over een contact dat op controle wacht, en alleen bij een taak die niet loopt. Uitzondering is overslaan met een reason (customer_purchased, unsubscribed): daarvoor is een inactief pending contact in een draft taak nodig, of pending/failed in een paused taak, zonder onafgehandeld gesprek.
• task_not_deletable - Alleen een taak zonder item in_progress met de status draft/ready/paused/completed/needs_attention kan worden verwijderd.
• revision_conflict - De taak is intussen gewijzigd - lees hem opnieuw (GET) en herhaal met de actuele revision.

De volledige foutentabel voor elk endpoint vindt u in het onderdeel Taken in de REST API-referentie.