Conectar aplicaciones externas a kChat

Esta guía le permite gestionar aplicaciones externas con kChat con ayuda de webhook.

Preámbulo

Un webhook es un método que permite a una aplicación ser informada inmediatamente cuando un evento en particular ocurre en otra aplicación, en lugar de preguntar constantemente a esta aplicación si algo nuevo ha sucedido (lo que se llama "polling").
- Webhook saliente: kChat proporciona información a otras apps cuando un evento ocurre en kChat.
- Webhook entrante: kChat recibe información de otras apps para activar acciones en kChat.
No es posible importar el historial de las discusiones desde otra aplicación (Slack, Teams, Jabber, etc.) o desde otra organización.

Acceso a la interfaz webhooks kChat

Requisitos previos

No ser un usuario externo (este no verá el menú Integración).

Para configurar un webhook, encontrar aplicaciones y integraciones Auto-hospedaje o de terceros:

Haga clic aquí‍ para acceder a la aplicación Web kChat (servicio en línea) kchat.infomaniak.com) abrir la app desktop kChat (aplicación de escritorio en macOS / Windows / Linux).
Haga clic en el icono Nuevo ‍ al nombre de su organización kChat.
Haga clic en Integración.
Acceda a las categorías:

Ejemplo de integración

Recordatorio de evento de calendario Infomaniak en kChat

Crear una simple entrada webhook

Para ello:

Haga clic en la categoría Webhooks entrantes.
Haga clic en el botón azul Añadir webhooks entrantes:
Agregue un nombre y una descripción (500 caracteres como máximo) para el webhook.
Seleccione el canal que recibirá los mensajes
Guarde para obtener la URL (no divulgar públicamente) de tipo:
https://votre-serveur-kchat.xyz/hooks/xxx-clé-générée-xxx

Uso de la webhook

En la aplicación que debe publicar en kChat:

Ajuste el siguiente código en función de la URL obtenida:

POST /hooks/xxx-clé-générée-xxx HTTP/1.1
Host: votre-serveur-kchat.xyz
Content-Type: application/json
Content-Length: 63

{
    "text": "Bonjour, ceci est un texte
Ceci est un autre texte."
}

Posiblemente use la misma petición pero en curl (para probar desde un Terminal en macOS p.ex):
curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Bonjour, ceci est un texte Ceci est un autre texte."}' https://votre-serveur-kchat.xyz/hooks/xxx-clé-générée-xxx

Si no hay cabecera Content-Type no está definido, el cuerpo de la petición debe ir precedido de payload= Así:

payload={"text": "Bonjour, ceci est un texte Ceci est un autre texte."}

Una solicitud exitosa recibirá la respuesta siguiente:

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	
}

Si desea tener el mismo formato de respuesta que 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

debe agregar ?slack_return_format=true en la dirección URL de la webhook.

La indicación BOT se añade junto al nombre de usuario en kChat por razones de seguridad.

Parámetros

Además del campo text, aquí está la lista completa de los parámetros que se soportan:

...........................................................................................................................................................................................................................................................................................................................................................................................................	Descripción	Requerimientos
`text`	Mensaje en formato Markdown para mostrar en la publicación. Para activar notificaciones, utilizar `@<nom d'utilisateur>`, `@channel` y `@here` Como harías en otros mensajes de kChat.	Sí. `attachments` no está definido, sí
`channel`	Reemplaza el canal en el que se envía el mensaje. Usar el nombre del canal, no el nombre de la pantalla, utilizar p,ex `town-square`, no `Place de la Ville`. Usar "@" seguido de un nombre de usuario para enviar un mensaje directo. Por defecto, utiliza el canal definido al crear el webhook. El webhook puede publicar en cualquier canal público y privado donde esté presente el creador del webhook. Las publicaciones en los mensajes directos aparecerán en el mensaje directo entre el usuario destinatario y el creador del webhook.	No.
`username`	Reemplaza el nombre de usuario en el que se envía el mensaje. Por defecto, utiliza el nombre de usuario definido al crear el webhook; si no se ha definido ningún nombre de usuario durante la creación, utiliza `webhook`. El parámetro de configuración Permitir integraciones para reemplazar los nombres de usuario debe estar activado para que la sustitución del nombre de usuario tenga efecto.	No.
`icon_url`	Reemplaza la imagen de perfil con la que se publica el mensaje. Por defecto, utiliza la URL definida al crear el webhook; si no se ha definido ningún icono durante la creación, el icono de webhook estándar (‍) se muestra. El parámetro de configuración Permitir integraciones para reemplazar iconos de foto de perfil debe activarse para que la sustitución del icono tenga efecto.	No.
`icon_emoji`	Reemplaza la imagen de perfil y el parámetro `icon_url`. Por defecto, no se define nada al crear el webhook. El valor esperado es el nombre de un emoji tal como está escrito en un mensaje, con o sin dos puntos (`:`). El parámetro de configuración Permitir integraciones para reemplazar iconos de foto de perfil deberá activarse para que la sustitución surta efecto.	No.
`attachments`	Apéndices al mensaje utilizados para opciones de formato más ricas.	Sí. `text` no está definido, sí
`type`	Define el `type` de publicación, principalmente para su uso por plugins. Si no está vacío, debe empezar con "`custom_`".	No.

Ejemplo de código con parámetros

Aquí es cómo generar un mensaje más completo con parámetros, algunos que pueden reemplazar parámetros ya establecidos al crear el webhook (nombre de usuario, canal preferido, avatar...) como se muestra en la tabla anterior:

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

Esto llevará a la visualización de este mensaje en el canal kchatemp de la organización:

sign

Enlace a esta FAQ:

Ver todas las FAQ de este producto.