Aufgabe (Task)

Einführung

Aufgabe (Task) ist die Fähigkeit des Agents, proaktive Nachrichten zu senden: Der Agent eröffnet die Konversation von sich aus, anstatt darauf zu warten, dass die Nutzer:in zuerst schreibt.

Im Unterschied zu einer regulären Konversation, die nach dem Muster „Nutzer:in stellt eine Frage → Agent antwortet“ abläuft, funktioniert eine Aufgabe so: „Die Plattform sendet gemäß den von Ihnen festgelegten Bedingungen stellvertretend für die Nutzer:in eine Nachricht an den Agent → der Agent generiert eine Antwort → die Antwort wird an die Nutzer:in gesendet“. Die „Auslösenachricht“, die Sie in der Aufgabe hinterlegen, ist im Kern eine Nachricht, die stellvertretend für die Nutzer:in an den Agent geschickt wird. Der Agent generiert seine Antwort genauso, als hätte er eine echte Nutzernachricht erhalten. Die Nutzer:in sieht am Ende die Antwort des Agents, nicht die Auslösenachricht selbst.

Typische Anwendungsszenarien:

Voraussetzungen

• Aufgaben werden nur an Nutzer:innen gesendet, die bereits eine Konversation mit dem Agent geführt haben. Die Plattform ermittelt für jede Nutzer:in die „zuletzt aktive“ Konversation im Zielkanal und fügt die Nachricht in diese Konversation ein. Nutzer:innen ohne Konversationsverlauf erhalten keine Aufgabennachricht (in den Ausführungsdetails als NO_CONVERSATION vermerkt).
• Wenn der Zielkanal eine Drittanbieter-Integration ist (z. B. WhatsApp, Telegram, LINE usw.), stellen Sie sicher, dass die entsprechende Integration unter „Integrations“ korrekt konfiguriert und aktiviert ist. Eine deaktivierte Integration oder ungültige Zugangsdaten führen zu Sendefehlern (CHANNEL_CONFIG_INVALID / CHANNEL_AUTH_FAILED).
• Bei der Ausführung einer Aufgabe wird das LLM des Agents zur Generierung der Antwort aufgerufen; dabei werden wie üblich Credits verbraucht.

Zugang

Öffnen Sie Entwicklungsbereich → Agent → gewünschten Agent auswählen → Menüpunkt „Tasks“ in der linken Seitenleiste.

Die Aufgabenliste unterstützt die Suche nach Aufgabenname sowie das Filtern nach Status (Status), Auslöseart (Trigger) und Zielgruppe (Target). Erläuterung der Listenfelder:

Aufgabe erstellen

Klicken Sie oben rechts auf New task und nehmen Sie die Konfiguration im rechten Seitenbereich vor.

1. Grundinformationen

Hinweis: Bei Auswahl von All users erscheint eine Sicherheitsabfrage, da dies eine Rundsendung an alle Nutzer:innen in sämtlichen Kanälen dieses Agents bedeutet. Vergewissern Sie sich unbedingt, dass der Zeitraum der Zielkonversationen sinnvoll eingestellt ist, um Fehlsendungen zu vermeiden.

Unterstützte Zielkanäle

Tipp: Einige Kanäle unterstützen aufgrund von Einschränkungen des jeweiligen Plattformprotokolls derzeit keine serverseitigen proaktiven Sendungen (z. B. Discord, DingTalk, SoBot); sie werden im Kanal-Dropdown ausgegraut und mit einer Begründung angezeigt. Bei eigenen Kanälen (Web / Widget usw.) wird die Antwort direkt in die Konversation geschrieben und ist sichtbar, sobald die Nutzer:in das Chatfenster das nächste Mal öffnet. Bei IM-Kanälen und Kundenservice-Plattformen wird die Antwort über die API der jeweiligen Plattform proaktiv an die Nutzer:in gesendet.

2. Auslöseart (Trigger)

Die Auslöseart bestimmt, „wann gesendet wird“. Es gibt drei Varianten:

Aktiv – zeitgesteuert (Active - Scheduled)

Die Plattform löst die Sendung gemäß dem festgelegten Zeitplan aus. Geeignet für regelmäßige Meldungen und einmalige Benachrichtigungen.

Die Zeiten werden anhand der für die Aufgabe gewählten Zeitzone berechnet. Nach der Erstellung befindet sich eine zeitgesteuerte Aufgabe im Status WAITING; sobald der erste Ausführungszeitpunkt erreicht ist, wechselt sie zu RUNNING. Eine Once-Aufgabe wechselt nach Abschluss der Ausführung automatisch zu COMPLETED.

Aktiv – ereignisgesteuert (Active - Event)

Ihr Geschäftssystem löst die Aufgabe über einen Webhook-Aufruf an die Plattform aus. Geeignet für die Anbindung an Geschäftsereignisse wie Bestellungen, Zahlungen oder Support-Tickets.

Wählen Sie beim Erstellen der Aufgabe die Authentifizierungsmethode und hinterlegen Sie die Zugangsdaten. Die Plattform generiert automatisch eine eindeutige Webhook-URL (nach der Erstellung in den Aufgabendetails einsehbar):

Beispiel für einen Webhook-Aufruf

Die Webhook-URL hat die Form {Plattform-Domain}/bot/proactive-task/webhook/{webhookPath}. Maßgeblich ist die vollständige Adresse, die in den Aufgabendetails angezeigt wird.

                      
                      POST {Webhook URL}
Content-Type: application/json
Authorization: Basic base64(username:password)

{
  "idempotency_key": "order-20260903-0001",
  "target": {
    "channel": "TELEGRAM",
    "user_id": "customer_123"
  },
  "variables": {
    "order_no": "SO-20260903-0001",
    "eta": "5. September"
  }
}

                    

Hinweis: Eine erfolgreiche Webhook-Anfrage bedeutet lediglich, dass die Anfrage „empfangen und in die Sendewarteschlange aufgenommen“ wurde. Das tatsächliche Sendeergebnis finden Sie im Ausführungsverlauf. Fehlgeschlagene Authentifizierung, eine bereits gestoppte Aufgabe oder ein Zielkanal, der nicht zu den konfigurierten Zielkanälen der Aufgabe gehört, führen zu einem Berechtigungsfehler. Pro Webhook-Adresse gilt ein Limit von 120 Aufrufen pro Minute.

Passiv – nutzerausgelöst (Passive - User Triggered)

Die Plattform prüft einmal pro Minute alle Zielnutzer:innen; für Nutzer:innen, die den Regeln entsprechen, wird die Sendung ausgelöst. Geeignet für Szenarien wie die Reaktivierung inaktiver Nutzer:innen oder die Betreuung besonders wertvoller Nutzer:innen.

Regelkonfiguration

Klicken Sie auf Add rule, um eine Regel hinzuzufügen. Mehrere Regeln lassen sich mit AND (alle müssen zutreffen) oder OR (eine muss zutreffen) verknüpfen.

Erläuterung: Nutzerattribute stammen aus „Variablenverwaltung → Nutzerattribute“ und werden pro Nutzer:in einzeln ausgewertet (hat die Nutzer:in keinen Wert gesetzt, gilt der Standardwert des Attributs); sie eignen sich zur Filterung nach Nutzerprofil. Benutzerdefinierte Attribute stammen aus „Variablenverwaltung → Benutzerdefinierte Variablen“ und sind einheitliche Werte auf Agent-Ebene, die für alle Nutzer:innen gleich sind; sie eignen sich als Bedingungen vom Typ „Hauptschalter“. Alle Regelfelder werden auf Basis der zuletzt aktiven Konversation der jeweiligen Nutzer:in im Zielkanal ausgewertet.

Nachrichtenfrequenz (Message Frequency)

Für passiv ausgelöste Aufgaben muss eine Frequenzbegrenzung festgelegt werden: Innerhalb des eingestellten Zeitfensters (N Stunden / N Tage) wird dieselbe Nutzer:in von dieser Aufgabe höchstens einmal angesprochen. So werden Nutzer:innen, die dauerhaft den Regeln entsprechen, nicht wiederholt gestört.

Tipp: Der Zeitpunkt der letzten Konversation (User's last chat time) liegt in der „Vergangenheit“; verwenden Sie daher Operatoren vom Typ „liegt N Einheiten zurück“. Operatoren vom Typ „N Einheiten ab jetzt“ eignen sich nur für zukünftige Zeitfelder (z. B. das Ablaufdatum eines Abonnements) und treffen beim Zeitpunkt der letzten Konversation niemals zu.

3. Auslösenachricht (Message)

Geben Sie den Nachrichteninhalt ein, der „stellvertretend für die Nutzer:in“ an den Agent gesendet werden soll. Der Agent generiert auf Basis dieser Nachricht sowie seines Prompts, seiner Wissensdatenbank usw. eine Antwort, die anschließend an die Nutzer:in gesendet wird.

Über {{Variable}} können folgende Variablen referenziert werden:

Beispiele

• Regelmäßige Meldung: Bitte fasse für mich in einem kurzen, freundlichen Ton die wichtigsten Branchennachrichten von heute zusammen.
• Reaktivierung inaktiver Nutzer:innen: Ich war seit einigen Tagen nicht mehr hier. Bitte begrüße mich proaktiv und erzähle mir, welche neuen Funktionen es in letzter Zeit gibt.
• Ereignisbenachrichtigung: Meine Bestellung {{event.variables.order_no}} wurde versandt und wird voraussichtlich am {{event.variables.eta}} zugestellt. Bitte teile mir die Versandinformationen mit und erinnere mich daran, den Empfang zu beachten.

Tipp: Die Auslösenachricht ist eine Anfrage „aus Nutzerperspektive“, die an den Agent gerichtet ist, und kein Text, der direkt den Nutzer:innen angezeigt wird. Wenn der Agent den Inhalt möglichst wörtlich wiedergeben soll, fordern Sie dies in der Nachricht ausdrücklich an, z. B. „Bitte teile der Nutzer:in wörtlich mit: …“.

Klicken Sie nach der Überprüfung auf Create.

Hinweis: Pro Agent dürfen sich gleichzeitig höchstens 10 Aufgaben im Status WAITING / RUNNING befinden. Wird diese Grenze überschritten, müssen Sie zunächst bestehende Aufgaben stoppen oder deren Abschluss abwarten.

Aufgabenstatus

Aufgabe und Ausführungsverlauf anzeigen

Klicken Sie in der Liste auf View, um die Aufgabendetails zu öffnen. Diese enthalten zwei Tabs:

• Configuration: Schreibgeschützte Ansicht der Aufgabenkonfiguration. Bei ereignisgesteuerten Aufgaben können Sie hier die Webhook-URL und die Authentifizierungsdaten einsehen.
• Execution History: Protokoll jeder Ausführung mit Ausführungszeitpunkt, Anzahl der Zielnutzer:innen, Anzahl der erfolgreichen / fehlgeschlagenen Sendungen und Erfolgsquote.

Klicken Sie auf eine Ausführung, um die Ausführungsdetails anzuzeigen: Erfolgs- / Fehlerstatistiken pro Kanal sowie die einzelnen Sendeeinträge. Erläuterung der Fehlerursachen:

Stoppen und Löschen

• Stop: Aufgaben im Status WAITING / RUNNING / ERROR können jederzeit gestoppt werden. Nach dem Stoppen wechseln sie zu TERMINATED und können nicht wieder aufgenommen werden.
• Delete: Nur Aufgaben im Status COMPLETED / TERMINATED können gelöscht werden. Beim Löschen werden der Ausführungsverlauf und die Ausführungsdetails ebenfalls entfernt.

Häufige Fragen

F: Warum sehen Nutzer:innen nach erfolgreicher Ausführung der Aufgabe nicht die von mir eingegebene Auslösenachricht?
Die Auslösenachricht ist eine „stellvertretend für die Nutzer:in an den Agent gesendete Anfrage“. Die Nutzer:in sieht die Antwort, die der Agent auf diese Nachricht generiert hat. Wenn Sie den Text exakt steuern möchten, fordern Sie den Agent in der Auslösenachricht ausdrücklich auf, den Inhalt wörtlich auszugeben.

F: Erhalten neue Nutzer:innen Aufgabennachrichten?
Nein. Aufgaben werden nur an Nutzer:innen mit bestehendem Konversationsverlauf gesendet, und die Konversationserstellungszeit muss innerhalb des „Zeitraums der Zielkonversationen“ liegen.

F: Warum wurde eine zeitgesteuerte Aufgabe nicht pünktlich zur vollen Stunde gesendet?
Der Scheduler prüft einmal pro Minute, und große Sendungen werden gemäß dem projektweiten Frequenzlimit in Chargen zugestellt. Der tatsächliche Zustellzeitpunkt kann sich daher leicht verzögern.

F: Der Webhook liefert einen Berechtigungsfehler (Permission deny)?
Prüfen Sie der Reihe nach: ob die Webhook-URL korrekt ist, ob die Authentifizierungsdaten übereinstimmen, ob die Aufgabe bereits gestoppt wurde und ob target.channel in der Anfrage zu den in der Aufgabe konfigurierten Zielkanälen gehört.