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.
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:
- 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).
- Click on the New icon ‍ next to the name of your kChat organization.
- Click on Integrations.
- Access the categories:
Example of integration
Create a simple incoming webhook
To do this:
- Click on the Incoming Webhooks category.
- Click on the blue button Add incoming webhooks:
- Add a name and a description (max 500 characters) for the webhook.
- Select the channel that will receive the messages
- 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:
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 with
curl
(to test from aTerminal
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:
Parameter | Description | Required |
---|---|---|
text | Message in Markdown format 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, for example “town-square”, not “Place de la ville”. Use "@" followed by a username to send a direct message. By default, uses the channel set during webhook creation. The webhook can post in any public or 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 | Replaces the username under which the message is posted. By default, uses the username set during webhook creation; if no username was set during creation, use webhook .The configuration parameter Allow integrations to replace usernames must be enabled for the username replacement to take effect. | No |
icon_url | Replaces the profile picture with which the message is posted. By default, uses the URL defined during webhook creation; if no icon was defined 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 | Replaces the profile picture and the parameter icon_url .By default, nothing is set upon 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 | Message attachments used for richer formatting options. | If text is not defined, yes |
type | Sets the type for publishing, mainly for use by plugins.If it is not empty, it must start with custom_ ". | No |
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: