Trigger

Für Entwickler, die einen Client mit OpenBot verbinden oder den Server erweitern. Die Beispiele brauchen die auf dieser Seite genannten Rechte. Beginne mit dem Entwicklerhandbuch.

Ein Trigger (Auslöser) gibt einem Bot eine Aufgabe mit einem Prompt. Er löst nach einem Zeitplan aus, über einen Webhook oder beides. Mehr tut er nicht: Der Bot entscheidet, wie er die Arbeit macht. Er kann zuerst planen, eine Todo-Liste führen und Arbeit an andere Bots geben. Wenn die Aufgabe endet, geht ihr Ergebnis in deinen Chat mit dem Bot.

Einen Trigger erstellen

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Check the open issues and sum them up.","schedule":{"cron":"0 9 * * 1-5","timeZone":"Europe/Berlin"}}' \
  https://api.example.com/v1/triggers

Feld	Was es tut
`prompt`	Die Aufgabe.
`bot`	Optional. Der Bot, der die Arbeit macht. Ohne ihn macht dein Standard-Bot sie.
`schedule`	Optional. Wann der Trigger von selbst auslöst.
`shared`	Optional. `true` erstellt einen gemeinsamen Trigger, der der Organisation gehört.
`enabled`	Optional. `false` verhindert, dass der Trigger auslöst. Der Standard ist `true`.

Die Antwort ist 201 mit dem Trigger. Er hat nextRunAt, die nächste Zeit, zu der der Zeitplan auslöst, und lastFiredAt.

GET /v1/triggers listet deine Trigger und die gemeinsamen auf. GET, PATCH und DELETE /v1/triggers/:triggerId lesen, ändern und löschen einen. Eine Änderung braucht expected, die revision, die du gelesen hast. Eine alte Revision gibt 409 mit TriggerConflict zurück.

Was ein Auslösen tut

Jedes Auslösen gibt die Aufgabe als Delegation an den Bot. Die Arbeit läuft in einem neuen Task-Chat des Bots. Seine erste Eingabe ist der Prompt, von “einem Trigger”. Die Delegation hat trigger mit der ID des Triggers.

Wenn die Arbeit endet, geht ihr Ergebnis als Mitteilung in den direkten Chat des Actors mit dem Bot. OpenBot erstellt diesen Chat, wenn es ihn noch nicht gibt. So liest der Bot das Ergebnis dort, und er kann dem Actor davon erzählen oder mit der Arbeit weitermachen. Das Audit-Log zeichnet trigger.fired mit der ID der Delegation in details.delegation auf.

Um die Arbeit eines Triggers zu finden, lies GET /v1/chats/:chatId/delegations für diesen direkten Chat, oder liste die Task-Chats des Bots mit GET /v1/chats?kind=task&bot=<id> auf.

Zeitpläne

Ein Zeitplan hat einen cron-Text mit fünf Feldern, zum Beispiel 0 9 * * 1-5 für 9:00 Uhr an Werktagen. timeZone ist eine IANA-Zeitzone, zum Beispiel Europe/Berlin. Ohne sie ist die Zeitzone UTC. Ein ungültiger cron-Text gibt 400 mit TriggerInvalid zurück. Ein cron-Text, der nie auslöst, zum Beispiel 0 0 30 2 * (30. Februar), gibt denselben Fehler zurück.

Die executionId des Triggers nennt den gespeicherten Timer. Ohne Timer ist sie null. Der Timer übersteht einen Neustart. Ein überfälliger Timer startet eine Aufgabe und setzt die nächste Zeit. Aufgabe, Audit-Eintrag und nächster Timer werden in einer Transaktion gespeichert. Eine Änderung ersetzt den Timer. Bereits gestartete Aufgaben laufen weiter. Ein fehlgeschlagener Timer behält seine Fehler-ID. Behebe die Ursache und ändere den Trigger für einen neuen Versuch.

Webhooks

PUT /v1/triggers/:triggerId/webhook erstellt ein Webhook-Geheimnis. OpenBot zeigt es nur einmal:

{
  "url": "https://api.example.com/v1/hooks/triggers/trg_4c1e...",
  "secret": "otg_..."
}

Ein anderes System löst den Trigger mit dem Geheimnis aus:

curl -H "Authorization: Bearer $WEBHOOK_SECRET" \
  -H "Idempotency-Key: issue-42" \
  -H "Content-Type: application/json" \
  -d '{"issue": 42}' \
  https://api.example.com/v1/hooks/triggers/trg_4c1e...

Die Antwort ist 202 mit delegation, executionId, commandKey und sequence. Sende für jeden Aufruf einen festen Idempotency-Key. Nutze nach einer verlorenen Antwort denselben Schlüssel und Inhalt. Anderer Inhalt mit demselben Schlüssel ergibt 409 ExecutionKeyConflict. Die Execution-API liefert Ereignisse und nimmt den Abbruch an. Das SDK Triggers.fire erstellt einen Schlüssel. Behalte den zurückgegebenen Befehl und wiederhole command.send. Der JSON-Body geht mit der Aufgabe an den Bot. OpenBot markiert ihn als Daten eines anderen Systems, nicht als Anweisung. Ein falsches Geheimnis, ein Trigger ohne Webhook oder ein abgeschalteter Trigger gibt 401 mit TriggerHookDenied zurück.

Ein neues PUT erstellt ein neues Geheimnis, und das alte funktioniert nicht mehr. DELETE /v1/triggers/:triggerId/webhook entfernt den Webhook.

Darf der Akteur dem Bot keine Arbeit mehr geben, oder ist der Bot archiviert, kommt 403 ExecutionForbidden. Ein Fehler im Ausführungsspeicher ergibt 503 ExecutionUnavailable mit einer sicheren Fehler-ID.

Für wen die Arbeit ist

Die Arbeit eines Triggers ist für seinen Actor: das letzte Member, das den Trigger oder seinen Webhook erstellt oder geändert hat. Eine Änderung macht dich also zum Actor. Der Task-Chat gehört dem Actor, und das Ergebnis geht in den Chat des Actors. Der Actor muss dem Bot Arbeit geben können. Wenn er das nicht mehr kann, löst der Trigger nicht aus.

Der gespeicherte Aufrufer behält den ursprünglichen Token und seine Grenzen. Jeder Schritt prüft die aktuellen Rechte. Ein widerrufener Token kann keine Arbeit starten oder fortsetzen. Prompts und Webhook-Daten werden verschlüsselt gespeichert. Der Bot fragt mit Requests nach neuen Fähigkeiten. Die Requests gehen an den Actor.

Nach einem Daten-Upgrade kann ein Trigger needsAuthorization: true zeigen. Prompt, Zeitplan, nächste Zeit und Aktivierung bleiben erhalten. Timer und Webhook können aber keine Arbeit starten. Speichere eine Änderung mit aktuellen Rechten, um einen neuen Aufrufer zu setzen und diesen Zustand zu löschen. Der neue Timer nutzt die nächste Zeit nach der Änderung. Alte Arbeit behält ihren Status. Sie startet nicht erneut als neuer Aufrufer.

Berechtigungen

Aktion auf `Trigger`	Was sie erlaubt
`read`	Trigger lesen: ihre Zeitpläne und Webhooks.
`write`	Trigger erstellen, ändern und löschen und ihre Webhook-Geheimnisse festlegen.

Der Pfad deiner eigenen Trigger ist org / <org> / user / <you> / trigger / <id>. Ein gemeinsamer Trigger hat owner: { "_tag": "Organization" }. Ein persönlicher Trigger hat owner: { "_tag": "Member", "userId": "<member id>" }. Jedes Member kann die gemeinsamen Trigger lesen. Administratoren können sie ändern. Die Liste enthält nur die Trigger, die du lesen darfst. Siehe Berechtigungen.