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").
  • 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.
• Il n'est pas possible d'importer l'historique des discussions depuis une autre application (Slack, Teams, Jabber, etc.) ou depuis une autre Organisation.

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:

1. Cliquez ici‍ afin d'accéder à l'app Web kChat (service en ligne kchat.infomaniak.com) ou ouvrez l'app desktop kChat (application de bureau sur macOS / Windows / Linux).
2. Cliquez sur l'icône Nouveau ‍ vers le nom de votre organisation kChat.
3. Cliquez sur Intégrations.
4. Accédez aux catégories :
   

Exemple d'intégration

• Rappel d'événement de calendrier Infomaniak sur kChat

Créer un simple webhook entrant

Pour cela :

1. Cliquez sur la catégorie Webhooks entrants.
2. Cliquez sur le bouton bleu Ajouter des webhooks entrants:
   
3. Ajoutez un nom et une description (max 500 caractères) pour le webhook.
4. Sélectionnez le canal qui recevra les messages
5. Enregistrez 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 :

1. Ajustez 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."
   }

2. Utilisez é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 :

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 :