Conectar aplicaciones externas a kChat

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

Preámbulo

• un webhook es un método que permite a una aplicación ser informada inmediatamente cuando ocurre un evento particular en otra aplicación, en lugar de estar preguntando constantemente a esa aplicación si ha llegado algo nuevo (lo que se llama "polling")
• no es posible importar el historial de discusiones desde otra aplicación (Slack, Teams, Jabber, etc.) o desde otra organización
• webhook saliente: kChat comunica información a otras aplicaciones cuando ocurre un evento en kChat
• webhook entrante: kChat recibe información de otras aplicaciones para desencadenar acciones en kChat

Acceder a la interfaz de webhooks de kChat

Requisitos previos

• no ser un usuario externo (no verá el menú Integraciones)

Para configurar un webhook, encontrar aplicaciones e integraciones autoalojadas o de terceros:

1. abrir la aplicación kChat (en su dispositivo o desde un navegador en la URL kchat.infomaniak.com)
2. hacer clic en la flecha hacia abajo ‍ a la derecha del nombre de su organización en kChat
3. hacer clic en Integraciones
   
    
4. acceder a las categorías:
   

Ejemplo de integración

• Recordatorio de evento del calendario de Infomaniak en kChat

Crear un webhook entrante simple

Para ello:

1. hacer clic en la categoría Webhooks entrantes
2. hacer clic en el botón azul Agregar webhooks entrantes
   
3. agregar un nombre y una descripción (máx. 500 caracteres) para el webhook
4. seleccionar el canal que recibirá los mensajes
5. guardar para obtener la URL (no divulgar públicamente) de tipo:
   https://su-servidor-kchat.xyz/hooks/xxx-clave-generada-xxx

Uso del webhook

En la aplicación que debe publicar en kChat:

1. ajustar el código a continuación según la URL obtenida:

   POST /hooks/xxx-clave-generada-xxx HTTP/1.1
   Host: su-servidor-kchat.xyz
   Content-Type: application/json
   Content-Length: 63
   
   {
       "text": "Hola, este es un texto\nEste es otro texto."
   }

2. opcionalmente, puede usar la misma solicitud, pero en curl (para probar desde una Terminal en macOS, por ejemplo):
   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hola, este es un texto\nEste es otro texto."}' https://su-servidor-kchat.xyz/hooks/xxx-clave-generada-xxx

Si no se establece un encabezado Content-Type, el cuerpo de la solicitud debe precederse con payload= de la siguiente manera:

payload={"text": "Hola, este es un texto\nEste es otro texto."}

Una solicitud exitosa recibirá la siguiente respuesta:

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 deseas 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

debes agregar ?slack_return_format=true al final de la URL del webhook.

Parámetros

Además del campo text, aquí está la lista completa de parámetros admitidos:

Ejemplo de código con parámetros

Así es como puedes generar un mensaje más completo con parámetros, algunos de los cuales pueden sobrescribir parámetros que ya se han establecido al crear el webhook (nombre de usuario, canal preferido, avatar...), como se indica en la tabla anterior:

POST /hooks/xxx-clave-generada-xxx HTTP/1.1
Host: su-servidor-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": "#### Resultados de las pruebas para el 27 de julio de 2023\n@channel por favor revise las pruebas fallidas.\n\n| Componente  | Pruebas realizadas   | Pruebas fallidas                                   |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Servidor     | 948         |  0                           |\n| Cliente Web | 123         |  2 [(Ver detalles)](https://linktologs) |\n| Cliente iOS | 78          |  3 [(Ver detalles)](https://linktologs) |"
}

Esto dará lugar a que este mensaje se muestre en el canal kchatemp de la organización: