Channels einrichten

Für die Verwaltung dieses Dienstes. Nutze ein Konto mit den unten genannten Rechten.

Einen Channel hinzufügen

Ein Administrator fügt einen Channel hinzu. Er braucht write auf Channel.

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commandKey":"channel-team-slack-1","name":"Team Slack","bot":"bot_...","linkPath":"/link","credentials":{"kind":"slack","botToken":"xoxb-...","signingSecret":"..."}}' \
  https://api.example.com/v1/organization/channels

Feld	Was es tut
`name`	Ein kurzer Name.
`bot`	Der Bot, der antwortet. Er muss ein gemeinsamer Bot der Organisation sein.
`credentials`	Die Geheimnisse der Plattform. Siehe unten. Sie gehen hinein, kommen aber nie heraus. Die Antwort zeigt nur `set` und einen `hint`.
`linkPath`	Optional. Ein Pfad auf deinem öffentlichen Origin, auf dem dein Client eine Person ihr Konto verknüpfen lässt.
`enabled`	Optional. `false` stoppt den Channel. Sein Webhook gibt dann `401` zurück.

Die Antwort ist 201 mit dem Channel. Gib seine webhookUrl an die Plattform. Der Aufrufer wird der Actor des Channel. Die Chats des Channel sind Chats des Actors. Der Actor muss dem Bot Arbeit geben können.

GET, PATCH und DELETE /v1/organization/channels/:channelId lesen, ändern und löschen einen Channel. Eine Änderung braucht expectedVersion, die version, die du gelesen hast. Eine alte Version gibt 409 mit ChannelConflict zurück. Eine Änderung macht den Aufrufer zum Actor. Lass credentials weg, um die Geheimnisse zu behalten. Die Art eines Channel lässt sich nicht ändern.

Befehle zum Anlegen und Ändern brauchen einen commandKey. Behalte ihn, wenn ein Netzaufruf fehlschlägt und du denselben Befehl erneut sendest. Ein neuer Schlüssel steht für einen neuen Befehl. Channels.create, Channels.update und Channels.rotateSecret im SDK erzeugen den Schlüssel einmal. Nutze den zurückgegebenen send-Effect erneut für einen neuen Versuch.

Die executionId des Channel nennt seine Konfigurationsarbeit. 201 bedeutet, dass Konfiguration und Arbeit zusammen gespeichert sind. Lies /v1/executions/:executionId oder abonniere seine Ereignisse für das Ergebnis. Bei einer Ablehnung durch die Plattform bleibt der Channel erhalten. Die Ausführung zeigt einen sicheren Fehler. Bei einer verlorenen oder unklaren Antwort wartet outcome_unknown auf eine Entscheidung. Spätere Änderungen warten auf das Ende der vorigen Arbeit, auch nach einem Neustart.

Ein neuer geheimer Schlüssel braucht auch commandKey und expectedVersion. Die Antwort enthält secret und channel. Ein erneuter Versuch desselben Befehls gibt denselben Schlüssel und dieselbe Version zurück. Er erzeugt keinen weiteren Schlüssel. Halte das Ergebnis geheim.

Bei einer bestätigten Ablehnung wegen zu vieler Aufrufe gibt es höchstens fünf Versuche. OpenBot speichert die Wartezeit und behält sie nach einem Neustart. Vor jedem Versuch prüft es die aktuellen Rechte. Eine verlorene Antwort erlaubt diesen neuen Versuch nicht. Lark erhält bei jedem Versuch denselben Nachrichtenschlüssel. Lark hält ihn eine Stunde lang. Ein unbekanntes Ergebnis braucht daher weiter eine Entscheidung.

Ein Löschbefehl braucht einen Body mit commandKey. Er gibt 202 und einen Ausführungsbeleg zurück. Channels.remove im SDK erzeugt den Schlüssel einmal. Der Channel nimmt sofort keine neuen Eingaben und Änderungen mehr an. Die Löschung wartet, bis alle gespeicherten Eingaben, Beobachter, Sendungen und Konfigurationen ihre Arbeit beendet und ihre Ressourcen freigegeben haben. Erst dann werden der Channel und seine Verknüpfungen gelöscht. Chats und Ausführungshistorie bleiben. Bei einem unbekannten externen Ergebnis braucht diese Ausführung weiter eine Entscheidung. Die Löschung wartet darauf. Das Schließen des Ereignisstroms bricht die Löschung nicht ab. Ein ausdrücklicher Abbruch lässt den Channel ausgeschaltet. Eine spätere Änderung kann ihn einschalten.

Nach einem Daten-Upgrade kann ein alter Channel needsAuthorization: true zeigen. Einstellungen, Geheimnisse, Links und Verlauf bleiben erhalten. Auch enabled bleibt gleich. Der Channel nimmt aber keine Eingaben an und startet keine Sende- oder Beobachtungsaufgaben. Ein Administrator muss eine Änderung speichern oder das Geheimnis wechseln. Das setzt einen neuen Aufrufer mit aktuellen Rechten und löscht needsAuthorization. Alte Arbeit mit unbekanntem Ergebnis wartet weiter auf eine Entscheidung. Neue Einstellungen spielen sie nicht erneut ab.

Slack

credentials: { "kind": "slack", "botToken": "xoxb-...", "signingSecret": "..." }

Schalte in der Slack-App Event Subscriptions ein, mit der webhookUrl als Request-URL. Füge die Bot-Events app_mention und message.im hinzu.
Schalte Interactivity mit derselben webhookUrl ein, damit die Buttons des Bots funktionieren.
Gib dem Bot die Scopes chat:write, app_mentions:read und im:history.

OpenBot prüft die X-Slack-Signature jedes Requests. Ein Request, der älter als 5 Minuten ist, wird abgelehnt.

Lark

credentials: { "kind": "lark", "domain": "feishu", "appId": "cli_...", "appSecret": "...", "verificationToken": "...", "encryptKey": "..." }

domain ist feishu für Feishu in China und lark für Lark an anderen Orten. Lege in der Lark-App einen Encrypt Key fest und nutze die webhookUrl als Request-URL für Events und für Karten-Callbacks. Füge das Event im.message.receive_v1 hinzu. OpenBot prüft die Signatur und das Verification Token jedes Events.

credentials: { "kind": "telegram", "botToken": "123456:..." }

OpenBot ruft setWebhook für dich auf, mit einem eigenen Geheimnis. Telegram schickt dieses Geheimnis mit jedem Update zurück. In einer Gruppe bekommt der Bot nur Nachrichten, die ihn nennen oder ihm antworten, außer du schaltest seinen Privacy Mode aus.

Ausführungsprüfungen

Channel-Einstellungen halten den vollständigen Aufrufer samt API-Token der Änderung. Die Token-Grenzen gelten weiter für spätere Arbeit. Prüfe Token und Member-Rechte, wenn ein Channel nach einer Rechteänderung stoppt.

Eingaben, Antworten und Karten haben Ausführungsdatensätze. Ein unbekanntes Sendeergebnis wartet auf eine Entscheidung über die Ausführungs-API. Prüfe die Plattform vor einem neuen Versuch. Ein Neustart trifft diese Entscheidung nicht. Alte Channel-Queue-Daten müssen vor dem Start des neuen Servers die Datenumwandlung im Wartungsfenster durchlaufen.