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

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 (lo que se conoce como "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.

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, encontrar aplicaciones e integraciones autoalojadas o de terceros:

1. Haga clic aquí‍ para acceder a la aplicación web kChat (servicio en línea kchat.infomaniak.com) 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:
   

Ejemplo de integración

• Recordatorio de evento de calendario Infomaniak en kChat

Crear un webhook entrante simple

Para ello:

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 (máx. 500 caracteres) para el webhook.
4. Seleccione el canal que recibirá los mensajes
5. Guarde para obtener la URL (no divulgar públicamente); ejemplo “https://your-server-kchat.xyz/hooks/xxx-key-generated-xxx”.

Uso del webhook

En la aplicación que debe publicar en kChat:

1. Ajuste el código a continuación según 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. 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): 

   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 se define ningún encabezado Content-Type, el cuerpo de la solicitud debe preceder de payload= de la siguiente manera:

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

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, aquí está la lista completa de los parámetros soportados:

Ejemplo de código con parámetros

Aquí es 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:

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 provocará la visualización de este mensaje en el canal kchatemp de la organización: