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

Introducción

• Un webhook es un método que permite a una aplicación recibir notificaciones inmediatas cuando se produce un evento específico en otra aplicación, en lugar de preguntar constantemente a esa aplicación si ha ocurrido algo nuevo ("polling").
  • Webhook saliente: kChat comunica información a otras aplicaciones cuando se produce un evento en kChat.
  • Webhook entrante: kChat recibe información de otras aplicaciones para activar acciones en kChat.
• No es posible importar el historial de las conversaciones desde otra aplicación (Slack, Teams, Jabber, etc.) o desde otra Organización.

⚠ Número máximo de webhooks entrantes/salientes:

Acceder a la interfaz de webhooks de kChat

Requisitos previos

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

Para configurar un webhook, busque aplicaciones e integraciones autoalojadas 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 para 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: activar 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 Añadir webhooks entrantes:
   
3. Añada 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 que debe conservar para sus desarrollos se muestra (no la divulgue públicamente); por ejemplo, “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”:
   

Uso del webhook

Ejemplo rápido

1. Se introduce 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 resultado del comando será 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 que se muestra 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": "Hola, texto1\nTexto2."
   }

2. Utilice, si es necesario, la misma solicitud, pero en curl (para probarla 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 la imagen anterior:

   curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hola, texto1\nTexto2."}' 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 correcta 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, aquí tiene la lista completa de los parámetros admitidos:

Ejemplo de código con parámetros

A continuación, se muestra cómo generar un mensaje más completo con parámetros, algunos de los cuales pueden reemplazar parámetros ya establecidos durante la creación del 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: