1 000 FAQ, 500 tutoriels et vidéos explicatives. Ici, il n'y a que des solutions !
Connecter des applications externes Ă kChat
Ce guide vous permet de gérer des applications externes avec kChat à l'aide de webhook.
Préambule
- un webhook est une méthode permettant à une application d'être informée immédiatement lorsqu'un événement particulier se produit dans une autre application, plutôt que de demander constamment à cette application si quelque chose de nouveau est arrivé (ce qu'on appelle "polling")
- il n'est pas possible d'importer l'historique des discussions depuis une autre application (Slack, Teams, Jabber, etc.) ou depuis une autre Organisation
- webhook sortant: kChat communique des informations à d'autres apps lorsqu'un événement se produit dans kChat
- webhook entrant: kChat reçoit des informations d'autres apps pour déclencher des actions dans kChat
Accéder à l'interface webhooks kChat
Prérequis
- ne pas être un utilisateur externe (celui-ci ne verra pas le menu Intégrations)
Pour configurer un webhook, trouver des applications et intégrations auto-hébergées ou tierces:
- ouvrir l'application kChat (sur votre appareil ou depuis un navigateur Ă l'URL kchat.infomaniak.com)
- cliquer sur le bouton ‍ à droite du nom de votre Organisation kChat
- cliquer sur Intégrations
- accéder aux catégories :
Exemple d'intégration
Créer un simple webhook entrant
Pour cela :
- cliquer sur la catégorie Webhooks entrants
- cliquer sur le bouton bleu Ajouter des webhooks entrants
- ajouter un nom et une description (max 500 caractères) pour le webhook
- sélectionner le canal qui recevra les messages
- enregistrer pour obtenir l'URL (Ă ne pas divulguer publiquement) de type :
https://votre-serveur-kchat.xyz/hooks/xxx-clé-générée-xxx
Utilisation du webhook
Sur l'application qui doit poster sur kChat :
ajuster le code ci-dessous en fonction de l'URL obtenue :
POST /hooks/xxx-clé-générée-xxx HTTP/1.1 Host: votre-serveur-kchat.xyz Content-Type: application/json Content-Length: 63 { "text": "Bonjour, ceci est un texte\nCeci est un autre texte." }
- utiliser Ă©ventuellement la mĂŞme requĂŞte mais en curl (pour tester depuis un Terminal sur macOS p.ex) :
curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Bonjour, ceci est un texte\nCeci est un autre texte."}' https://votre-serveur-kchat.xyz/hooks/xxx-clé-générée-xxx
Si aucun en-tête Content-Type n'est défini, le corps de la requête doit être précédé de payload= comme ceci :
payload={"text": "Bonjour, ceci est un texte\nCeci est un autre texte."}
Une requête réussie recevra la réponse suivante :
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
}
Si vous souhaitez avoir le même format de réponse que 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
vous devez ajouter ?slack_return_format=true
à l’URL du webhook.
Paramètres
En plus du champ text
, voici la liste complète des paramètres supportés :
Paramètre | Description | Requis |
---|---|---|
text | Message au format Markdown à afficher dans la publication. Pour déclencher des notifications, utiliser @<nom d'utilisateur> , @channel et @here comme vous le feriez dans d'autres messages kChat. | Si attachments n'est pas défini, oui |
channel | Remplace le canal dans lequel le message est posté. Utiliser le nom du canal, pas le nom d'affichage, utiliser p,ex town-square , pas Place de la Ville .Utiliser "@" suivi d'un nom d'utilisateur pour envoyer un message direct. Par défaut, utilise le canal défini lors de la création du webhook. Le webhook peut poster dans n'importe quel canal public et privé où le créateur du webhook est présent. Les publications dans les messages directs apparaîtront dans le message direct entre l'utilisateur ciblé et le créateur du webhook. | Non |
username | Remplace le nom d'utilisateur sous lequel le message est posté. Par défaut, utilise le nom d'utilisateur défini lors de la création du webhook ; si aucun nom d'utilisateur n'a été défini lors de la création, utilise webhook .Le paramètre de configuration Autoriser les intégrations à remplacer les noms d'utilisateur doit être activé pour que le remplacement du nom d'utilisateur prenne effet. | Non |
icon_url | Remplace l'image de profil avec laquelle le message est posté. Par défaut, utilise l'URL définie lors de la création du webhook ; si aucune icône n'a été définie lors de la création, l'icône de webhook standard (‍) est affichée. Le paramètre de configuration Autoriser les intégrations à remplacer les icônes de photo de profil doit être activé pour que le remplacement de l'icône prenne effet. | Non |
icon_emoji | Remplace l'image de profil et le paramètre icon_url .Par défaut, rien n'est défini lors de la création du webhook. La valeur attendue est le nom d'un emoji tel qu'il est tapé dans un message, avec ou sans deux-points ( : ).Le paramètre de configuration Autoriser les intégrations à remplacer les icônes de photo de profil doit être activé pour que le remplacement prenne effet. | Non |
attachments | Pièces jointes au message utilisées pour des options de mise en forme plus riches. | Si text n'est pas défini, oui |
type | DĂ©finit le type de publication, principalement pour une utilisation par des plugins.S'il n'est pas vide, doit commencer par " custom_ ". | Non |
Exemple de code avec paramètres
Voici comment générer un message plus complet avec des paramètres, certains pouvant remplacer des paramètres déjà établis lors de la création du webhook (nom d'utilisateur, canal préféré, avatar...) comme indiqué dans le tableau ci-dessus :
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\n@channel veuillez vérifier les tests échoués.\n\n| Composant | Tests effectués | Tests échoués |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Serveur | 948 | 0 |\n| Client Web | 123 | 2 [(voir détails)](https://linktologs) |\n| Client iOS | 78 | 3 [(voir détails)](https://linktologs) |"
}
Cela entraînera l'affichage de ce message dans le canal kchatemp de l'organisation :