Connect external applications to kChat

This guide allows you to manage external applications with kChat with the help of webhook.

Preamble

• A webhook is a method that allows an application to be informed immediately when a particular event occurs in another application, rather than constantly asking this application if something new has happened (what is called "polling").
  • Outbound Webhook: kChat communicates information to other apps when an event occurs in kChat.
  • Incoming Webhook: kChat receives information from other apps to trigger actions in kChat.
• It is not possible to import the history of the discussions from another application (Slack, Teams, Jabber, etc.) or from another Organization.

Access the webhooks kChat interface

Prerequisites

• Don't be an external user (this one won't see the menu Integrations).

To configure a webhook, to find applications and integrations Self-hospitalized or third parties:

1. Click here‍ to access the app Web kChat (online service) kchat.infomaniak.com) or open the app desktop kChat (desktop application on macOS / Windows / Linux).
2. Click on the icon New ‍ to the name of your organization kChat.
3. Click on Integrations.
4. Access the categories:
   

Example of integration

• Infomaniak Calendar Event Reminder on kChat

Create a simple incoming webhook

To this end:

1. Click on the category Incoming Webhooks.
2. Click the blue button Add incoming webhooks:
   
3. Add a name and description (max 500 characters) for the webhook.
4. Select the channel that will receive the messages
5. Save to get the URL (not to be publicly disclosed) of type:
   https://votre-serveur-kchat.xyz/hooks/xxx-clé-générée-xxx

Using the webhook

On the application that must post on kChat:

1. Adjust the code below based on the URL obtained:

   POST /hooks/xxx-clé-générée-xxx HTTP/1.1
   Host: votre-serveur-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   
   {
       "text": "Bonjour, ceci est un texte
   Ceci est un autre texte."
   }

2. Use the same query, but in curl (to test from a Terminal on macOS e.g.):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Bonjour, ceci est un texte Ceci est un autre texte."}' https://votre-serveur-kchat.xyz/hooks/xxx-clé-générée-xxx

If no header Content-Type is defined, the body of the request must be preceded by payload= Like this:

payload={"text": "Bonjour, ceci est un texte Ceci est un autre texte."}

A successful request will receive the following response:

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	
}

If you want to have the same response format as Slack:

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

you need to add ?slack_return_format=true to the URL of the webhook.

Parameters

In addition to the field text, here is the complete list of supported parameters:

Example code with parameters

Here's how to generate a more complete message with parameters, some of which can replace parameters already established when creating the webhook (user name, preferred channel, avatar...) as indicated in the table above:

POST /hooks/xxx-clé-générée-xxx HTTP/1.1
Host: votre-serveur-kchat.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": "#### Résultats des tests pour le 27 juillet 2023
@channel veuillez vérifier les tests échoués.

| Composant  | Tests effectués   | Tests échoués                                   |
|:-----------|:-----------:|:-----------------------------------------------|
| Serveur     | 948         |  0                           |
| Client Web | 123         |  2 [(voir détails)](https://linktologs) |
| Client iOS | 78          |  3 [(voir détails)](https://linktologs) |"
}

This will result in the display of this message in the channel kchatemp of the organization: