Connect external applications to kChat

This guide allows you to manage external applications with kChat using 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").
  • 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 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, find self-hosted or third-party applications and integrations:

1. Click here to access the kChat Web app (online service) kchat.infomaniak.com) or open the kChat desktop app (desktop application on macOS / Windows / Linux).
2. Click on the New icon ‍ to the name of your organization kChat.
3. Click 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 incoming Webhooks category.
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); examplehttps://your-server-kchat.xyz/hooks/xxx-key-generated-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-key-generated-xxx HTTP/1.1
   Host: your-server-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   {
       "text": "Hello, text1
   Text2."
   }

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": "Hello, text1 Text2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

If no header Content-Type is defined, the body of the request must be preceded by payload= 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 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: