Connettere applicazioni esterne a kChat

Questa guida ti permette di gestire applicazioni esterne con kChat utilizzando webhook.

Premessa

• Un webhook è un metodo che permette a un'applicazione di essere informata immediatamente quando si verifica un evento particolare in un'altra applicazione, piuttosto che chiedere costantemente a quest'ultima se è successo qualcosa di nuovo (cosa che si chiama "polling").
  • Webhook in uscita: kChat invia informazioni ad altre app quando si verifica un evento in kChat.
  • Webhook in entrata: kChat riceve informazioni da altre app per attivare azioni in kChat.
• Non è possibile importare la cronologia delle conversazioni da un'altra applicazione (Slack, Teams, Jabber, ecc.) o da un'altra Organizzazione.

Accedere all'interfaccia webhook di kChat

Prerequisiti

• Non essere un utente esterno (questo non vedrà il menu Integrazioni).

Per configurare un webhook, trovare applicazioni e integrazioni auto-hosted o di terze parti:

1. Clicca qui‍ per accedere all'app Web kChat (servizio online kchat.infomaniak.com) o apri l'app desktop kChat (applicazione desktop su macOS / Windows / Linux).
2. Clicca sull'icona Nuovo ‍ accanto al nome della tua organizzazione kChat.
3. Fai clic su Integrazioni.
4. Accedi alle categorie:
   

Esempio di integrazione

• Promemoria evento calendario Infomaniak su kChat

Creare un semplice webhook in entrata

Per fare questo:

1. Fai clic sulla categoria Webhook in entrata.
2. Fai clic sul pulsante blu Aggiungi webhook entranti:
   
3. Aggiungi un nome e una descrizione (max 500 caratteri) per il webhook.
4. Seleziona il canale che riceverà i messaggi
5. Salva per ottenere l'URL (da non divulgare pubblicamente); esempio “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”.

Utilizzo del webhook

Sull'applicazione che deve pubblicare su kChat:

1. Modifica il codice seguente in base all'URL ottenuta:

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

2. Utilizzare eventualmente la stessa richiesta ma in curl (per testare da un'applicazione di tipo Terminal (interfaccia a riga di comando, CLI /Command Line Interface) sul tuo dispositivo):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1 Text2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

Se non è specificato alcun header Tipo di contenuto non è definito, il corpo della richiesta deve essere preceduto da TRANSLATION_ERROR così:

payload={"text": "Hello, text1 Text2."}

Una richiesta riuscita riceverà la seguente risposta:

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	
}

Se desideri ottenere lo stesso formato di risposta di 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

devi aggiungere ?slack_return_format=true all'URL del webhook.

Parametri

Oltre al campo text, ecco l'elenco completo dei parametri supportati:

Esempio di codice con parametri

Ecco come generare un messaggio più completo con dei parametri, alcuni dei quali possono sostituire i parametri già stabiliti durante la creazione del webhook (nome utente, canale preferito, avatar...) come indicato nella tabella sopra:

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) |"
}

Questo farà apparire il messaggio nel canale kchatemp dell'organizzazione :