Deze handleiding helpt u bij het beheren van externe applicaties met kChat met behulp van webhooks.

Inleiding

• Een webhook is een methode waarmee een applicatie onmiddellijk op de hoogte wordt gesteld wanneer een bepaalde gebeurtenis in een andere applicatie plaatsvindt, in plaats van die applicatie voortdurend te vragen of er iets nieuws is gebeurd ("polling").
  • Uitgaande webhook: kChat stuurt informatie naar andere apps wanneer er een gebeurtenis in kChat plaatsvindt.
  • Inkomende webhook: kChat ontvangt informatie van andere apps om acties in kChat te activeren.
• Het is niet mogelijk om de gespreksgeschiedenis uit een andere applicatie (Slack, Teams, Jabber, enz.) of uit een andere organisatie te importeren.

⚠ Maximaal aantal inkomende/uitgaande webhooks:

Toegang krijgen tot de kChat-webhook-interface

Vereisten

• Geen externe gebruiker zijn (deze ziet het menu Integraties niet).

Om een webhook te configureren, zoekt u zelf gehoste of applicaties en integraties van derden:

1. Klik hier om de web-app kChat (online dienst ksuite.infomaniak.com/kchat) te openen, of open de desktop-app kChat (desktopapplicatie voor macOS / Windows / Linux).
2. Klik op het pictogram Nieuw ‍ naast de naam van uw kChat-organisatie.
3. Klik op Integraties:
   
4. Ga naar de categorieën:
   

Specifieke instructies

Voorbeelden van integraties in kChat:

• Agenda Infomaniak: Een herinnering voor een gebeurtenis in kChat weergeven
• Applicatie n8n: Een bericht in kChat verzenden

Instructies voor andere toepassingen

Om een inkomende webhook te maken (om een externe gebeurtenis in kChat weer te geven):

1. Klik op de categorie Inkomende webhooks.
2. Klik op de blauwe knop Inkomende webhook toevoegen:
   
3. Voeg een naam en een beschrijving toe voor de webhook.
4. Selecteer het kanaal dat de berichten ontvangt.
5. Klik op de knop Opslaan:
   
6. De URL die u moet opslaan voor uw ontwikkelingen wordt weergegeven (niet openbaar delen); voorbeeld: „https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx“:
   

Gebruik van de webhook

Snel voorbeeld

1. Een exacte curl-opdracht (hieronder in detail) wordt in een terminal ingevoerd.
2. De opdracht bevat de URL die in punt 6 hierboven is verkregen.
3. De opdracht zorgt ervoor dat er een bericht wordt geplaatst in het kanaal dat in punt 4 hierboven is aangegeven:
   

Details

In de applicatie die berichten naar kChat moet sturen:

1. Pas de volgende code aan op basis van de URL die u in kChat heeft ontvangen:

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

2. Gebruik indien nodig dezelfde aanvraag, maar dan in curl (om te testen vanuit een applicatie van het type Terminal (commandoregelinterface, CLI) op uw apparaat), zoals in het bovenstaande voorbeeld:
   

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

Als er geen header Content-Type is gedefinieerd, moet de aanvraagbody beginnen met payload=, zoals hieronder:

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

Een succesvolle aanvraag ontvangt de volgende reactie:

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	
}

Als u hetzelfde antwoordformaat als Slack wilt:

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

moet u ?slack_return_format=true toevoegen aan de webhook-URL.

Parameters

Naast het veld text vindt u hier de volledige lijst met ondersteunde parameters:

Codevoorbeeld met parameters

Zo kunt u een uitgebreider bericht met parameters maken, waarbij sommige parameters al parameters zijn die zijn ingesteld bij het maken van de webhook (gebruikersnaam, voorkeurskanaal, avatar, enz.), zoals aangegeven in de bovenstaande tabel:

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

Resultaat van een vergelijkbaar voorbeeld in de vorm van een afbeelding: