1000 FAQs, 500 tutorials and explanatory videos. Here, there are only solutions!
Connect external apps to kChat
This guide allows you to access the management of external applications for kChat.
Prerequisites
- not be an external user (this user won't see the Integrations menu)
Accessing the Interface
To configure a webhook, find applications and self-hosted or third-party integrations:
- open the kChat application (on your device or from a browser at URL kchat.infomaniak.com)
- click on the chevron to the right of your kChat organization name
- click on Integrations
- access categories:
Integration Example
Create a Simple Incoming Webhook
For 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 messages
- save to get 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 on kChat:
- 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."
} - 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 request body 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 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.
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 set, yes |
channel | Replaces the channel in which the message is posted. Use the channel name, not the display name, use for example town-square , not Place de la Ville .Use "@" followed by a username to send a direct message. By default, use 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 | Replaces the username under which the message is posted. By default, use the username set when the webhook was created; if no username was set when created, use webhook .The Allow integrations to replace usernames configuration parameter 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, use the URL set when the webhook was created; if no icon was set when created, the standard webhook icon () is displayed. The Allow integrations to replace profile picture icons configuration parameter must be enabled for the icon replacement to take effect. | No |
icon_emoji | Replaces the profile picture and the icon_url parameter.By default, nothing is set when the webhook is created. The expected value is the name of an emoji as typed in a message, with or without colons ( : ).The Allow integrations to replace profile picture icons configuration parameter must be enabled for the replacement to take effect. | No |
attachments | Message attachments used for richer formatting options. | If text is not set, yes |
type | Sets the publication type , mainly for use by plugins.If not empty, must start with " custom_ ". | No |
Code Example with Parameters
Here's how to generate a more complete message with parameters, some of which can replace established parameters when the webhook was created (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 failed tests.\n\n| Component | Tests Conducted | Tests Failed |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Server | 948 | 0 |\n| Web Client | 123 | 2 [(see details)](https://linktologs) |\n| iOS Client | 78 | 3 [(see details)](https://linktologs) |"
}
This will result in displaying this message in the kchatemp channel of the organization: