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 notified immediately when a particular event occurs in another application, rather than constantly asking that application if something new has happened (known as "polling").
• It is not possible to import chat history from another application (Slack, Teams, Jabber, etc.) or from another organization.
• 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.

Accessing the kChat Webhooks Interface

Prerequisites

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

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

1. Open the kChat app (on your device or from a browser at the URL kchat.infomaniak.com).
2. Click on the chevron ‍ next to your kChat organization name.
3. Click on Integrations
   
    
4. Access the categories:
   

Integration Example

• Infomaniak Calendar Event Reminder on kChat

Create a Simple Incoming Webhook

To do this:

1. Click on the category Incoming Webhooks.
2. Click on 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 obtain the URL (do not disclose publicly) of type:
   https://your-kchat-server.xyz/hooks/xxx-generated-key-xxx

Using the Webhook

On the application that needs to post to kChat:

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

   POST /hooks/xxx-generated-key-xxx HTTP/1.1
   Host: your-kchat-server.xyz
   Content-Type: application/json
   Content-Length: 63
   
   {
       "text": "Hello, this is a text\nThis is another text."
   }

2. Optionally use the same request but in curl (to test from a Terminal on macOS, for example):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, this is a text\nThis is another text."}' https://your-kchat-server.xyz/hooks/xxx-generated-key-xxx

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

payload={"text": "Hello, this is a text\nThis is another text."}

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 receive 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 webhook URL.

Parameters

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

Code Example with Parameters

Here is how to generate a more complete message with parameters, some of which can override parameters already set during webhook creation (username, preferred channel, avatar...) as indicated in the table above:

POST /hooks/xxx-generated-key-xxx HTTP/1.1
Host: your-kchat-server.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": "#### Test Results for July 27, 2023\n@channel please check the failed tests.\n\n| Component  | Tests Completed   | Tests Failed                                   |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Server     | 948         |  0                           |\n| Web Client | 123         |  2 [(view details)](https://linktologs) |\n| iOS Client | 78          |  3 [(view details)](https://linktologs) |"
}

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