Dieser Leitfaden hilft Ihnen, externe Anwendungen mit kChat mithilfe von Webhooks zu verwalten.

Vorwort

• Ein Webhook ist eine Methode, mit der eine Anwendung sofort benachrichtigt 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 Verlauf von Gesprächen aus einer anderen Anwendung (Slack, Teams, Jabber, etc.) oder aus einer anderen Organisation zu importieren.

⚠ Max. Anzahl der eingehenden/ausgehenden Webhooks:

Auf die kChat-Webhook-Schnittstelle zugreifen

Voraussetzungen

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

Um einen Webhook zu konfigurieren, finden Sie selbstgehostete oder Drittanbieter-Anwendungen und -Integrationen:

1. Hier klicken‍‍ um auf die Web-App kChat (Online-Dienst ksuite.infomaniak.com/kchat) zuzugreifen oder öffnen Sie die Desktop-App kChat (Desktop-Anwendung auf 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 die Integration in kChat:

• Calendar Infomaniak: Erinnerung an ein Ereignis in kChat anzeigen
• Anwendung n8n: Senden einer Nachricht in kChat auslösen

Anleitungen für andere Verwendungen

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 die blaue Schaltfläche 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 erhält.
5. Klicken Sie auf die Schaltfläche zum Speichern:
   
6. Die URL, die Sie für Ihre Entwicklungen speichern müssen, wird angezeigt (nicht öffentlich weitergeben); Beispiel: „https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx“:
   

Verwendung des Webhooks

Schnelles Beispiel

1. Ein genauer Befehl curl (weiter unten detailliert) wird in ein Terminal eingegeben.
2. Der Befehl enthält die im Punkt 6 oben erhaltene URL.
3. Der Befehl hat zur Folge, dass eine Nachricht im im Punkt 4 oben angegebenen Kanal gepostet wird:
   

Details

In der Anwendung, die in kChat posten 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 in curl (um von einer Anwendung vom Typ Terminal (Kommandoschnittstelle, CLI / Command Line Interface) auf Ihrem Gerät zu testen), wie im obigen Bildbeispiel: 

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

Wenn kein Header Content-Type definiert ist, muss der Anfragekörper mit payload= beginnen, wie folgt:

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 dasselbe Antwortformat wie Slack haben möchten:

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

müssen Sie ?slack_return_format=true zur Webhook-URL hinzufügen.

Parameter

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

Codebeispiel mit Parametern

So können Sie eine umfassendere Nachricht mit Parametern erstellen, wobei einige Parameter bereits beim Erstellen des Webhooks festgelegte Parameter (Benutzername, bevorzugter Kanal, Avatar usw.) ersetzen können, wie in der obigen Tabelle angegeben:

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 Bildform: