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 un evento particolare si verifica in un'altra applicazione, piuttosto che chiedere costantemente a quest'ultima se è successo qualcosa di nuovo ("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.

⚠  Numero massimo di Webhook in entrata/uscita :

Accedere all'interfaccia webhook 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 ksuite.infomaniak.com/kchat) o apri l'app desktop kChat (applicazione di 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:
   

Guide specifici

Esempi di integrazione su kChat:

• Calendar Infomaniak: visualizzare un promemoria di un evento su kChat
• applicazione n8n: inviare un messaggio su kChat

Guide per qualsiasi altro uso

Per creare un webhook in entrata (per visualizzare un evento esterno su kChat):

1. Fare clic sulla categoria Webhook in entrata.
2. Fare clic sul pulsante blu Aggiungi webhook in entrata:
   
3. Aggiungi un nome e una descrizione per il webhook.
4. Seleziona il canale che riceverà i messaggi.
5. Fare clic sul pulsante per Salvare:
   
6. L'URL da conservare per i tuoi sviluppi viene visualizzata (non divulgare pubblicamente); esempio “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Utilizzo del webhook

Esempio rapido

1. Un comando curl specifico (dettagliato di seguito) viene inserito in un terminale.
2. Il comando contiene l'URL ottenuta al punto 6 sopra.
3. Il comando avrà come risultato la pubblicazione di un messaggio nel canale specificato al punto 4 sopra:
   

Dettagli

Nell'applicazione che deve pubblicare su kChat:

1. Aggiusta il codice qui sotto in base all'URL ottenuta su kChat:

   POST /hooks/xxx-key-generated-xxx HTTP/1.1
   Host: your-server-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   {
       "text": "Hello, text1\nText2."
   }

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) come nell'esempio di immagine sopra: 

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

Se nessun'intestazione Content-Type è definita, il corpo della richiesta deve essere preceduto da payload= come segue:

payload={"text": "Hello, text1\nText2."}

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 si desidera 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

è necessario 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 parametri, alcuni dei quali possono sostituire parametri già stabiliti durante la creazione del webhook (nome utente, canale preferito, avatar...) come indicato nella tabella sopra:

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "https://cdn-icons-png.flaticon.com/512/5971/5971593.png",
  "text": "### System Status Report\nEnvironment: PRODUCTION\nStatus: SUCCESSFUL\n\n---\n\n| Component | Version | Build ID | Status |\n|:----------|:-------:|:---------|:-------|\n| API-Core  | 2.4.1   | #88421   | OK     |\n| Web-UI    | 1.9.0   | #88425   | OK     |\n| Database  | 14.5    | N/A      | OK     |\n\n---\n\n**Commit Reference:**\n`git-ref: a7f8e9c21b` \n\n**Summary:**\nAll automated integration tests passed successfully. No manual intervention is required. Please contact the DevOps team for further details regarding this release."
}' \
https://faq-infomaniakaruh.kchat.infomaniak.com/hooks/019c23e9-a9a8-735c-b6ce-0a69df63aaf0

Risultato di un esempio simile in immagine: