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 kan worden gesteld wanneer een bepaalde gebeurtenis plaatsvindt in een andere applicatie, in plaats van voortdurend te controleren of er iets nieuws is gebeurd ("polling").
  • Uitgaande webhook: kChat communiceert informatie naar andere apps wanneer een gebeurtenis plaatsvindt in kChat.
  • Inkomende webhook: kChat ontvangt informatie van andere apps om acties in kChat te activeren.
• Het is niet mogelijk om de gespreksgeschiedenis te importeren vanuit een andere applicatie (Slack, Teams, Jabber, enz.) of vanuit een andere organisatie.
• Maximaal aantal inkomende/uitgaande webhooks:
  • kSuite Free = 1 / 1
  • kSuite Standard = 20 / 20
  • kSuite Business = onbeperkt
  • kSuite Enterprise = onbeperkt

Toegang tot de kChat-webhooksinterface

Vereisten

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

Om een webhook te configureren, vindt u hier toepassingen en integraties die u zelf kunt hosten of die van derden zijn:

1. Klik hier om de web-app kChat te openen (online service ksuite.infomaniak.com/kchat) 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 handleidingen

Voorbeelden van integraties in kChat:

• Agenda van Infomaniak: een herinnering voor een evenement weergeven in kChat
• applicatie n8n: het verzenden van een bericht naar kChat activeren

Handleidingen voor ander gebruik

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 webhooks toevoegen:
   
3. Voeg een naam en een beschrijving toe voor de webhook.
4. Selecteer het kanaal dat de berichten zal ontvangen.
5. Klik op de knop om te opslaan:
   
6. De URL die u voor uw ontwikkelingen moet gebruiken, wordt weergegeven (deel deze niet openbaar); bijvoorbeeld “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Gebruik van de webhook

Snel voorbeeld

1. Een specifieke (gedetailleerde uitleg volgt hieronder) curl-opdracht wordt in een terminal ingevoerd.
2. Het commando bevat de URL die in stap 6 hierboven is verkregen.
3. Het resultaat van het commando is dat er een bericht wordt geplaatst in het kanaal dat in stap 4 hierboven is gespecificeerd:
   

Details

Over de applicatie die berichten naar kChat moet verzenden:

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

   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. Gebruik eventueel dezelfde query, maar dan met curl (om te testen vanuit een applicatie van het type Terminal (commandoregelinterface, CLI) op uw apparaat), zoals in het voorbeeld in de afbeelding hierboven:

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

Als er geen Content-Type-header is gedefinieerd, moet de hoofdtekst van het verzoek worden voorafgegaan door payload=, zoals hier:

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

Een succesvolle aanvraag levert de volgende reactie op:

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

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

Parameters

Naast het veld text, volgt hier de volledige lijst met ondersteunde parameters:

Voorbeeldcode met parameters

Hieronder ziet u hoe u een uitgebreidere melding kunt genereren met parameters, waarbij sommige parameters de parameters kunnen vervangen die al zijn ingesteld tijdens het aanmaken van de webhook (gebruikersnaam, voorkeurskanaal, avatar, enz.), zoals in de bovenstaande tabel wordt aangegeven:

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}}

Resultaat van een vergelijkbaar voorbeeld in de afbeelding: