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

Prólogo

• 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 preguntar constantemente a esta aplicación si ha ocurrido algo nuevo ("polling").
  • 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.
• No es posible importar el historial de conversaciones desde otra aplicación (Slack, Teams, Jabber, etc.) o desde otra Organización.

⚠ Número máximo de Webhook entrante/saliente:

Acceder a la interfaz webhooks kChat

Requisitos previos

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

Para configurar un webhook, encontrar aplicaciones e integraciones auto-hospedadas o de terceros:

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

Guías específicas

Ejemplos de integración en kChat:

• Calendar Infomaniak: mostrar un recordatorio de evento en kChat
• aplicación n8n: disparar el envío de un mensaje en kChat

Guías para cualquier otro uso

Para crear un webhook entrante (para mostrar un evento externo en kChat):

1. Haga clic en la categoría Webhooks entrantes.
2. Haga clic en el botón azul Agregar webhooks entrantes:
   
3. Agregue un nombre y una descripción para el webhook.
4. Seleccione el canal que recibirá los mensajes.
5. Haga clic en el botón para Guardar:
   
6. La URL a conservar para sus desarrollos se muestra (no divulgar públicamente); ejemplo “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Uso del webhook

Ejemplo rápido

1. Se ingresa un comando curl específico (detallado más abajo) en un terminal.
2. El comando contiene la URL obtenida en el punto 6 anterior.
3. El comando tendrá como resultado publicar un mensaje en el canal especificado en el punto 4 anterior:
   

Detalles

En la aplicación que debe publicar en kChat:

1. Ajuste el código a continuación según la URL obtenida en 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. Utilice eventualmente la misma solicitud pero en curl (para probar desde una aplicación de tipo Terminal (interfaz de línea de comandos, CLI /Command Line Interface) en su dispositivo) como en el ejemplo de imagen anterior: 

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, text1\nText2."}' https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx

Si no se define ninguna cabecera Content-Type, el cuerpo de la solicitud debe ir precedido de payload= de la siguiente manera:

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

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 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 a la URL del webhook.

Parámetros

Además del campo text, a continuación se muestra la lista completa de los parámetros admitidos:

Ejemplo de código con parámetros

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

curl -i -X POST -H 'Content-Type: application/json' \
-d '{
"username": "System Monitor",
  "icon_url": "https://cdn-icons-png.flaticon.com/512/5971/5971593.png",
  "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."
}' \
https://faq-infomaniakaruh.kchat.infomaniak.com/hooks/019c23e9-a9a8-735c-b6ce-0a69df63aaf0

Resultado de un ejemplo similar en imagen: