Ein Feishu Channel gibt Agenten in einer Organisation eine einzelne Hotline in eine Feishu-Gruppe: ausgehende Benachrichtigungen, eingehende Antworten und interaktive Genehmigungskarten (über den feishu_gate Hook).
Diese Anleitung führt Sie durch das End-to-End-Setup. Sie setzt voraus, dass FIM One unter einer stabilen HTTPS-Adresse erreichbar ist — nennen Sie diese API_BASE_URL (z. B. https://one.yourdomain.com).
1. Erstelle eine Feishu-App
- Gehe zur Feishu Open Platform und klicke auf Create custom app for enterprise.
- Gib einen Namen, ein Symbol und eine kurze Beschreibung ein — Endbenutzer deiner Organisation sehen diese auf Karten.
- Auf der Seite Credentials & Basic Info kopiere die App ID und das App Secret. Du wirst sie in Schritt 4 in FIM One einfügen.
Behandle das App Secret wie ein Passwort. FIM One verschlüsselt es im Ruhezustand, aber jeder, der eine Klartextkopie hat, kann den Bot imitieren.
2. Berechtigungen erteilen
Aktivieren Sie unter Permissions & Scopes die folgenden Bereiche und reichen Sie die Berechtigungsversion ein:
| Bereich | Grund |
|---|
im:message | Nachrichten senden (Text + Karten) |
im:message:send_as_bot | Als Bot-Identität posten |
im:chat | Gruppenchats auflisten und lesen, in denen sich der Bot befindet |
im:chat:readonly | Minimaler Lesezugriff für Gruppenerkennung |
im:resource | (Optional) Bilder/Dateien hochladen, die auf Karten angezeigt werden |
3. Event-Abonnements aktivieren (Request URL vorerst leer lassen)
Öffnen Sie Event Subscriptions, aber füllen Sie die Request URL noch nicht aus — Sie erhalten sie in Schritt 5 von FIM One.
Abonnieren Sie die folgenden Events:
im.message.receive_v1 — eingehende Nachrichten von Benutzerncard.action.trigger — Klicks auf Approve / Reject Schaltflächen
Auf der gleichen Seite können Sie optional ein Verification Token und Encrypt Key festlegen. FIM One unterstützt beide Modi und verwendet denjenigen, der bereitgestellt wird.
4. Kanal in FIM One hinzufügen
-
Melden Sie sich als Org Owner oder Admin an.
-
Gehen Sie zu Organization Settings → Channels → New Channel.
-
Wählen Sie Feishu als Typ und füllen Sie folgende Felder aus:
| Feld | Quelle |
|---|
| Name | Beliebige interne Bezeichnung (z. B. Ops team Feishu) |
| App ID | Aus Schritt 1 (cli_xxxxxxxxxxxxxxxx) |
| App Secret | Aus Schritt 1 |
| Verification Token | (Optional) Aus Schritt 3 |
| Encrypt Key | (Optional) Aus Schritt 3 |
-
Klicken Sie auf Browse chats — FIM One ruft Feishu mit Ihren Anmeldedaten auf und listet alle Gruppen auf, denen der Bot derzeit angehört.
Wenn die Liste leer ist, wurde der Bot noch zu keiner Gruppe hinzugefügt. Öffnen Sie Feishu, fügen Sie den Bot zur Zielgruppe hinzu und öffnen Sie dann die Auswahl erneut.
- Wählen Sie den Gruppenchat aus, zu dem Sie weiterleiten möchten, und klicken Sie auf Save.
5. Callback-URL bei Feishu registrieren
Nach dem Speichern zeigt FIM One eine Callback URL im Kanal-Detailbereich an, die wie folgt aussieht:
{API_BASE_URL}/api/channels/{CHANNEL_ID}/callback
url_verification-Herausforderung per POST; FIM One antwortet automatisch.
6. Testnachricht senden
Klicken Sie im FIM One-Kanal-Detailbereich auf Send test message. Eine kurze Klartextnachricht (FIM One test message from <your email>) sollte innerhalb einer Sekunde in der Zielgruppe erscheinen.
Falls nicht:
- 401 / 403 — überprüfen Sie App Secret erneut, aktivieren Sie die Bereiche aus Schritt 2 erneut, und veröffentlichen Sie die Berechtigungsversion erneut.
- Stille Fehler — bestätigen Sie, dass der Bot tatsächlich in der Gruppe ist (Schritt 4 Picker) und dass
is_active in der Kanalzeile true ist.
- Verifizierung schlägt in Schritt 5 fehl — bestätigen Sie, dass
API_BASE_URL HTTPS ist und öffentlich erreichbar ist; Feishu lehnt Anfrage-URLs ohne HTTPS ab.
7. Einen Agenten verbinden (optional — Genehmigungen)
Um Tool-Aufrufe hinter Gruppengenehmigungen zu sperren:
- Aktivieren Sie bei der Tool- / Connector-Aktion Requires confirmation.
- Fügen Sie beim Agenten
feishu_gate unter Hooks → Class hooks hinzu.
- Stellen Sie sicher, dass die Organisation des Agenten genau einen aktiven Feishu-Kanal hat — der Hook leitet automatisch dorthin weiter.
Wenn der Agent versucht, ein gesperrtes Tool auszuführen, wird eine interaktive Karte in der Gruppe mit Approve / Reject gepostet. Das Tool wartet (SSE-Stream wird pausiert), bis ein Mitglied auf eine der Optionen tippt; das Ergebnis wird zurückgestreamt und der Agent wird entweder abgeschlossen oder abgebrochen.
Fehlerbehebung
Eine chat_id ohne den Picker finden
Die Browse chats UI ist der empfohlene Workflow. Wenn Sie die rohe ID benötigen (z. B. für einen POST /api/channels Aufruf aus Scripting), gibt es drei Fallbacks:
a. curl direkt gegen Feishu
APP_ID="cli_xxxxxxxxxxxxxxxx"
APP_SECRET="<your-app-secret>"
TOKEN=$(curl -s -X POST \
"https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
-H "Content-Type: application/json" \
-d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" \
| python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")
curl -s "https://open.feishu.cn/open-apis/im/v1/chats?page_size=50" \
-H "Authorization: Bearer $TOKEN" | python3 -m json.tool
items[].chat_id in der Antwort (mit Präfix oc_) ist ein Kandidat.
b. Feishu API Explorer
In der Feishu Open Platform Konsole öffnen Sie Dev Tools → API Explorer, suchen Sie /open-apis/im/v1/chats, wählen Sie tenant_access_token Authentifizierung und klicken Sie auf Invoke. Feishu generiert das Token für Sie — keine Shell erforderlich.
c. Aus dem Feishu Client kopieren
Im Feishu Desktop- oder Mobile-Client öffnen Sie die Gruppe → Gruppeneinstellungen → Gruppeninfo, und einige Versionen bieten eine Copy group ID Funktion. Die Verfügbarkeit hängt von der Client-Version und den vom Administrator festgelegten Berechtigungen ab, daher ist dies der am wenigsten zuverlässige Fallback.
Card-Klicks erreichen FIM One nicht (Fehler 200340)
Wenn das Klicken auf Genehmigen oder Ablehnen auf einer Karte 出错了，请稍后重试 code: 200340 im Feishu-Client erzeugt, arbeiten Sie diese Liste ab:
card.action.trigger muss abonniert sein (Schritt 3). Wenn Sie Genehmigungsgates aktiviert haben, bevor Sie abonniert haben, klicken Sie auf Erneut abonnieren in der Feishu-Konsole.- Speichern Sie die Callback-URL erneut. Feishu speichert manchmal einen veralteten Abonnementzustand zwischen, der Neustarts übersteht — selbst wenn der URL-Verifizierungs-Handshake noch funktioniert, kann das Event-Routing stillschweigend stoppen. Öffnen Sie die Event-Abonnementseite in der Feishu Open Platform, geben Sie die exakte gleiche Callback-URL erneut ein, und klicken Sie erneut auf Speichern / Verifizieren. Die URL wird in einer Roundtrip erneut verifiziert und Live-Button-Klicks beginnen beim nächsten Drücken zu fließen. Dies ist die häufigste Lösung, wenn der Kanal gestern funktioniert hat, aber heute ohne Code-Änderung gestoppt hat.
- Überprüfen Sie den Event Debugger in der Feishu Open Platform (
事件与回调 → 事件调试). Jeder Button-Druck sollte dort mit dem Lieferstatus (2xx / 4xx / 未投递) angezeigt werden. Wenn Sie 未投递 sehen, lehnt Feishu das Event selbst ab, bevor es gesendet wird — normalerweise ein fehlender Scope oder ein deaktiviertes Abonnement.
- Scope-Überprüfung. Stellen Sie in
权限管理 sicher, dass die App die Scopes im:message und alle card-bezogenen Scopes hat, die Ihr Mandant benötigt. Ein fehlender Scope manifestiert sich dadurch, dass das Abonnement in der UI grün angezeigt wird, aber Events bei der Lieferung stillschweigend gelöscht werden.
Approve/Reject-Schaltflächen können wiederholt angeklickt werden
Der Webhook gibt jetzt beim ersten Entscheidungsfall eine Ersatzkarte zurück – die Schaltflächen werden entfernt und die Kartenüberschrift wechselt zu Grün (genehmigt) oder Rot (abgelehnt). Falls Sie nach dem ersten Klick immer noch anklickbare Schaltflächen sehen, zeigt Ihr Feishu-Client möglicherweise eine zwischengespeicherte Kopie an; öffnen Sie den Chat erneut und die entschiedene Karte wird korrekt angezeigt.
Eine Organisation, zwei Feishu-Kanäle
feishu_gate wählt den ersten aktiven Kanal aus, den es findet. Wenn Sie mehrere Feishu-Endpunkte in derselben Organisation benötigen (z. B. Staging- vs. Produktionsgruppen), deaktivieren Sie alle bis auf einen, oder schreiben Sie einen benutzerdefinierten Hook, der nach Agent-Tag auswählt. 
