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

Premessa

• Un webhook è un metodo che permette a un'applicazione di essere informata immediatamente quando un evento particolare si verifica in un'altra applicazione, piuttosto che chiedere costantemente a quest'ultima se è successo qualcosa di nuovo (quello che viene chiamato "polling").
  • Webhook in uscita: kChat comunica 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 (quest'ultimo non vedrà il menu Integrazioni).

Per configurare un webhook, trovare applicazioni e integrazioni auto-ospitate 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. Clicca su Integrazioni.
4. Accedi alle categorie:
   

Esempio di integrazione

• Ricordo dell'evento di calendario Infomaniak su kChat

Creare un semplice webhook in ingresso

Per fare questo:

1. Fai clic sulla categoria Webhook in ingresso.
2. Fai clic sul pulsante blu Aggiungi webhook in ingresso:
   
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

Nell'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. Utilizza 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 nessuna intestazione Content-Type è definita, il corpo della richiesta deve essere preceduto da payload= come segue:

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 avere 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.

Impostazioni

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

Esempio di codice con parametri

Ecco come generare un messaggio più completo con parametri, alcuni dei quali possono sostituire 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) |"
}

Ciò comporterà la visualizzazione di questo messaggio nel canale kchatemp dell'organizzazione: