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

Einleitung

• Ein Webhook ist eine Methode, mit der eine Anwendung sofort darüber informiert wird, wenn ein bestimmtes Ereignis in einer anderen Anwendung auftritt, anstatt diese Anwendung ständig zu fragen, 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 von einer anderen Anwendung (Slack, Teams, Jabber usw.) oder von einer anderen Organisation zu importieren.
• Maximale Anzahl eingehender/ausgehender Webhooks:
  • kSuite Free = 1 / 1
  • kSuite Standard = 20 / 20
  • kSuite Business = unbegrenzt
  • kSuite Enterprise = unbegrenzt

Zugriff auf die kChat-Webhooks-Oberfläche

Voraussetzungen

• Kein externer Benutzer (dieser Benutzer sieht das Menü Integrationen nicht).

Um einen Webhook zu konfigurieren, finden Sie Anwendungen und Integrationen, die selbst gehostet oder von Drittanbietern bereitgestellt werden:

1. Klicken Sie hier, um die Web-App kChat (Online-Dienst unter ksuite.infomaniak.com/kchat) aufzurufen, 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. Greifen Sie auf die Kategorien zu:
   

Spezifische Anleitungen

Beispiele für Integrationen in kChat:

• Kalender Infomaniak: Ereigniserinnerung in kChat anzeigen
• Anwendung n8n: Auslösen des Versands einer Nachricht in kChat

Anleitungen für andere Anwendungsfälle

Um einen eingehenden Webhook zu erstellen (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 die Schaltfläche, um zu speichern:
   
6. Die URL, die Sie für Ihre Entwicklungen verwenden können, wird angezeigt (diese sollte nicht öffentlich bekannt gegeben werden); Beispiel: „https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx“:
   

Verwendung des Webhooks

Kurzes Beispiel

1. Ein präziser curl-Befehl (detaillierter weiter unten) wird in ein 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 veröffentlicht wird:
   

Details

In der Anwendung, die Beiträge in kChat veröffentlichen soll:

1. Passen Sie den folgenden Code entsprechend der in kChat erhaltenen URL an:

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

2. Verwenden Sie gegebenenfalls dieselbe Anfrage, aber mit curl (um sie von einer Anwendung wie Terminal (Befehlszeilenschnittstelle, CLI) auf Ihrem Gerät aus zu testen), wie im obigen Beispielbild:

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' {{URL_12}}

Wenn kein Content-Type-Header festgelegt ist, muss der Anfragetext mit payload= beginnen, wie folgt:

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

Eine erfolgreiche Anfrage liefert 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 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:

Beispielcode mit Parametern

Hier erfahren Sie, wie Sie eine umfassendere Nachricht mit Parametern erstellen können, wobei einige Parameter bereits bei der Erstellung des Webhooks festgelegte Parameter ersetzen können (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": "{{URL_13}}",
  "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."
}' \
{{URL_14}}

Ergebnis eines ähnlichen Beispiels in der Abbildung: