Collegare applicazioni esterne a kChat

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

Premessa

un webhook è un metodo che consente a un'applicazione di essere informata immediatamente quando si verifica un particolare evento in un'altra applicazione, anziché chiedere costantemente a quell'applicazione se è arrivata qualcosa di nuovo (quello che viene chiamato "polling")
non è possibile importare la cronologia delle discussioni da un'altra applicazione (Slack, Teams, Jabber, ecc.) o da un'altra organizzazione
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

Accedere all'interfaccia webhook di kChat

Requisiti

non essere un utente esterno (non vedrà il menu Integrazioni)

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

aprire l'app kChat (sul proprio dispositivo o tramite un browser all'URL kchat.infomaniak.com)
fare clic sulla freccia verso il basso ‍ a destra del nome della propria organizzazione kChat
fare clic su Integrazioni
accedere alle categorie:

Esempio di integrazione

Promemoria evento calendario Infomaniak su kChat

Creare un semplice webhook in entrata

Per fare ciò:

fare clic sulla categoria Webhook in entrata
fare clic sul pulsante blu Aggiungi webhook in entrata
aggiungere un nome e una descrizione (max 500 caratteri) per il webhook
selezionare il canale che riceverà i messaggi
salvare per ottenere l'URL (da non divulgare pubblicamente) di tipo:
https://il-tuo-server-kchat.xyz/hooks/xxx-chiave-generata-xxx

Utilizzo del webhook

Nell'app che deve pubblicare su kChat:

regolare il codice qui sotto in base all'URL ottenuto:

POST /hooks/xxx-chiave-generata-xxx HTTP/1.1
Host: il-tuo-server-kchat.xyz
Content-Type: application/json
Content-Length: 63

{
    "text": "Ciao, questo è un testo\nQuesto è un altro testo."
}

eventualmente utilizzare la stessa richiesta ma in curl (per testare da un Terminale su macOS, ad esempio):
curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Ciao, questo è un testo\nQuesto è un altro testo."}' https://il-tuo-server-kchat.xyz/hooks/xxx-chiave-generata-xxx

Se non è impostato alcun header Content-Type, il corpo della richiesta deve essere preceduto da payload= nel seguente modo:

payload={"text": "Ciao, questo è un testo\nQuesto è un altro testo."}

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 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 alla fine dell'URL del webhook.

La dicitura BOT viene aggiunta accanto al nome utente in kChat per motivi di sicurezza.

Parametri

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

Parametro	Descrizione	Obbligatorio
`text`	Messaggio in formato Markdown che verrà visualizzato nel post. Per attivare notifiche, usa `@<nome_utente>`, `@channel` e `@here` come faresti in altri messaggi di kChat.	Se non è definito `attachments`, sì
`channel`	Sostituisce il canale in cui verrà pubblicato il messaggio. Usa il nome del canale, non il nome visualizzato, ad es., `town-square`, non `Piazza della città`. Usa "@" seguito dal nome utente per inviare un messaggio diretto. Per impostazione predefinita, verrà utilizzato il canale impostato durante la creazione del webhook. Il webhook può pubblicare in qualsiasi canale pubblico e privato in cui il creatore del webhook è presente. Le pubblicazioni nei messaggi diretti appariranno nel messaggio diretto tra l'utente di destinazione e il creatore del webhook.	No
`username`	Sostituisce il nome utente sotto cui verrà pubblicato il messaggio. Per impostazione predefinita, utilizza il nome utente definito durante la creazione del webhook; se non è stato definito alcun nome utente, viene utilizzato `webhook`. Il parametro di configurazione Consenti integrazioni per sovrascrivere i nomi utente deve essere abilitato affinché la sovrascrittura del nome utente abbia effetto.	No
`icon_url`	Sostituisce l'immagine del profilo con cui viene pubblicato il messaggio. Per impostazione predefinita, utilizza l'URL definito durante la creazione del webhook; se non è stato definito alcun icon, verrà visualizzata l'icona standard di webhook (‍). Il parametro di configurazione Consenti integrazioni per sovrascrivere le icone dei profili deve essere abilitato affinché la sovrascrittura dell'icona abbia effetto.	No
`icon_emoji`	Sostituisce l'immagine del profilo e il parametro `icon_url`. Per impostazione predefinita, non viene definito nulla durante la creazione del webhook. Il valore atteso è il nome di un emoji, come viene digitato in un messaggio, con o senza i due punti (`:`). Il parametro di configurazione Consenti integrazioni per sovrascrivere le icone dei profili deve essere abilitato affinché la sovrascrittura sia efficace.	No
`attachments`	Allegati al messaggio che vengono utilizzati per opzioni di formattazione più ricche.	Se non è definito `text`, sì
`type`	Definisce il `type` della pubblicazione, principalmente per l'uso da parte dei plugin. Se non è vuoto, deve iniziare con "`custom_`".	No

Esempio di codice con parametri

Così puoi generare un messaggio più completo con parametri, alcuni dei quali possono sovrascrivere parametri già impostati durante la creazione del webhook (nome utente, canale preferito, avatar...), come indicato nella tabella precedente:

POST /hooks/xxx-chiave-generata-xxx HTTP/1.1
Host: il-tuo-server-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": "#### Risultati dei test per il 27 luglio 2023\n@channel per favore controlla i test falliti.\n\n| Componente  | Test eseguiti   | Test falliti                                   |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Server     | 948         |  0                           |\n| Client Web | 123         |  2 [(Vedi dettagli)](https://linktologs) |\n| Client iOS | 78          |  3 [(Vedi dettagli)](https://linktologs) |"
}

Questo porterà a visualizzare questo messaggio nel canale kchatemp dell'organizzazione:

sign

Link a questa FAQ:

Vedere tutte le FAQ di questo prodotto