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 to kChat.
Prerequisites
- not being an external user (they will not see the Integrations menu)
Accessing the Interface
To configure a webhook, find self-hosted or third-party applications and integrations:
- open the kChat app (on your device or from a browser at URL kchat.infomaniak.com)
- click on the chevron to the right of the name of your kChat organization
- click on Integrations
- access the 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 (500 char. max) for the webhook
- select the channel that will receive the messages
- save to get the URL (not to be publicly disclosed) of type:
https://your-kchat-server.xyz/hooks/xxx-generatedkey-xxx
Using the Webhook
On the application that needs to post to kChat:
- adjust the code below according to the obtained URL:
POST /hooks/xxx-generatedkey-xxx HTTP/1.1
Host: your-kchat-server.xyz
Content-Type: application/json
Content-Length: 63
{
"text": "Hello, this is some text\nThis is more 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 some text\nThis is more text."}' https://your-kchat-server.xyz/hooks/xxx-generatedkey-xxx
If no Content-Type header is set, the request body should be prefixed with payload= like this:
payload={"text": "Hello, this is some text\nThis is more text."}
A successful request will receive the following response:
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
Parameters
In addition to the text
field, here is the complete list of supported parameters:
Parameter | Description | Required |
---|---|---|
text | Message in Markdown format to be displayed 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., use town-square , not Town Square .Use "@" followed by a username to send a direct message. By default, uses the channel set during webhook creation. The webhook can post to 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, uses the username set during webhook creation; if no username was set during creation, uses webhook .The Allow integrations to replace usernames configuration setting must be enabled for username replacement to take effect. | No |
icon_url | Replaces the profile picture with which the message is posted. By default, uses the URL set during webhook creation; if no icon was set during creation, the standard webhook icon () is displayed. The Allow integrations to replace profile picture icons configuration setting must be enabled for icon replacement to take effect. | No |
icon_emoji | Replaces the profile picture and the icon_url parameter.By default, none is set during webhook creation. 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 setting must be enabled for replacement to take effect. | No |
attachments | Message attachments used for richer formatting options. | If text is not defined, yes |
type | Sets the post type , primarily for use by plugins.If not empty, must begin with " custom_ ". | No |
Example code with parameters
Here's how to generate a more complete message with parameters, some of which may override any parameters already established during webhook creation (username, preferred channel, avatar...) as indicated in the table above:
POST /hooks/xxx-generatedkey-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 27th, 2023\n@channel please review failed tests.\n\n| Component | Tests Run | 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 organization's kchatemp channel: