Externe Anwendungen mit kChat verbinden

Dieser Leitfaden ermöglicht es Ihnen, externe Anwendungen mit kChat mithilfe von Webhooks zu verwalten.

Einleitung

• Ein Webhook ist eine Methode, die es einer Anwendung ermöglicht, sofort benachrichtigt zu werden, wenn ein bestimmtes Ereignis in einer anderen Anwendung eintritt, anstatt ständig zu fragen, ob etwas Neues passiert ist (bekannt als "Polling").
• Es ist nicht möglich, den Chatverlauf aus einer anderen Anwendung (Slack, Teams, Jabber usw.) oder aus einer anderen Organisation zu importieren.
• Ausgehender Webhook: kChat kommuniziert Informationen an andere Apps, wenn in kChat ein Ereignis eintritt.
• Eingehender Webhook: kChat erhält Informationen von anderen Apps, um Aktionen in kChat auszulösen.

Zugriff auf die kChat-Webhooks-Oberfläche

Voraussetzungen

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

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

1. Öffnen Sie die kChat-App (auf Ihrem Gerät oder über einen Browser unter der URL kchat.infomaniak.com).
2. Klicken Sie auf den Chevron ‍ neben dem Namen Ihrer kChat-Organisation.
3. Klicken Sie auf Integrationen
   
    
4. Greifen Sie auf die Kategorien zu:
   

Integrationsbeispiel

• Infomaniak-Kalenderereignisbenachrichtigung auf kChat

Erstellen Sie einen einfachen eingehenden Webhook

Dazu:

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 (max. 500 Zeichen) für den Webhook hinzu.
4. Wählen Sie den Kanal aus, der die Nachrichten erhalten soll.
5. Speichern Sie, um die URL zu erhalten (nicht öffentlich bekannt geben) vom Typ:
   https://your-kchat-server.xyz/hooks/xxx-generierte-schlüssel-xxx

Verwendung des Webhooks

In der Anwendung, die auf kChat posten soll:

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

   POST /hooks/xxx-generierte-schlüssel-xxx HTTP/1.1
   Host: your-kchat-server.xyz
   Content-Type: application/json
   Content-Length: 63
   
   {
       "text": "Hallo, dies ist ein Text\nDies ist ein weiterer Text."
   }

2. Optional können Sie die gleiche Anfrage, jedoch in curl verwenden (um von einem Terminal unter macOS zu testen, zum Beispiel):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hallo, dies ist ein Text\nDies ist ein weiterer Text."}' https://your-kchat-server.xyz/hooks/xxx-generierte-schlüssel-xxx

Wenn kein Content-Type-Header festgelegt ist, muss der Body der Anfrage mit payload= wie folgt vorangestellt werden:

payload={"text": "Hallo, dies ist ein Text\nDies ist ein weiterer Text."}

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 an die URL des Webhooks anhängen.

Parameter

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

Codebeispiel mit Parametern

So generieren Sie eine umfassendere Nachricht mit Parametern, von denen einige Parameter überschreiben können, die bereits beim Erstellen des Webhooks festgelegt wurden (Benutzername, bevorzugter Kanal, Avatar...), wie in der obigen Tabelle angegeben:

POST /hooks/xxx-generierte-schlüssel-xxx HTTP/1.1
Host: your-kchat-server.xyz
Content-Type: application/json
Content-Length: 630

{
  "channel": "kchatemp",
  "username": "test-automation",
  "icon_url": "https://domain.xyz/wp-content/uploads/2023/06/icon.png",
  "text": "#### Testergebnisse für den 27. Juli 2023\n@channel bitte überprüfen Sie die fehlgeschlagenen Tests.\n\n| Komponente  | Durchgeführte Tests   | Fehlgeschlagene Tests                                   |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Server     | 948         |  0                           |\n| Web-Client | 123         |  2 [(Details ansehen)](https://linktologs) |\n| iOS-Client | 78          |  3 [(Details ansehen)](https://linktologs) |"
}

kchatemp-Kanal der Organisation angezeigt wird: