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

Introduzione

• Un webhook è un metodo che consente a un'applicazione di essere informata immediatamente quando si verifica un determinato evento in un'altra applicazione, anziché richiedere 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:
  • kSuite Free = 1 / 1
  • kSuite Standard = 20 / 20
  • kSuite Business = illimitato
  • kSuite Enterprise = illimitato

Accedere all'interfaccia web di kChat

Prerequisiti

• Non essere un utente esterno (quest'ultimo non vedrà il menu Integrazioni).

Per configurare un webhook, individua applicazioni e integrazioni self-hosted o di terze parti:

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

Guide specifiche

Esempi di integrazione su kChat:

• Calendario Infomaniak: visualizza un promemoria evento su kChat
• applicazione n8n: avviare l'invio di un messaggio su kChat

Guide per qualsiasi altro utilizzo

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. Aggiungere un nome e una descrizione per il webhook.
4. Seleziona il canale che riceverà i messaggi.
5. Fai clic sul pulsante per Salvare:
   
6. L'URL da utilizzare per i vostri sviluppi viene visualizzato (non divulgarlo pubblicamente); ad esempio “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Utilizzo del webhook

Esempio rapido

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

Dettagli

Nell'applicazione che deve pubblicare su kChat:

1. Modifica il codice qui sotto in base all'URL ottenuto 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. Se necessario, utilizza la stessa richiesta ma con curl (per effettuare dei test da un'applicazione di tipo Terminal (interfaccia a riga di comando, CLI /Command Line Interface) sul tuo dispositivo), come nell'esempio illustrato sopra:

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' {{URL_12}}

Se non è definito alcun header Content-Type, il corpo della richiesta deve essere preceduto da payload=, come segue:

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

Una richiesta riuscita restituirà 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 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

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

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "{{URL_13}}",
  "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."
}' \
{{URL_14}}

Risultato di un esempio simile, mostrato in un'immagine: