Anleitungen

Aufgaben

Eine Aufgabe wählt eine Empfängerliste mit einem Agenten an, nach Regeln, die Sie vorab festlegen - Budget, Anruffenster, Anzahl der Versuche. Nichts wird gewählt, solange Sie die Aufgabe nicht selbst starten.

Was eine Aufgabe ist

Eine Aufgabe (task_...) ist eine ausgehende Kampagne: ein Agent auf dem volai-Motor, eine Liste von Empfängern mit Telefonnummer und optionalen Variablen für den System-Prompt sowie Regeln (Budget, Anruffenster, maximale Anzahl der Versuche und Gesprächsdauer). Es gibt drei Typen nach Zweck - invoice (Zahlungserinnerung), appointment (Terminbestätigung) und custom (alles andere) - bei den ersten beiden trägt zusätzlich, wenn source den Wert integration hat, jeder Empfänger einen Verweis auf den Beleg oder das Ereignis (externalRefs), den der Agent im Gespräch erwähnt.

Status und Übergänge

In der Praxis geht eine Aufgabe immer von `draft` direkt zu `running` (`start`); löschen (`DELETE`) lässt sie sich nur in den markierten Status.

Genaue Bedingung zum Löschen: Der Status ist einer der oben markierten UND KEIN Element hat status: "in_progress" (ein laufender Anruf, der noch nicht beendet ist) - sonst task_not_deletable.

Import von Empfängern (CSV)

POST /v1/tasks/csv-preview parst die CSV und gibt sie mit Fehlern je Zeile zurück - es wird NICHTS gespeichert, es ist nur eine Vorschau vor dem Anlegen oder Ändern einer Aufgabe. Dieselbe Funktion ruft auch das Formular für neue Aufgaben im Portal auf.

• Das Trennzeichen wird anhand der ersten Zeile automatisch erkannt (Komma oder Semikolon).
• Es muss eine Spalte phone geben - Groß- und Kleinschreibung, Leerzeichen um den Namen und ein Doppelpunkt dahinter spielen keine Rolle, und auch telefon, tel oder mobil werden akzeptiert; in der Vorschau wird die Spalte immer als phone zurückgegeben. Eine bloße Nummernliste ohne Kopfzeile (eine pro Zeile, eine einzige Spalte) wird ebenfalls akzeptiert. Sonst scheitert die gesamte CSV an dem einen Fehler phone bei der Kopfzeile.
• Jede weitere Spalte ist eine Variable für den System-Prompt des Agenten ({{column_name}}) - höchstens 20 Spalten, Name höchstens 64 Zeichen, Wert höchstens 512 Zeichen.
• Die Telefonnummer wird wie überall in der API normalisiert (normalizePhone) - eine ungültige oder leere Nummer ist nur in DIESER Zeile ein Fehler, der Rest der CSV wird weiter verarbeitet.
• Eine Zelle, die wie eine Tabellenkalkulationsformel aussieht (beginnt mit =, +, - oder @), wird abgelehnt - Schutz vor CSV-Injection beim Öffnen in Excel.
• Höchstens 1000 Zeilen pro CSV (dieselbe Obergrenze wie die Zahl der Empfänger einer Aufgabe) und 1 MB Rohtext; die ganze Aufgabe samt Unterlagen muss in 2 MB passen, sonst liefert das Anlegen validation.

Die Antwort enthält headers, delimiter, rows (jede Zeile mit ihren Fehlern), validRows (nur die einwandfreien, genau in der Form, die recipients in POST /v1/tasks erwartet) und die zusammenfassenden errors. Senden Sie validRows beim Anlegen oder Ändern der Aufgabe direkt als recipients.

Budget und Anruffenster

Budget

budgetHal ist die OBERGRENZE der Ausgaben in Heller für die gesamte Aufgabe. Beim Anlegen muss es mindestens einen Versuch in maximaler Länge abdecken (sonst budget_too_low); beim Start wird vor JEDEM Wählvorgang der höchstmögliche Preis des Versuchs reserviert (reservedBudgetHal), erst ein angenommener Anruf schlägt sich in spentHal nieder. Die Reservierung entspricht dem Preis eines Anrufs in genau der Länge maxDurationSecs (Anrufabschnitt und Agentenabschnitt, jeweils wie bei der Abrechnung auf den Heller aufgerundet), und ein durch die Längenobergrenze beendeter Anruf wird höchstens für maxDurationSecs abgerechnet, auch wenn er einen Sekundenbruchteil später endet. Eine Aufgabe gibt nie mehr aus, als Sie ihr in budgetHal geben.

Anruffenster

callingWindow ist {timezone: "Europe/Prague", start, end, days} - heute wird nur die Prager Zeitzone unterstützt, start/end im Format HH:MM (das Ende gilt einschließlich der ganzen Minute: Das Fenster 09:00-18:00 lässt den letzten Anruf um 18:00:59 zu, ein Fenster bis 23:59 deckt den ganzen Tag ab) und days als Zahlen 0-6 (0 = Sonntag). Ohne Angabe gelten Werktage 9:00-18:00. Außerhalb des Fensters liefert start window_closed - warten Sie entweder, bis es öffnet, oder passen Sie das Fenster über PATCH an. Das optionale expiresAt ist das Ende der Kampagne als positive sichere Ganzzahl in Unix-Millisekunden. Es wird beim Start und vor jedem Wählvorgang geprüft, auch dem ersten. Ab diesem Zeitpunkt beginnt kein neuer Anruf, und kein Versuch wird verbraucht; ein laufender Anruf wird zu Ende geführt. Der Wiederholungshorizont der Richtlinie lorela_enterprise (retryMaxAgeDays, standardmäßig 5) wird dagegen als N × 24 Stunden ab dem ersten gezählten Versuch berechnet, nicht ab dem Anlegen der Aufgabe.

Versuche und Gesprächsdauer

maxAttempts beträgt ohne Richtlinie 1-3 (Standard 1), mit retryPolicy: "lorela_enterprise" 1-4 (beim Anlegen Standard 4). Es legt die höchste Anzahl automatischer Wählvorgänge je Kontakt einschließlich des ersten fest (1 = keine Wiederholung). Gezählt wird jeder Versuch, bei dem der Anruf stattfinden konnte, also auch ein nicht angenommener oder vom Angerufenen abgelehnter Anruf und ein Versuch mit unsicherem Ergebnis. Nicht gezählt wird ein Versuch, den volai schon vor dem Wählen abgelehnt hat (zum Beispiel gesperrte, eigene oder ungültige Nummer, Do-not-call-Liste, eine Nummer, auf die gerade ein anderer Anruf läuft, Anruflimits); ein solcher Versuch hat items[].attempts[].countsAsAttempt: false. Nicht gezählt wird auch ein Anruf, dessen Ziel der Betreiber nicht rechtzeitig erhielt, sodass das Telefon des Angerufenen gar nicht klingelte (der Versuch hat errorCode: "relay_not_routed", der Anruf endReason: "rejected"): Der Kontakt erhält frühestens nach einer Minute einen neuen Versuch (mit der Richtlinie lorela_enterprise nach deren Zeitplan), und nach dem dritten solchen Versuch in Folge geht er mit reviewReason: "call:relay_not_routed" zur Prüfung. Nicht gezählt wird auch ein Anruf, über den unser Sprachmotor nie berichtet hat und den wir nach zwei Stunden ohne Meldung als nicht gewählt und ohne Preis abgeschlossen haben (der Versuch hat errorCode: "no_provider_report"): Der Kontakt kehrt zu den wartenden zurück und erhält frühestens nach einer Minute einen neuen Versuch (mit der Richtlinie lorela_enterprise nach deren Zeitplan). Drei nicht gezählte Versuche in Folge, auch gemischt mit relay_not_routed-Versuchen, schicken den Kontakt mit dem reviewReason des letzten von ihnen zur Prüfung, also call:no_provider_report; Kontakte, die ein solcher Anruf früher zur Prüfung geschickt hat (call:failed, mit der Richtlinie call:unknown), werden nicht von selbst wieder geöffnet. Ohne Richtlinie gilt die Obergrenze nur für automatische Wählvorgänge: Ein Kontakt, dem Sie nach Verbrauch der Versuche resolve mit action: "retry" geben, erhält einen weiteren Wählvorgang. maxDurationSecs (30-300) ist die Obergrenze für die Länge EINES Anrufs, nach der er automatisch beendet wird - die Standarddauer beträgt 120 Sekunden. Die optionale Richtlinie lorela_enterprise wird vor dem ersten Versuch über API oder MCP eingeschaltet; bestehende Aufgaben ändern sich nicht von selbst. Der zweite Versuch erfolgt frühestens 8 Minuten nach Beginn des ersten tatsächlichen Versuchs, innerhalb von 08:00-22:00 Europe/Prague. Der dritte geht in das nächste andere Fenster 08:00-09:00 oder 17:00-19:00, der vierte in das gegenteilige Fenster am folgenden Kalendertag. Es gelten stets auch callingWindow und seine Tage; nach dem Wiederholungshorizont ruft die Richtlinie nicht mehr an: Das optionale retryMaxAgeDays ist eine ganze Zahl von Tagen 1-30 (ohne Angabe 5) und gilt nur mit der Richtlinie. Der Horizont endet N × 24 Stunden nach dem ersten gezählten Versuch des Kontakts (feste 24-Stunden-Tage, sodass sich über eine Zeitumstellung hinweg die lokale Endzeit um eine Stunde verschiebt). Er lässt sich über PATCH auch nach Beginn der Versuche ändern (nicht bei einer Aufgabe im Status running oder completed, die sich nicht bearbeiten lässt): Eine Erhöhung bei einer angehaltenen Aufgabe bringt Kontakte, die nur wegen des Horizonts ausgefallen sind (reviewReason: "retry_age_expired"), zurück in den Status failed (warten auf den nächsten Versuch) mit neuem nextAttemptAt, sofern sie noch einen freien Versuch haben und der nächste Zeitplan-Slot in den neuen Horizont und vor expiresAt fällt; eine Senkung öffnet nichts. Nur ein PATCH, der den Horizont erhöht, öffnet Kontakte wieder, senden Sie daher retryMaxAgeDays und ein verlängertes expiresAt in einer Anfrage. Wiederholt werden nur no_answer, missed, busy, eine abgeschlossene Mailbox und ein angenommener Anruf, in dem der Angerufene nichts gesagt hat (alles ohne Kontakt mit einem Menschen). Kontakt mit einem Menschen, Ablehnung und Motorfehler beenden die automatische Wiederholung; ein unklares Ergebnis geht zur Prüfung. Der letzte erlaubte Versuch (maxAttempts), der mit einem solchen wiederholbaren Ergebnis endet (nicht angenommen, besetzt, Mailbox oder angenommener Anruf, in dem der Angerufene nichts gesagt hat), schließt den Kontakt als skipped mit reviewReason: "retry_policy_exhausted" ab (wie retry_age_expired nach Ablauf des Horizonts): Es gibt nichts zu prüfen oder zu wiederholen. Ein unklares Ergebnis des letzten Versuchs bleibt mit demselben Grund in review. Ohne Richtlinie ändert sich nichts: Der letzte nicht angenommene Versuch ist weiterhin review. Ein verifizierter Rückruf eines Menschen nach Verbrauch der Versuche setzt den Kontakt auf completed. DNC, Budget und Limits bleiben in Kraft: Die automatische Sperre nach 3 Fehlschlägen innerhalb von 24 Stunden kann auch den vierten Versuch verhindern. Bei PATCH ohne maxAttempts bleibt das bisherige Limit erhalten. Mit der Richtlinie liefert ein manuelles resolve mit action: "retry" den Fehler validation; erlaubt sind nur ihre automatisch geplanten Versuche. Eine Ausnahme ist die Wiederherstellung eines nachweislich nicht gewählten, abgelaufenen Claims vor dem ersten tatsächlichen Versuch: ohne aktiven Worker, Dispatch-Absicht, Provider-Call-ID, Reservierung, Preis oder Callback und nur mit nachgewiesenen Ablehnungen vor dem Wählen in der Historie. Die Wiederherstellung bewahrt Historie und Obergrenzen und stellt den Kontakt in einer angehaltenen Aufgabe zurück zu den wartenden; sie wählt selbst nicht an. Erinnerungen lassen sich so nicht wieder öffnen. Eine manuelle Wiederholung umgeht also weder die vier Versuche noch den Wiederholungshorizont noch das Ende nach Kontakt mit einem Menschen.

Globaler Durchsatz

Vorgehen für den Agenten

Ein typischer Ablauf, in dieser Reihenfolge:

1. Der Agent der Aufgabe muss VERÖFFENTLICHT und die veröffentlichte Version GETESTET sein (POST /v1/agents/{id}/draft/publish, dann POST /v1/agents/{id}/simulate) - sonst liefert ein späteres start agent_not_ready.
2. Optional POST /v1/tasks/csv-preview - prüft die CSV der Empfänger, bevor die Aufgabe angelegt wird.
3. POST /v1/tasks - legt die Aufgabe im Status draft an. Es wird nichts angewählt.
4. GET /v1/tasks/{id} - lesen Sie issues (Dry-Run-Validierung) und prüfen Sie, dass die Aufgabe startbereit ist.
5. Bei Bedarf PATCH /v1/tasks/{id} - passen Sie die Regeln an, IMMER mit der revision aus dem letzten Lesen.
6. POST /v1/tasks/{id}/start - startet das Anwählen. Jeder angenommene Anruf wird sofort abgerechnet.
7. POST /v1/tasks/{id}/pause jederzeit während des Laufs, POST /v1/tasks/{id}/start setzt wieder fort.
8. Nach einer Unterbrechung (Pause mitten im Anruf, abgelaufener Claim, ein Anruf mit noch unbekanntem Preis oder ein unsicherer Wählvorgang, zu dem der Anruf gefunden wurde) gleicht POST /v1/tasks/{id}/reconcile den Zustand mit den tatsächlichen Anrufen ab; eine solche Aufgabe mit Restarbeit endet in paused, auch wenn einige Kontakte in review warten, und lässt sich über start erneut starten. Eine laufende Aufgabe und jeden anderen Grund (variables_limit, Fehlschlag der Rechnungs- oder Kalenderprüfung, ein unsicherer Wählvorgang, zu dem der Anruf nicht gefunden wurde) ändert reconcile nicht; Kontakte zur Prüfung erledigen Sie über resolve.
9. Einen Kontakt, der zur Prüfung geendet hat (items[].status: "review"), erledigen Sie mit POST /v1/tasks/{id}/items/{itemId}/resolve mit action: "retry" oder "skip". Bei einem gewöhnlichen Grund stellt retry den Kontakt zurück zu den wartenden und die Aufgabe nach paused; skip schließt ihn ab, und die Aufgabe wechselt nach paused, wenn noch Arbeit übrig ist, oder nach completed, wenn alle Kontakte erledigt oder übersprungen sind. Eine Aufgabe in paused setzen Sie dann mit POST /v1/tasks/{id}/start fort.
10. Hat ein Kontakt reviewReason: "dial:destination_auto_blocked", ist die Nummer nach wiederholt nicht angenommenen Anrufen 30 Tage automatisch gesperrt, und ein bloßes retry hebt die Sperre nicht auf - der Kontakt wäre sofort wieder in review. Heben Sie zuerst die Sperre auf (POST /v1/dnc/{e164}/unblock, in MCP unblock_destination, die Nummer entnehmen Sie items[].phone), dann resolve mit action: "retry". Bei dial:on_dnc entfernen Sie die Nummer zuerst aus der Do-not-call-Liste (DELETE /v1/dnc/{e164}), andernfalls überspringen Sie den Kontakt. Bei der eigenen Nummer des Kontos, der Nummer eines anderen volai-Kontos, einer ungültigen Nummer, einer Nummer außerhalb Tschechiens und der Slowakei und einer Premiumnummer (dial:cannot_call_own_number, dial:cannot_call_volai_number, dial:invalid_number, dial:unsupported_country, dial:blocked_destination) hilft ein weiterer Versuch nicht: Verwenden Sie nur skip.
11. Hat ein Kontakt reviewReason: "billing_unknown", ist der ursprüngliche Anruf möglicherweise schon gelaufen und hat nur noch keinen bekannten Preis. Rufen Sie zuerst reconcile auf und prüfen Sie den verknüpften Anruf. retry merkt sich, dass der Kontakt erneut versucht werden soll, erlaubt aber keinen neuen Anruf, bis sich der ursprüngliche Preis gesetzt hat; danach wechselt die Aufgabe in paused und erfordert ein neues start. skip verhindert einen weiteren Anruf; der ursprüngliche Anruf bleibt verknüpft, und seine Reservierung zählt weiter zum Budget, bis sich der Preis gesetzt hat. Ist noch Arbeit übrig, wechselt die Aufgabe nach skip direkt in paused und lässt sich starten; ohne weitere Arbeit wartet sie in needs_attention und endet nach Setzen des Preises in completed. Ein Anruf, der gar nicht gewählt wurde (der Motor hat ihn abgelehnt), wird nie abgerechnet und setzt sich sofort auf 0.
12. Einen Kontakt, der inzwischen gekauft hat oder sich abgemeldet hat, überspringen Sie ohne Anruf über resolve mit action: "skip", reason: "customer_purchased" oder "unsubscribed", revision, einer festen operationId und einer evidenceRef, die auf den Beleg des Kaufs oder der Abmeldung verweist (nie auf Telefon oder E-Mail). Das geht bei einem pending-Kontakt in einer draft-Aufgabe und bei pending/failed in einer paused-Aufgabe ohne offenen Anruf; Versuche, Preise und die Do-not-call-Liste bleiben erhalten. GET /v1/tasks/{id} zeigt den Beleg dann in items[].resolution (reason, operationId, evidenceRef, resolvedAt); derselbe Body lässt sich gefahrlos wiederholen, ein anderer reason oder eine andere evidenceRef beim selben Kontakt ist 409 revision_conflict. Das Überspringen trägt die Nummer nicht in die Do-not-call-Liste ein: Soll ein Kontakt nie wieder angerufen werden, fügen Sie ihn über POST /v1/dnc hinzu.
13. DELETE /v1/tasks/{id} am Ende, wenn die Aufgabe nie lief oder bereits durchgelaufen ist und Sie den Eintrag löschen möchten.

Fast jeder schreibende Aufruf (PATCH, start, pause, DELETE) nimmt die revision aus dem letzten Lesen der Aufgabe - dieselbe optimistische Nebenläufigkeit wie bei Entwürfen von Agenten. Bei einer Abweichung kommt revision_conflict: Laden Sie die Aufgabe erneut (GET) und wiederholen Sie den Aufruf mit der aktuellen revision. reconcile ist eine Ausnahme - die revision ist dort optional.

MCP

Dieselben Tools wie in REST (list_tasks, get_task, create_task, update_task, pause_task, resolve_task_item, reconcile_task, start_task) - bis auf einen Unterschied beim Start.

start_task bestätigt die Zahlen

MCP start_task nimmt zusätzlich confirmedRecipients und confirmedBudgetHal entgegen - sie müssen genau zur tatsächlichen Zahl der Empfänger und zum Budget der Aufgabe passen, sonst liefert es validation mit den tatsächlichen Werten und startet NICHTS. Ein fremder KI-Agent kann so aufgrund einer einzigen missverstandenen Anweisung nicht versehentlich eine kostenpflichtige Kampagne mit erfundenen Zahlen starten - REST POST .../start hat diesen Mechanismus nicht, weil dort der Kontoinhaber direkt mit seinem eigenen Schlüssel aufruft.

delete_task und die CSV-Vorschau gibt es in MCP nicht - das Löschen bleibt in REST und im Portal (eine unumkehrbare Aktion mit Abtippen des Namens), die CSV-Vorschau ist nur ein Formularschritt.

Fehler

• task_not_found - Auf dem Konto gibt es keine Aufgabe mit dieser id.
• task_not_editable - Die Aufgabe läuft oder ist abgeschlossen (running/completed) oder ist needs_attention ohne Möglichkeit zur Wiederaufnahme - die Regeln lassen sich jetzt nicht ändern. Denselben Code liefert auch POST .../items/{itemId}/resolve bei einer laufenden Aufgabe: Ein Kontakt in review erscheint schon, während die Aufgabe die übrigen Kontakte anruft und noch running ist - warten Sie, bis sie in needs_attention wechselt, oder halten Sie sie an (POST .../pause).
• items_immutable - Die Empfängerliste lässt sich nicht ersetzen, nachdem mindestens ein Wählversuch stattgefunden hat oder ein Kontakt mit reason übersprungen wurde (Kauf oder Abmeldung).
• budget_too_low - Das Budget deckt nicht einmal einen Versuch in maximaler Gesprächslänge ab - erhöhen Sie budgetHal oder senken Sie maxDurationSecs.
• task_not_startable - Die Aufgabe ist nicht im Status draft/ready/paused oder hat keinen wartenden Empfänger.
• task_needs_attention - Vor dem nächsten Start ist POST .../reconcile nötig - während der Laufzeit hat sich etwas geändert (Version des Agenten, Motor).
• agent_not_ready - Der Entwurf des Agenten ist entweder nicht veröffentlicht oder die veröffentlichte Version ist nicht getestet - veröffentlichen Sie ihn (POST /v1/agents/{id}/draft/publish) und testen Sie vor dem Start die veröffentlichte Version (POST /v1/agents/{id}/simulate).
• agent_version_changed - Die Konfiguration des Agenten hat sich WÄHREND der laufenden Aufgabe geändert - testen Sie und starten Sie über reconcile neu.
• engine_required - Der Agent der Aufgabe läuft nicht auf dem volai-Motor (useForOutboundTasks: true) - ausgehende Kampagnen erfordern heute den Motor, nicht ElevenLabs.
• engine_contract_unavailable - Der Motor meldet derzeit keine Unterstützung für Variablen und Obergrenzen ausgehender Aufgaben - versuchen Sie den Start später erneut.
• window_closed - Außerhalb des eingestellten Anruffensters - warten Sie, bis es öffnet, oder passen Sie callingWindow an.
• task_not_running - Eine Pause geht nur bei einer laufenden Aufgabe.
• item_not_resolvable - Der Kontakt ist nicht im Status review - entscheiden (retry/skip) lässt sich nur über einen Kontakt, der auf Prüfung wartet, und nur bei einer Aufgabe, die nicht läuft. Eine Ausnahme ist das Überspringen mit reason (customer_purchased, unsubscribed): Dafür ist ein inaktiver pending-Kontakt in einer draft-Aufgabe oder pending/failed in einer paused-Aufgabe ohne offenen Anruf nötig.
• task_not_deletable - Löschen lässt sich nur eine Aufgabe ohne Element in_progress im Status draft/ready/paused/completed/needs_attention.
• revision_conflict - Die Aufgabe hat sich inzwischen geändert - laden Sie sie erneut (GET) und wiederholen Sie den Aufruf mit der aktuellen revision.

Die vollständige Fehlertabelle für jeden Endpunkt finden Sie im Abschnitt Aufgaben in der REST-API-Referenz.