Conectar aplicaciones externas a kChat

Esta guía le permite gestionar aplicaciones externas con kChat con la 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 aplicaciones 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 e integraciones auto-alojadas o de terceros:

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

Ejemplo de integración

• Recordatorio de evento de calendario Infomaniak en kChat

Crear una simple entrada webhook

Para ello:

1. Haga clic en la categoría Webhooks entrantes.
2. Haga clic en el botón azul Añadir webhooks entrantes:
   
3. Agregue un nombre y una descripción (500 caracteres como máximo) para el webhook.
4. Seleccione el canal que recibirá los mensajes
5. Guarde para obtener la dirección URL (no se divulgará públicamente); ejemplo:https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”.

Uso de la webhook

En la aplicación que debe publicar en kChat:

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

   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. 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": "Hello, text1 Text2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

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

payload={"text": "Hello, text1 Text2."}

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.

Parámetros

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

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: