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

Preamble

• A webhook is a method that allows an application to be immediately informed when a particular event occurs in another application, rather than constantly asking this application if something new has happened ("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 chat history from another application (Slack, Teams, Jabber, etc.) or from another Organization.

⚠ Max. number of incoming/outgoing webhooks:

Access the kChat webhooks interface

Prerequisites

• Not being an external user (this user will not see the menu Integrations).

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

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

Specific guides

Integration examples on kChat:

• Calendar Infomaniak: display an event reminder on kChat
• application n8n: trigger sending a message on kChat

Guides for any other use

To create an incoming webhook (to display an external event on kChat):

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

Webhook usage

Quick example

1. A specific curl command (detailed below) is entered in a terminal.
2. The command contains the URL obtained in point 6 above.
3. The command will result in posting a message in the channel specified in point 4 above:
   

Details

On the application that needs to post on kChat:

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

   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. Optionally, use the same request but in curl (to test from a Terminal type application (command line interface, CLI / Command Line Interface) on your device) as in the image example above: 

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

If no Content-Type header is defined, the request body must be preceded by payload= as follows:

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

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.

Parameters

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 when creating the webhook (username, preferred channel, avatar...) as indicated in the table above:

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "https://cdn-icons-png.flaticon.com/512/5971/5971593.png",
  "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."
}' \
https://faq-infomaniakaruh.kchat.infomaniak.com/hooks/019c23e9-a9a8-735c-b6ce-0a69df63aaf0

Result of a similar example in image: