1000 FAQs, 500 tutorials and explanatory videos. Here, there are only solutions!
Connect external applications to kChat
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 (known as "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.
Access the kChat webhooks interface
Prerequisites
- Not being an external user (they will not see the menu Integrations).
To configure a webhook, find self-hosted or third-party applications and integrations:
- Click here‍ to access the Web app kChat (online service kchat.infomaniak.com) or open the desktop app kChat (desktop application on macOS / Windows / Linux).
- Click on the New icon ‍ next to your kChat organization name.
- Click on Integrations.
- Access the categories:
Integration example
Create a simple incoming webhook
To do this:
- Click on the Incoming Webhooks category.
- Click the blue Add Incoming Webhooks button:
- Add a name and description (max 500 characters) for the webhook.
- Select the channel that will receive the messages
- Save to get the URL (do not disclose publicly); example “
https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx
”.
Using the webhook
On the application that needs to post to kChat:
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." }
Optionally, use the same request but in
curl
(to test from aTerminal
type application (command line interface,CLI / Command Line Interface
) 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
header is set, the request body must be preceded by payload=
as follows:
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 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.
The BOT indicator is added next to the username on kChat for security reasons.
Settings
In addition to the text
field, here is the complete list of supported parameters:
Parameter | Description | Required |
---|---|---|
text | Markdown-formatted message to display in the post. To trigger notifications, use “@<username>”, “@channel” and “@here” as you would in other kChat messages. | If attachments is not defined, yes |
channel | Replaces the channel in which the message is posted. Use the channel name, not the display name, e.g. “town-square”, not “Town Square”. Use “@” followed by a username to send a direct message. By default, uses the channel set when the webhook was created. The webhook can post in any public and private channel where the webhook creator is present. Posts in direct messages will appear in the direct message between the targeted user and the webhook creator. | No |
username | Replace the username under which the message is posted. By default, use the username set during webhook creation; if no username was set during creation, use webhook . | No |
icon_url | Replace the profile picture with which the message is posted. By default, use the URL set during webhook creation; if no icon was set during creation, the standard webhook icon (‍) is displayed. The configuration parameter Allow integrations to replace profile picture icons must be enabled for the icon replacement to take effect. | No |
icon_emoji | Replace the profile picture and the parameter icon_url .By default, nothing is set during webhook creation. The expected value is the name of an emoji as it is typed in a message, with or without colons ( : ).The configuration parameter Allow integrations to replace profile picture icons must be enabled for the replacement to take effect. | No |
attachments | Attachments used in the message for richer formatting options. | If text is not defined, yes |
type | Defines the type publication date, mainly for use by plugins.If it is not empty, it must start with custom_ ". | No |
Code example 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:
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 kchatemp channel of the organization: