Mit diesem Leitfaden können Sie externe Anwendungen mithilfe von Webhooks mit kChat verwalten.

Einleitung

• Ein Webhook ist eine Methode, mit der eine Anwendung sofort über ein bestimmtes Ereignis in einer anderen Anwendung informiert wird, anstatt ständig zu prüfen, ob etwas Neues passiert ist („Polling“).
  • Ausgehender Webhook: kChat übermittelt Informationen an andere Apps, wenn ein Ereignis in kChat auftritt.
  • Eingehender Webhook: kChat empfängt Informationen von anderen Apps, um Aktionen in kChat auszulösen.
• Es ist nicht möglich, den Chatverlauf aus einer anderen Anwendung (Slack, Teams, Jabber usw.) oder aus einer anderen Organisation zu importieren.

⚠ Maximale Anzahl eingehender/ausgehender Webhooks:

Zugriff auf die Webhook-Oberfläche von kChat

Voraussetzungen

• Sie dürfen kein externer Benutzer sein (dieser Benutzer sieht das Menü Integrationen nicht).

Um einen Webhook zu konfigurieren, suchen Sie nach selbst gehosteten oder Drittanbieter-Anwendungen und -Integrationen:

1. Klicken Sie hier, um auf die Web-App kChat zuzugreifen (Online-Dienst unter ksuite.infomaniak.com/kchat) oder öffnen Sie die Desktop-App kChat (Desktop-Anwendung für macOS / Windows / Linux).
2. Klicken Sie auf das Symbol Neu ‍ neben dem Namen Ihrer kChat-Organisation.
3. Klicken Sie auf Integrationen:
   
4. Gehen Sie zu den Kategorien:
   

Spezifische Anleitungen

Beispiele für Integrationen in kChat:

• Kalender Infomaniak: Ereigniserinnerung in kChat anzeigen
• Anwendung n8n: Senden einer Nachricht in kChat auslösen

Anleitungen für andere Anwendungsfälle

So erstellen Sie einen eingehenden Webhook (um ein externes Ereignis in kChat anzuzeigen):

1. Klicken Sie auf die Kategorie Eingehende Webhooks.
2. Klicken Sie auf den blauen Button Eingehende Webhooks hinzufügen:
   
3. Fügen Sie einen Namen und eine Beschreibung für den Webhook hinzu.
4. Wählen Sie den Kanal aus, der die Nachrichten empfangen soll.
5. Klicken Sie auf den Button Speichern:
   
6. Die URL, die Sie für Ihre Entwicklungen verwenden können, wird angezeigt (diese sollten Sie nicht öffentlich preisgeben); Beispiel: „https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx“:
   

Verwendung des Webhooks

Kurzes Beispiel

1. Ein bestimmter curl-Befehl (detaillierter weiter unten) wird in einem Terminal eingegeben.
2. Der Befehl enthält die URL, die in Schritt 6 oben ermittelt wurde.
3. Der Befehl führt dazu, dass eine Nachricht in dem in Schritt 4 oben angegebenen Kanal gepostet wird:
   

Details

In der Anwendung, die Nachrichten an kChat senden soll:

1. Passen Sie den folgenden Code an die in kChat erhaltene URL an:

   POST /hooks/xxx-key-generated-xxx HTTP/1.1
   Host: your-server-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   {
       "text": "Hallo, Text1\nText2."
   }

2. Verwenden Sie gegebenenfalls die gleiche Anfrage, aber mit curl (um sie von einer Terminal-Anwendung (Befehlszeilenschnittstelle, CLI /Command Line Interface) auf Ihrem Gerät aus zu testen), wie im obigen Bildbeispiel:

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hallo, Text1\nText2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

Wenn kein Content-Type-Header festgelegt ist, muss der Anfragetext mit payload= beginnen, z. B.:

payload={"text": "Hello, text1\nText2."}

Eine erfolgreiche Anfrage erhält die folgende Antwort:

HTTP/1.1 200 OK	
Content-Type: application/json	
X-Version-Id: 4.7.1.dev.12799dvd77e172e8a2eba0f4041ec1471.false	
Date: Sun, 01 Jun 2023 17:00:00 GMT	
Content-Length: 58	
	
{	
    "id":"x",	
    "create_at":1713198308869,	
    "update_at":1713198308869,	
    "delete_at":0,	
    "user_id":"x",	
    "channel_id":"x",	
    "root_id":"",	
    "original_id":"",	
    "participants":null,	
    "message":"test",	
    "type":"",	
    "props":{	
        "override_username":"webhook",	
        "override_icon_url":null,	
        "override_icon_emoji":null,	
        "webhook_display_name":"test",	
        "attachments":[	
	
        ],	
        "card":null,	
        "from_webhook":"true"	
    },	
    "hashtags":null,	
    "metadata":{	
        "embeds":[	
            {	
                "type":"message_attachment"	
            }	
        ],	
        "files":[	
	
        ],	
        "reactions":[	
	
        ]	
    },	
    "file_ids":null,	
    "has_reactions":false,	
    "edit_at":0,	
    "is_pinned":false,	
    "remote_id":null,	
    "reply_count":0,	
    "pending_post_id":null,	
    "is_following":false	
}

Wenn Sie das gleiche Antwortformat wie bei Slack wünschen:

HTTP/1.1 200 OK
Content-Type: text/plain
X-Request-Id: hoan69ws7rp5xj7wu9rmystry
X-Version-Id: 4.7.1.dev.12799dvd77e172e8a2eba0f4041ec1471.false
Date: Sun, 01 Jun 2023 17:00:00 GMT
Content-Length: 2
ok

Sie müssen ?slack_return_format=true zur URL des Webhooks hinzufügen.

Parameter

Zusätzlich zum Feld text finden Sie hier die vollständige Liste der unterstützten Parameter:

Codebeispiel mit Parametern

Hier erfahren Sie, wie Sie eine umfassendere Nachricht mit Parametern erstellen können, von denen einige Parameter ersetzen können, die bereits bei der Erstellung des Webhooks festgelegt wurden (Benutzername, bevorzugter Kanal, Avatar usw.), wie in der obigen Tabelle dargestellt:

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "https://cdn-icons-png.flaticon.com/512/5971/5971593.png",
  "text": "### System Status Report\nEnvironment: PRODUCTION\nStatus: SUCCESSFUL\n\n---\n\n| Component | Version | Build ID | Status |\n|:----------|:-------:|:---------|:-------|\n| API-Core  | 2.4.1   | #88421   | OK     |\n| Web-UI    | 1.9.0   | #88425   | OK     |\n| Database  | 14.5    | N/A      | OK     |\n\n---\n\n**Commit Reference:**\n`git-ref: a7f8e9c21b` \n\n**Summary:**\nAll automated integration tests passed successfully. No manual intervention is required. Please contact the DevOps team for further details regarding this release."
}' \
https://faq-infomaniakaruh.kchat.infomaniak.com/hooks/019c23e9-a9a8-735c-b6ce-0a69df63aaf0

Ergebnis eines ähnlichen Beispiels in Form eines Bildes: