Connect external applications to kChat

This guide allows you to manage external applications with kChat using webhooks.

Introduction

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

Access the kChat webhooks interface

Prerequisites

• Not to be an external user (they will not see the menu Integrations).

To set up a webhook, find self-hosted or third-party applications and integrations:

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

Example of integration

• Infomaniak calendar event reminder on kChat

Create a simple incoming webhook

To do this:

1. Click on the Incoming Webhooks category.
2. Click on the blue button Add incoming webhooks:
   
3. Add a name and a description (max 500 characters) for the webhook.
4. Select the channel that will receive the messages
5. Save to get the URL (do not share it publicly); example “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”.

Using the webhook

On the application that needs to post on kChat:

1. Adjust the code below according to the URL obtained:

   POST /hooks/xxx-key-generated-xxx HTTP/1.1
   Host: your-server-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   {
       "text": "Hello, text1
   Text2."
   }

2. Optionally, use the same request but with curl (to test from a Terminal application (command line interface, CLI) on your device):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1 Text2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

If no Content-Type is not defined, the body of the request must be preceded by TRANSLATION_ERROR like this:

payload={"text": "Hello, text1 Text2."}

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 must add ?slack_return_format=true to the webhook URL.

Settings

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

Example code with parameters

Here is how to generate a more complete message with parameters, some of which can replace parameters already set during the creation of the webhook (username, 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 cause this message to be displayed in the channel kchatemp of the organization: